Oracle GlassFish Server 3.0.1 Add-On Component Development Guide

Creating Connector Modules

Connector modules are small add-on modules that consist of application “sniffers” that associate application types with containers that can run the application type. GlassFish Server connector modules are separate from the associated add-on module that delivers the container implementation to allow GlassFish Server to dynamically install and configure containers on demand.

When a deployment request is received by the GlassFish Server runtime:

  1. The current Sniffer implementations are used to determine the application type.

  2. Once an application type is found, the runtime looks for a running container associated with that application type. If no running container is found, the runtime attempts to install and configure the container associated with the application type as defined by the Sniffer implementation.

  3. The Deployer interface is used to prepare and load the implementation.

Associating File Types With Containers by Using the Sniffer Interface

Containers do not necessarily need to be installed on the local machine for GlassFish Server to recognize the container's application type. GlassFish Server uses a “sniffer” concept to study the artifacts in a deployment request and to choose the associated container that handles the application type that the user is trying to deploy. To create this association, create a Java programming language class that implements the org.glassfish.api.container.Sniffer interface. This implementation can be as simple as looking for a specific file in the application's archive (such as the presence of WEB-INF/web.xml), or as complicated as running an annotation scanner to determine an XML-less archive (such as enterprise bean annotations in a JAR file). A Sniffer implementation must be as small as possible and must not load any of the container's runtime classes.

A simple version of a Sniffer implementation uses the handles method to check the existence of a file in the archive that denotes the application type (as WEB-INF/web.xml denotes a web application). Once a Sniffer implementation has detected that it can handle the deployment request artifact, GlassFish Server calls the setUp method. The setUp method is responsible for setting up the container, which can involve one or more of the following actions:

The setUp method returns an array of the com.sun.enterprise.module.Module objects required by the container.

The Sniffer interface defines the following methods:

handles(ReadableArchive source, ClassLoader loader)

Returns a boolean value indicating whether this Sniffer implementation can handle the specified archive.

getURLPatterns()

Returns a String array containing all URL patterns to apply against the request URL. If a pattern matches, the service method of the associated container is invoked.

getAnnotationTypes()

Returns a list of annotation types recognized by this Sniffer implementation. If an application archive contains one of the returned annotation types, the deployment process invokes the container's deployers as if the handles method had returned true.

getModuleType()

Returns the module type associated with this Sniffer implementation as a String.

setup(String containerHome, Logger logger)

Sets up the container libraries so that any dependent bundles from the connector JAR file will be made available to the HK2 runtime. The setup method returns an array of com.sun.enterprise.module.Module classes, which are definitions of container implementations. GlassFish Server can then load these modules so that it can create an instance of the container's Deployer or Container implementations when it needs to. The module is locked as long as at least one module is loaded in the associated container.

teardown()

Removes a container and all associated modules in the HK2 modules subsystem.

getContainerNames()

Returns a String array containing the Container implementations that this Sniffer implementation enables.

isUserVisible()

Returns a boolean value indicating whether this Sniffer implementation should be visible to end-users.

getDeploymentConfigurations(final ReadableArchive source)

Returns a Map<String, String> of deployment configuration names to configurations from this Sniffer implementation for the specified application (the archive source). The names are created by GlassFish Server; the configurations are the names of the files that contain configuration information (for example, WEB-INF/web.xml and possibly WEB-INF/sun-web.xml for a web application). If the getDeploymentConfigurations method encounters errors while searching or reading the specified archive source, it throws a java.io.IOException.

Making Sniffer Implementations Available to the GlassFish Server

Package Sniffer implementation code into modules and install the modules in the as-install/modules directory. GlassFish Server will automatically discover these modules. If an administrator installs connector modules that containSniffer implementations while GlassFish Server is running, GlassFish Server will pick them up at the next deployment request.