Package org.forgerock.openam.plugins

Interface AmPlugin

All Known Implementing Classes:
AbstractNodeAmPlugin, IotPlugin
@SupportedAll 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 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 onShutdown() method for all plugins will be called in the reverse order from the order that onStartup() was called, with dependent plugins being notified after their dependencies for startup, and before them for shutdown.

  • Method Details

    • getPluginVersion

      String getPluginVersion()
      The plugin version. This must be in semver (semantic version) format.
      Returns:
      The version of the plugin.
      See Also:

    • getDependencies

      default Map<Class<? extends AmPlugin>,String> getDependencies()
      Get the collection of plugins that this plugin expects to be installed. The onInstall(), upgrade(String) and 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 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:

    • 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 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, upgrade(String) may be called, and 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 getPluginVersion() is higher than the version already installed. This method will be called before the onStartup() method.
      Parameters:
      fromVersion - The old version of the plugin that has been installed.
      Throws:
      PluginException

    • onStartup

      default void onStartup(org.forgerock.openam.plugins.StartupType startupType) throws PluginException
      Handle plugin startup. This method will be called every time AM starts, after onInstall(), onAmUpgrade(String, String) and 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 onStartup(StartupType) instead.
      Handle plugin startup. This method will be called every time AM starts, after onInstall(), onAmUpgrade(String, String) and 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 onStartup() was called to indicate that the plugin can startup.

    • getServiceSchemaXML

      default Map<String,String> getServiceSchemaXML() throws PluginException
      Defines the SMS Service name and an SMS Service Schema XML for each service that this AmPlugin implementation registers as part of startup.

      On Startup: this method will be called to automatically request the XML schema and then load it into the SMS both during configuration and after a restart.

      Returns:
      If this AmPlugin implementation does not define any SMS services then this method can return null or an empty Map. Otherwise it should return a mapping of the SMS Service name and its corresponding SMS Service Schema.
      Throws:
      PluginException - if there is a problem getting the serviceSchemaXML