Package net.shibboleth.idp.installer.plugin.impl

# Class PluginInstaller

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.idp.installer.plugin.impl.PluginInstaller

All Implemented Interfaces:
  `AutoCloseable`, `Component`, `DestructableComponent`, `InitializableComponent`

public final class PluginInstaller extends AbstractInitializableComponent implements AutoCloseable
The class where the heavy lifting of managing a plugin happens.

## Field Summary

Fields
Modifier and Type
Field
Description
`private Predicate<String>`
`acceptKey`
The callback before we install a key into the TrustStore.
`private IdPPlugin`
`description`
The plugin's story about itself.
`private Path`
`distPath`
DistDir.
`private Path`
`distribution`
The actual distribution.
`private Path`
`downloadDirectory`
Where we have downloaded.
`private final org.apache.hc.client5.http.classic.HttpClient`
`httpClient`
What to use to download things.
`private Path`
`idpHome`
Where we are installing to.
`private List<Path>`
`installedContents`
The absolute paths of what was installed - this is setup by `loadCopiedFiles()`.
`private URLClassLoader`
`installedPluginsLoader`
The "plugins" classpath loader.
`private String`
`installedVersionFromContents`
The version from the contents file, or null if it isn't loaded.
`private URLClassLoader`
`installingPluginLoader`
The "plugin under construction" classpath loader.
`private static final org.slf4j.Logger`
`LOG`
Class logger.
`private final Map<Module.ModuleResource,Module.ResourceResult>`
`moduleChanges`
Module Changes.
`private ModuleContext`
`moduleContext`
The Module Context.
`private static final String`
`PLUGIN_FILE_PROPERTY_PREFIX`
Property Prefix for install files .
`private static final String`
`PLUGIN_RELATIVE_PATHS_PROPERTY`
Property Name for whether paths are relative.
`private static final String`
`PLUGIN_VERSION_PROPERTY`
Property Name for version.
`private String`
`pluginId`
What we are dealing with.
`private Path`
`pluginsContents`
Plugins webapp.
`private Path`
`pluginsWebapp`
Pluginss webapp.
`private boolean`
`rebuildWar`
Do we rebuild?
`private Set<String>`
`reenabledPluginModules`
The names of those plugin modules enabled by rule.
`private HttpClientSecurityParameters`
`securityParams`
The securityParams for the module context.
`private String`
`truststore`
Where to get the keys from if not defaulted.
`private Path`
`unpackDirectory`
Where we have unpacked into.
`private List<URL>`
`updateOverrideURLs`
If overridden these are the urls to us for update (rather than what the plugin asks for.
`private Path`
`workspacePath`
Dumping space for renamed files.

## Constructor Summary

Constructors
Constructor
Description
`PluginInstaller(org.apache.hc.client5.http.classic.HttpClient client)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`private void`
`captureChanges(Map<Module.ModuleResource,Module.ResourceResult> changes)`
Capture module changes.
`private void`
`checkRequiredModules(Set<String> loadedModules)`
Police that required modules for plugin installation are enabled.
`private void`
`checkSignature(Path base, String fileName)`
Check the signature of the plugin.
`void`
`close()`
`private void`
`closeSilently(AutoCloseable what)`
close, ignoring errors.
`protected void`
`doInitialize()`
`private void`
`doReportOperation(Module.ModuleResource resource, Module.ResourceResult result)`
Report on a resource result.
`private void`
`download(URL baseURL, String fileName)`
Method to download a zip file to the {`downloadDirectory`.
`private void`
`emitModuleChanges()`
Emit module changes.
`private IdPPlugin`
`getDescription()`
Check for non null and then if so return the `description`.
`private URLClassLoader`
`getDistributionLoader()`
Generate a `URLClassLoader` which looks at the installing WEB-INF.
`private Path`
`getIdpHome()`
Get a null safe idpHome.
`protected static InstallableComponentVersion`
`getIdPVersion()`
Return a version we can use in a test proof manner.
`List<Path>`
`getInstalledContents()`
What files were installed to webapp for this plugin?
`IdPPlugin`
`getInstalledPlugin(String name)`
Find the `IdPPlugin` with the provided Id.
`List<IdPPlugin>`
`getInstalledPlugins()`
Return a list of the installed plugins.
`private URLClassLoader`
`getInstalledPluginsLoader()`
Generate a `URLClassLoader` which looks at the installed WEB-INF/lib in addition to the dist webapp and bin/lib directories.
`Set<String>`
`getLoadedModules()`
What modules (on the installed plugins Classpath) are currently loaded?
`private ModuleContext`
`getModuleContext()`
Check for initialized and if so return the `moduleContext`.
`private Pair<String,String>`
`getModulePluginInfo(String moduleId)`
If we have the information, get the Plugin Id and version which supplies the module id.
`private Path`
`getPluginsWebapp()`
Check for initialized and if so return the `pluginsWebapp`.
`private static org.apache.commons.compress.archivers.ArchiveInputStream<?>`
`getStreamFor(Path fullName, boolean isZip)`
Create the correct `ArchiveInputStream` for the input.
`String`
`getVersionFromContents()`
return the version that the contents page thinks is installed.
`private void`
`handlePackages(RollbackPluginInstall rollback)`
Deploy any required packages.
`private Path`
`inferInstalledIdpHome(Properties props)`
Infer where the properties were installed to.
`private void`
`installNew(RollbackPluginInstall rollBack)`
Copy the webapp folder from the distribution to the per plugin location inside dist.
`void`
`installPlugin(URL baseURL, String fileName, boolean checkVersion)`
Install the plugin from the provided URL.
`void`
`installPlugin(Path base, String fileName, boolean checkVersion)`
Install the plugin from a local path.
`boolean`
`isRebuildWar()`
Do we rebuild the war?
`private static boolean`
`isZip(String fileName)`
does the file name end in .zip?
`private void`
`loadCopiedFiles()`
Load the contents for this plugin from the properties file used during installation.
`private void`
`reEnableModules(Set<String> loadedModules)`
Re-enabled the listed modules iff then are implemented by the plugin we just installed.
`private void`
`saveCopiedFiles(List<Path> copiedFiles)`
Stream the copy list to a property file and empty it.
`void`
`setAcceptKey(Predicate<String> what)`
Set the acceptKey predicate.
`void`
`setIdpHome(Path home)`
Set IdP Home.
`void`
`setModuleContextSecurityParams(HttpClientSecurityParameters params)`
Set the Module Context security parameters.
`void`
`setPluginId(String id)`
Set the plugin id.
`void`
`setRebuildWar(boolean what)`
Set whether we rebuild the war.
`void`
`setTrustore(String loc)`
Set the truststore.
`void`
`setUpdateOverrideURLs(List<URL> urls)`
Set the override URLS.
`private void`
`setupDescriptionFromDistribution()`
Get hold of the `IdPPlugin` for this plugin.
`private void`
`setupPluginId()`
Look into the distribution and suck out the plugin id.
`void`
`uninstall()`
Remove the jars for this plugin and rebuild the war.
`private void`
`uninstallOld(RollbackPluginInstall rollback)`
Uninstall the old version of the plugin.
`private void`
`unpack(Path base, String fileName)`
Helper Method for unpacking the distribution.
`private static void`
`unpack(Path unpackTo, Path fullName, boolean isZip, boolean stripFirst)`
Method to unpack a zip or tgz file into our {`unpackDirectory`.

### Methods inherited from class net.shibboleth.shared.component.AbstractInitializableComponent

`checkComponentActive, checkSetterPreconditions, destroy, doDestroy, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException, initialize, isDestroyed, isInitialized`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### LOG

@Nonnull private static final org.slf4j.Logger LOG
Class logger.

### PLUGIN_VERSION_PROPERTY

@Nonnull @NotEmpty private static final String PLUGIN_VERSION_PROPERTY
Property Name for version.

See Also:
  - Constant Field Values

### PLUGIN_FILE_PROPERTY_PREFIX

@Nonnull @NotEmpty private static final String PLUGIN_FILE_PROPERTY_PREFIX
Property Prefix for install files .

See Also:
  - Constant Field Values

### PLUGIN_RELATIVE_PATHS_PROPERTY

@Nonnull @NotEmpty private static final String PLUGIN_RELATIVE_PATHS_PROPERTY
Property Name for whether paths are relative.

See Also:
  - Constant Field Values

### idpHome

@NonnullAfterInit private Path idpHome
Where we are installing to.

### pluginId

private String pluginId
What we are dealing with.

### unpackDirectory

private Path unpackDirectory
Where we have unpacked into.

### downloadDirectory

private Path downloadDirectory
Where we have downloaded.

### description

private IdPPlugin description
The plugin's story about itself.

### acceptKey

@Nonnull private Predicate<String> acceptKey
The callback before we install a key into the TrustStore.

### distribution

private Path distribution
The actual distribution.

### truststore

private String truststore
Where to get the keys from if not defaulted.

### httpClient

@Nonnull private final org.apache.hc.client5.http.classic.HttpClient httpClient
What to use to download things.

### updateOverrideURLs

@Nonnull private List<URL> updateOverrideURLs
If overridden these are the urls to us for update (rather than what the plugin asks for.

### workspacePath

@NonnullAfterInit private Path workspacePath
Dumping space for renamed files.

### distPath

@NonnullAfterInit private Path distPath
DistDir.

### pluginsWebapp

@NonnullAfterInit private Path pluginsWebapp
Pluginss webapp.

### pluginsContents

@NonnullAfterInit private Path pluginsContents
Plugins webapp.

### installedContents

@Nullable private List<Path> installedContents
The absolute paths of what was installed - this is setup by `loadCopiedFiles()`.

### installedVersionFromContents

@Nullable private String installedVersionFromContents
The version from the contents file, or null if it isn't loaded.

### moduleContext

@NonnullAfterInit private ModuleContext moduleContext
The Module Context.

### reenabledPluginModules

@Nonnull private Set<String> reenabledPluginModules
The names of those plugin modules enabled by rule.

### moduleChanges

@Nonnull private final Map<Module.ModuleResource,Module.ResourceResult> moduleChanges
Module Changes.

### installedPluginsLoader

@Nullable private URLClassLoader installedPluginsLoader
The "plugins" classpath loader. AutoClosed.

### installingPluginLoader

@Nullable private URLClassLoader installingPluginLoader
The "plugin under construction" classpath loader. AutoClosed.

### securityParams

@Nullable private HttpClientSecurityParameters securityParams
The securityParams for the module context.

### rebuildWar

private boolean rebuildWar
Do we rebuild?

## Constructor Details

### PluginInstaller

public PluginInstaller(@Nonnull org.apache.hc.client5.http.classic.HttpClient client)
Constructor.

Parameters:
  `client` - - the HttpClient to use

## Method Details

### setIdpHome

public void setIdpHome(@Nonnull Path home)
Set IdP Home.

Parameters:
  `home` - Where we are working from

### getIdpHome

@Nonnull private Path getIdpHome()
Get a null safe idpHome.

Returns:
  idpHome

### setPluginId

public void setPluginId(@Nonnull @NotEmpty String id)
Set the plugin id.

Parameters:
  `id` - what to set.

### setTrustore

public void setTrustore(@Nullable String loc)
Set the truststore.

Parameters:
  `loc` - what set.

### setAcceptKey

public void setAcceptKey(@Nonnull Predicate<String> what)
Set the acceptKey predicate.

Parameters:
  `what` - what to set.

### setUpdateOverrideURLs

public void setUpdateOverrideURLs(@Nonnull List<URL> urls)
Set the override URLS.

Parameters:
  `urls` - The updateOverrideURLs to set.

### setModuleContextSecurityParams

public void setModuleContextSecurityParams(@Nullable HttpClientSecurityParameters params)
Set the Module Context security parameters.

Parameters:
  `params` - what to set.

### setRebuildWar

public void setRebuildWar(boolean what)
Set whether we rebuild the war.

Parameters:
  `what` - - whether we will or not

### isRebuildWar

public boolean isRebuildWar()
Do we rebuild the war?

Returns:
  true if we are going to.

### installPlugin

public void installPlugin(@Nonnull URL baseURL, @Nonnull @NotEmpty String fileName, boolean checkVersion) throws org.apache.tools.ant.BuildException
Install the plugin from the provided URL. Involves downloading the file and then doing a `installPlugin(Path, String, boolean)`.

Parameters:
  `baseURL` - where we get the files from
  `fileName` - the name
  `checkVersion` - do we want to check vs the IdP Version?
Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### installPlugin

public void installPlugin(@Nonnull Path base, @Nonnull @NotEmpty String fileName, boolean checkVersion) throws org.apache.tools.ant.BuildException
Install the plugin from a local path.

- Check signature
- Unpack to temp folder
- Install from the folder

Parameters:
  `base` - the directory where the files are
  `fileName` - the name
  `checkVersion` - do we want to check vs the IdP Version?
Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### uninstall

public void uninstall() throws org.apache.tools.ant.BuildException
Remove the jars for this plugin and rebuild the war.

Throws:
  `org.apache.tools.ant.BuildException` - if badness occurs.

### setupDescriptionFromDistribution

private void setupDescriptionFromDistribution() throws org.apache.tools.ant.BuildException
Get hold of the `IdPPlugin` for this plugin.

Throws:
  `org.apache.tools.ant.BuildException` - if badness is happens.

### getInstalledContents

@Nonnull public List<Path> getInstalledContents()
What files were installed to webapp for this plugin?

Returns:
  a list of the absolute paths of the installed contents, may be empty if nothing is installed or the plugin didn't install anything.

### getVersionFromContents

@Nullable public String getVersionFromContents()
return the version that the contents page thinks is installed.

Returns:
  the version, or null if it is not found.

### getModuleContext

@Nonnull private ModuleContext getModuleContext()
Check for initialized and if so return the `moduleContext`.

Returns:
  the `moduleContext`.

### getPluginsWebapp

@Nonnull private Path getPluginsWebapp()
Check for initialized and if so return the `pluginsWebapp`.

Returns:
  the `pluginsWebapp`.

### getDescription

@Nonnull private IdPPlugin getDescription()
Check for non null and then if so return the `description`.

Returns:
  the `description`

### getLoadedModules

@Nonnull public Set<String> getLoadedModules() throws org.apache.tools.ant.BuildException
What modules (on the installed plugins Classpath) are currently loaded?

Returns:
  a set of the names of the currently enabled Modules.
Throws:
  `org.apache.tools.ant.BuildException` - on loading a module

### checkRequiredModules

private void checkRequiredModules(@Nonnull Set<String> loadedModules) throws org.apache.tools.ant.BuildException
Police that required modules for plugin installation are enabled.

Parameters:
  `loadedModules` - the modules we know to be enabled
Throws:
  `org.apache.tools.ant.BuildException` - if any required modules are missing or disabled

### getModulePluginInfo

private Pair<String,String> getModulePluginInfo(String moduleId) throws org.apache.tools.ant.BuildException
If we have the information, get the Plugin Id and version which supplies the module id.

Parameters:
  `moduleId` - The module ID
Returns:
  a Pair of string the first being the plugin ID and the second its version
Throws:
  `org.apache.tools.ant.BuildException`

### reEnableModules

private void reEnableModules(Set<String> loadedModules) throws org.apache.tools.ant.BuildException
Re-enabled the listed modules iff then are implemented by the plugin we just installed.

Parameters:
  `loadedModules` - the modules to enable
Throws:
  `org.apache.tools.ant.BuildException` - on errors finding or enabling the modules

### handlePackages

private void handlePackages(@Nonnull RollbackPluginInstall rollback) throws org.apache.tools.ant.BuildException
Deploy any required packages.

Parameters:
  `rollback` - Roll Back Context
Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### installNew

private void installNew(@Nonnull RollbackPluginInstall rollBack) throws org.apache.tools.ant.BuildException
Copy the webapp folder from the distribution to the per plugin location inside dist.

Parameters:
  `rollBack` - Roll Back Context
Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### uninstallOld

private void uninstallOld(@Nonnull RollbackPluginInstall rollback) throws org.apache.tools.ant.BuildException
Uninstall the old version of the plugin.

Parameters:
  `rollback` - Rollback Context
Throws:
  `org.apache.tools.ant.BuildException` - on IO or module errors

### saveCopiedFiles

private void saveCopiedFiles(@Nonnull List<Path> copiedFiles) throws org.apache.tools.ant.BuildException
Stream the copy list to a property file and empty it.

Parameters:
  `copiedFiles` - The copied files
Throws:
  `org.apache.tools.ant.BuildException` - If we hit an IO exception

### inferInstalledIdpHome

@Nullable private Path inferInstalledIdpHome(@Nonnull Properties props)
Infer where the properties were installed to.

Parameters:
  `props` - The property files
Returns:
  the idpHome it was installed to or null if no files installed

### loadCopiedFiles

private void loadCopiedFiles() throws org.apache.tools.ant.BuildException
Load the contents for this plugin from the properties file used during installation.

Throws:
  `org.apache.tools.ant.BuildException` - if the load fails

### download

private void download(@Nonnull URL baseURL, @Nonnull String fileName) throws org.apache.tools.ant.BuildException
Method to download a zip file to the {`downloadDirectory`.

Parameters:
  `baseURL` - Where the zip/tgz and signature file is
  `fileName` - the name.
Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### captureChanges

private void captureChanges(@Nonnull Map<Module.ModuleResource,Module.ResourceResult> changes)
Capture module changes.

Parameters:
  `changes` - what has changed

### emitModuleChanges

private void emitModuleChanges()
Emit module changes.

### doReportOperation

private void doReportOperation(@Nonnull Module.ModuleResource resource, @Nonnull Module.ResourceResult result)
Report on a resource result.

Parameters:
  `resource` - resource
  `result` - result of operation

### unpack

private void unpack(@Nonnull Path base, @Nonnull String fileName) throws org.apache.tools.ant.BuildException
Helper Method for unpacking the distribution. Populates `unpackDirectory` and`distribution`

Parameters:
  `base` - Where the zip/tgz file is
  `fileName` - the name.
Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### unpack

private static void unpack(@Nonnull Path unpackTo, @Nonnull Path fullName, boolean isZip, boolean stripFirst) throws org.apache.tools.ant.BuildException
Method to unpack a zip or tgz file into our {`unpackDirectory`.

Parameters:
  `unpackTo` - Where to unpack to
  `fullName` - what to unzip
  `isZip` - is this a zip file?
  `stripFirst` - do we remove the first "directory" in the path (allows install in place)
Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### isZip

private static boolean isZip(@Nonnull String fileName) throws org.apache.tools.ant.BuildException
does the file name end in .zip?

Parameters:
  `fileName` - the name to consider
Returns:
  true if it ends with .zip
Throws:
  `org.apache.tools.ant.BuildException` - if the name is too short

### getStreamFor

@Nonnull private static org.apache.commons.compress.archivers.ArchiveInputStream<?> getStreamFor(@Nonnull Path fullName, boolean isZip) throws IOException
Create the correct `ArchiveInputStream` for the input.

Parameters:
  `fullName` - the path of the zip file to unpack.
  `isZip` - if true then this is a zip file, otherwise a tgz file
Returns:
  the the appropriate `ArchiveInputStream`
Throws:
  `IOException` - if we trip over an unpack

### setupPluginId

private void setupPluginId() throws org.apache.tools.ant.BuildException
Look into the distribution and suck out the plugin id.

Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### checkSignature

private void checkSignature(@Nonnull Path base, @Nonnull String fileName) throws org.apache.tools.ant.BuildException
Check the signature of the plugin.

Parameters:
  `base` - Where the zip/tgz file is
  `fileName` - the name.
Throws:
  `org.apache.tools.ant.BuildException` - if badness is detected.

### doInitialize

protected void doInitialize() throws ComponentInitializationException

Overrides:
  `doInitialize` in class `AbstractInitializableComponent`
Throws:
  `ComponentInitializationException`

### getInstalledPluginsLoader

@Nonnull private URLClassLoader getInstalledPluginsLoader() throws org.apache.tools.ant.BuildException
Generate a `URLClassLoader` which looks at the installed WEB-INF/lib in addition to the dist webapp and bin/lib directories. As a side effect, it also copies the libs (since they may well be overwritten)

Returns:
  an appropriate loader
Throws:
  `org.apache.tools.ant.BuildException` - if a directory traversal fails.

### getDistributionLoader

@Nonnull private URLClassLoader getDistributionLoader() throws org.apache.tools.ant.BuildException
Generate a `URLClassLoader` which looks at the installing WEB-INF.

Returns:
  an appropriate loader
Throws:
  `org.apache.tools.ant.BuildException` - if a directory traversal fails.

### getInstalledPlugins

@Nonnull public List<IdPPlugin> getInstalledPlugins() throws org.apache.tools.ant.BuildException
Return a list of the installed plugins.

Returns:
  All the plugins.
Throws:
  `org.apache.tools.ant.BuildException` - if loafing the classpath fails.

### getInstalledPlugin

@Nullable public IdPPlugin getInstalledPlugin(@Nonnull String name)
Find the `IdPPlugin` with the provided Id.

Parameters:
  `name` - what to find
Returns:
  the `IdPPlugin` or null if not found.

### closeSilently

private void closeSilently(@Nullable AutoCloseable what)
close, ignoring errors.

Parameters:
  `what` - what to close

### close

public void close()

Specified by:
  `close` in interface `AutoCloseable`

### getIdPVersion

@Nonnull protected static InstallableComponentVersion getIdPVersion()
Return a version we can use in a test proof manner.

Returns:
  the IdP version or a fixed value