org.forgerock.openam.plugins

Interface AmPlugin

All Known Implementing Classes:

AbstractNodeAmPlugin

public interface AmPlugin

Define an AM plugin. Implementing classes can use @Inject setters to get access to APIs available via Guice dependency injection. For example, if you want to add an SMS service on install, you can add the following setter:

  @Inject
 public void setPluginTools(PluginTools tools) {
     this.tools = tools;
 }
 

So that you can use the PluginTools.addSmsService(java.io.InputStream) method to load your schema XML.

It can be assumed that when running, implementations of this class will be singleton instances.

It should not be expected that the runtime singleton instances will be the instances on which AmPlugin.onAmUpgrade(String, String) will be called. Guice-injected properties will also not be populated during that method call.

Plugins should not use the ShutdownManager/ShutdownListener API for handling shutdown, as the order of calling those listeners is not deterministic. The AmPlugin.onShutdown() method for all plugins will be called in the reverse order from the order that AmPlugin.onStartup() was called, with dependent plugins being notified after their dependencies for startup, and before them for shutdown.

Since:

AM 5.5.0

Method Summary

Modifier and Type	Method and Description
default Map<Class<? extends AmPlugin>,String>	getDependencies() Get the collection of plugins that this plugin expects to be installed.
String	getPluginVersion() The plugin version.
default void	onAmUpgrade(String fromVersion, String toVersion) Handle AM system upgrade.
void	onInstall() Handle plugin installation.
default void	onShutdown() Handle plugin shutdown.
default void	onStartup() Deprecated. Use AmPlugin.onStartup(StartupType) instead.
default void	onStartup(StartupType startupType) Handle plugin startup.
default void	onUnsatisfiedDependency(Set<String> missingDependencies) This method will be called if the plugin has previously been installed, but the dependencies cannot currently be satisfied.
default void	upgrade(String fromVersion) This method will be called when the version returned by AmPlugin.getPluginVersion() is higher than the version already installed.

Method Detail

getPluginVersion

String getPluginVersion()

The plugin version. This must be in semver (semantic version) format.

Returns:

The version of the plugin.

See Also:

Semantic Versioning

getDependencies

default Map<Class<? extends AmPlugin>,String> getDependencies()

Get the collection of plugins that this plugin expects to be installed. The AmPlugin.onInstall(), AmPlugin.upgrade(String) and AmPlugin.onStartup() methods will only be called if all these dependencies are satisfied. If any plugin cannot be satisfied from the classpath, if the plugin is not yet installed, it will not be installed and system installation will result in an error, otherwise the AmPlugin.onUnsatisfiedDependency(Set) method will be called.

Returns:

A non-null map of plugin class to plugin version for the dependencies of this plugin. The version can use OSGi version range syntax, e.g. [1.3,1.8.3) for greater than or equal to 1.3 and less than 1.8.3.

See Also:

OSGi SemVer

onUnsatisfiedDependency

default void onUnsatisfiedDependency(Set<String> missingDependencies)
                              throws PluginException

This method will be called if the plugin has previously been installed, but the dependencies cannot currently be satisfied.

Parameters:

missingDependencies - The plugin class names for all the plugin dependencies that cannot be satisfied.

Throws:

PluginException

onInstall

void onInstall()
        throws PluginException

Handle plugin installation. This method will only be called once, on first AM startup once the plugin is included in the classpath. The AmPlugin.onStartup() method will be called after this one.

Throws:

PluginException

onAmUpgrade

default void onAmUpgrade(String fromVersion,
                         String toVersion)
                  throws PluginException

Handle AM system upgrade. This method will be called once for each system upgrade that takes place after the plugin has already been installed. After this method is called, AmPlugin.upgrade(String) may be called, and AmPlugin.onStartup() will be called.

Parameters:

fromVersion - The old AM version.

toVersion - The new AM version.

Throws:

PluginException

upgrade

default void upgrade(String fromVersion)
              throws PluginException

This method will be called when the version returned by AmPlugin.getPluginVersion() is higher than the version already installed. This method will be called before the AmPlugin.onStartup() method.

Parameters:

fromVersion - The old version of the plugin that has been installed.

Throws:

PluginException

onStartup

default void onStartup(StartupType startupType)
                throws PluginException

Handle plugin startup. This method will be called every time AM starts, after AmPlugin.onInstall(), AmPlugin.onAmUpgrade(String, String) and AmPlugin.upgrade(String) have been called (if relevant).

Parameters:

startupType - The type of startup that is taking place.

Throws:

PluginException

onStartup

@Deprecated
default void onStartup()
                            throws PluginException

Deprecated. Use AmPlugin.onStartup(StartupType) instead.

Handle plugin startup. This method will be called every time AM starts, after AmPlugin.onInstall(), AmPlugin.onAmUpgrade(String, String) and AmPlugin.upgrade(String) have been called (if relevant).

Throws:

PluginException

onShutdown

default void onShutdown()

Handle plugin shutdown. This method will be called when AM is shutting down, and should be used to close any resources that the plugin is using. This method will only be called if AmPlugin.onStartup() was called to indicate that the plugin can startup.