The Plugin Class

The plugin class is responsible for informing AM about the details of the customized authentication node. There is little variation between the plugin class for each authentication node, other than the version number and class names within.

Authentication nodes are installed into the product using the AM plugin framework. All AM plugins are created by implementing org.forgerock.openam.plugins.AmPlugin interface and then registering it using the Java service architecture - placing a file in META-INF/services.

For plugins that provide authentication nodes there is an abstract implementation of the AmPlugin interface named org.forgerock.openam.auth.node.api.AbstractNodeAmPlugin.

The following is an example of the plugin class for an authentication node:

public class MyCustomNodePlugin extends AbstractNodeAmPlugin { 

  private static String currentVersion = "1.0.0"; 

  @Override
  protected Map<String, Iterable<? extends Class<? extends Node>>>
  getNodesByVersion() {
    return Collections.singletonMap("1.0.0", Collections.singletonList(MyCustomNode.class)); 
  }

  @Override
  public String getPluginVersion() {
    return MyCustomNodePlugin.currentVersion;
  }
}

Key:

	Name the plugin class after the core class, and append Plugin. For example, `MyCustomNodePlugin`.
	Provide a version number for the authentication node.
	Ensure a call to the `getNodesByVersion()` function returns the core classes of the authentication nodes to register. In this example the version is `1.0.0`, and there is just one node being registered as that version.

AM plugins are notified of the following events:

onInstall

The plugin has been found during AM startup, and is being installed for the first time. It should create all the services and objects it needs.

onStartup(StartupType startupType)

The plugin is installed and is being started. Any dependency plugins can be relied on as having been started.

The type of startup is provided:

FIRST_TIME_INSTALL. The AM instance has been installed for the first time.
FIRST_TIME_DEMO_INSTALL. The AM deployment has been installed for the first time, using an embedded data store as the config and user stores.
NORMAL_STARTUP. The AM instance is starting from a previously installed state, or is joining an already installed cluster.

onShutdown

The AM instance is in the process of shutting down cleanly. Any resources the plugin is using should be released and cleaned up.

upgrade(String fromVersion)

An existing version of the plugin is installed, and a new version has been found during startup. The plugin should make any changes it needs to the services and objects used in the previous version, and create all the services and objects required by the new version.

The version of the plugin being upgraded is provided.

onAmUpgrade(String fromVersion, String toVersion)

An AM system upgrade is in progress. Any updates needed to accommodate the AM upgrade should be made.

Plugin-specific upgrade should not be made here, as upgrade will be called subsequently if the plugin version has also changed.

The AM version being upgraded from, and to, are provided.

The plugin is responsible for maintaining a version number for its content, which is used for triggering appropriate events for installation and upgrade.

For more information, see amPlugin in the AM 7.0.2 Public API Javadoc.