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.
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.
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.
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/
For ex. if one wants to unconfigure
for example:
The start-domain command causes the scanning of 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.
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
am_components_configurator_01_01_00.jar
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.
@since 9.1
@see com.sun.appserv.addons.Installer
@see com.sun.appserv.addons.Configurator