Addon is a companion product or runtime component installed on top of Sun Java System Application Server. The runtime of the addon typically is embedded in the application server JVM as a Lifecycle module. An addon might also use one or more Java EE applications for managing its' runtime. An addon is free to use its own workspace, shared libraries, configuration files or any mechanism needed to setup its' runtime.

An addon package is implemented as two plugins called Installer plugin and configurator plugin for installation and configuration respectively. To enable the components code their implementation, the addon infrastructure API is made available as a maven repository. The component teams implement the above API to develop installer and configurator plugins. Once the addon is installed and configured, it'll be possible to unconfigure per domain or across all domains. It is also possible to upgrade the configurator to a new version as discussed below. Since the upgrade is detected using the naming convention for the addon jar file name, it is critical that the naming convention is adhered to.

At present, it is possible to install/configure the addon at the domain level and in future this may be extended to server instances.

## Installer Plugin

If addon requires installation of shared files which are not specific to a particular application server domain, installation and initial configuration of such files must be handled by installer plugin. Installer plugin is an implementation of `com.sun.appserv.addons.Installer` interface. The installer plugin has read-write access to installation root directory (INSTALL_ROOT) of the appserver.

Installer plugin is invoked either at the end of appserver installation or when the CLI command `asadmin install-addon addon_name_installer.jar` is executed.

As part of installation, the installer plugin should ensure that a configurator jar file representing the run time component is made available in INSTALL_ROOT/lib/addons. This jar file, called configurator plugin is used to configure the domain.

The installer plugin will get executed only in the DAS (Domain Administration Server) installation.

The installer plugin is also used to uninstall the addon. Uninstallation is triggered either at the beginning of appserver uninstallation or when `asadmin uninstall-addon addon_name` CLI command is executed.

### Packaging Guidelines for Installer Plugin

The installer plugin for an addon must be packaged in a jar file named `addon_name_installer.jar`, where addon_name is the name of the addon. The `META-INF/services/com.sun.appserv.addons.Installer` file in the installer plugin jar will contain the name of the addon installer implementation class.

## Configurator Plugin

Configurator plugin is an implementation of `com.sun.appserv.addons.Configurator` interface. It will be placed in the INSTALL_ROOT/lib/addons by the installer plugin. Configuration plugin will be invoked always in the DAS installation. It will get invoked before DAS is started and before a command that start the remote instance is executed.

The configurator plugin should assume read-only access to INSTALL_ROOT and read-write access to root directory of the domain (DOMAIN_DIR). The configurator will be invoked once, prior to starting application server domain. The configurator will access application server configuration files like DOMAIN_DIR/config/domain.xml, DOMAIN_DIR/config/server.policy etc. and make ncessary changes. While making such changes, configurator plugin is expected to use the addons directory in the INSTANCE_ROOT to refer the shared files.

If an addon require a working directory where it need to store the configuraton files or any data, addon runtime can create it when required. It is recommended for the addon to create such directories under INSTANCE_ROOT/addons/

### Packaging Guidelines for Configurator Plugin

The configurator plugin for an addon must be packaged in a jar file named `addon_name_configurator.jar`, where addon_name is the name of the addon. The `META-INF/services/com.sun.appserv.addons.Configurator` file of the configurator plugin jar will contain the name of the addon configurator implementation class.

### Addon Registry

Appserver will maintain a properties file `domain-registry` in the INSTANCE_ROOT/config directory. This registry will conatin the state of the addon. The registry will contain information about the state of the addon similar to what is shown below.

    addon_name_configurator_01_01_00.configured=true
    addon_name_configurator_01_01_00.enabled=true

A user can change the state of the addon in this file to enable/disable/unconfigure the addon. Next time when the server is restarted, the corresponding operation will actually become effective.

For ex. if one wants to unconfigure `addon_name_configurator_01_01_00`, the value for configured will be set tofalse and when the server is restarted, the addon will be unconfigured for that domain. If the addon needs to be unconfigured across all domains which use this installation then move the `lib/addons/addon_name_configurator_01_01_00.jar` to `lib/addons/.deleted directory`.

### Upgrade

To start with, the upgrade has been implemented for configurator and it can be implemented for installer based on the requirement. To detect upgrade for a configurator, a specific naming convention is used as given below.

`<component_name>_configurator_<major>_<minor>_<patch level>.jar`

for example:
`am_components_configurator_01_01_00.jar`

The start-domain command causes the scanning of `lib/addons` directory and if a new version of the configurator is detected based on the above naming convention, then the upgrade method of the component's implementation will be invoked. The old configurator jar may then be removed or moved to `lib/addons/.deleted` directory.

## Example Addon and Naming Convention

    addon_name_installer.jar
            |- META-INF/services/com.sun.appserv.addons.Installer
            |- InstallerImpl.class (implements Installer)
            |- InstallerUtil.class
            |- InstallerMore.class
            |- addon_name_01_01_00.jar
               |- META-INF/services/com.sun.appserv.addons.Configurator
               |- ConfiguratorImpl.class (implements Configurator)
               |- Another.class
               |- More.class
               |- Util.class

## Related Documentation

GlassFish wiki contains an one pager document about addons.

- GlassFish One Pager

@since 9.1 @see com.sun.appserv.addons.Installer @see com.sun.appserv.addons.Configurator