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 can be implemented as two plugins called Installer plugin and configurator plugin.

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-installer-jar is executed.

While installing, the installer plugin should ensure that a 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. Any shared bits of the addon that need to be synchronized to remote instances need to be copied to the DOMAIN_ROOT/addons directory by the configurator plugin. This directory will be synchronized to all remote instances.

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 main class 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 .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 (addon.properties) 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-1.jar.enabled=true
addon-2.jar.configured=false
addon-3.jar.enabled=false
A user can change the state of the addon in this file to enable/disable/unconfigure the addon. Next time when DAS and the remote instances are restarted, the corresponding operation will actually become effective.

Example Addon

addon-name_installer.jar
        |- META-INF/services/com.sun.appserv.addons.Installer
        |- InstallerImpl.class (implements Installer)
        |- InstallerUtil.class
        |- InstallerMore.class
        |- addon-name.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. @since 9.1 @see com.sun.appserv.addons.Installer @see com.sun.appserv.addons.Configurator