Manveen Kaur's Blog

June 2007 Archives

Testing your Update Center Module

Before you "host" your module on a server for others to download, it would be wise to test it out yourself.

This blog describes how you can test your update center module locally on your GlassFish container through the updatetool client. Hopefully you already know how to create and package your update center module.

Here's what you do to "host" the module on your local running instance of GlassFish. Updatetool is available from GlassFish v2 onwards.

1. Copy your final module jar to be tested into GF_V2_HOME/domains/domain1/docroot. This enables it to be accessible from http://localhost:8080/module.jar
2. Copy GF_V2_HOME/updatecenter/registry/glassfish/server.xml to GF_V2_HOME/domains/domain1/docroot. Let's call it update_center.xml. Doing this will enable it to be accessible from http://localhost:8080/update_center.xml.
3. Edit update_center.xml to have a single entry for the module. Add appropriate values for module codenamebase="my.package" distribution="http://localhost:8080/roller_module.jar".Make sure the Module-Type (under manifest element) is ADDON_INSTALLER.
   Don't worry about getting the exact numbers for downloadsize etc. for now.
4. Edit GF_v2_HOME/updatecenter/config/config.xml.
   For the catalog name='glassfish' change the url to url='http://localhost:8080/update_center.xml'. Start your server.
5. Run GF_V2_HOME/updatecenter/bin/updatetool and choose your module.

The module jars are downloaded under GF_v2_HOME/updatecenter/registry/glassfish/package.name/module. The updatetool is expected to extract and install the module for you.

Trivia: Did you know that a Netbeans module or .nbm extension is just a fancy name for a .jar?

Important contact information: If you are interested in hosting your application on GlassFish Update Center repository, do touch base with the GlassFish Update Center team at: dev@updatecenter.dev.java.net and they'll be happy to work with you.

Creating a GlassFish Update Center module

To try GlassFish Update Center, install GlassFish V2 (screencast). Then go to install-root/glassfish/updatecenter/bin and invoke updatetool (or updatetool.bat). You'll see a list of addon modules available for installation.

But what's an addon and how do you create one?

An addon is a companion product or runtime component installed on top of Sun Java System Application Server.

Right, but how do you create such a module?

To start with, you need to implement an com.sun.appserv.addons.Installer interface. You may also need a com.sun.appserv.addons.Configurator interface implementation.

What's the difference between and installer and a configurator 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. 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.
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 necessary changes.

Where can I get the installer plugin API?

How do I package the installer plugin?

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

How do I invoke and test the installer plugin?

Installer plugin is invoked either at the end of appserver installation or when the CLI command

asadmin install-addon addon_name_installer.jar 

Now for the final packaging.

File system layout for downloadable module file (equivalent of NetBeans NBM file) will be jar archive file with following structure:

         module_xx.jar
                |   
                +- info
                |   |
                |   +- info.xml
                |
                +- module
                      |
                      |
                      +- locale (optional, for localized packages)
                           |
                           |
                           +-installer_xx.jar or installer_xx.zip

installer_xx.jar can be addon component installer or configurator jar file as specified in Addon installer and configurator plug-in imported interfaces.

The DTD for info.xml is here.

This work is licensed under a Creative Commons License.