Eclipse GlassFish Add-On Component Development Guide, Release 7

The Hundred-Kilobyte Kernel (HK2) is the lightweight and extensible kernel of Eclipse GlassFish. To interact with Eclipse GlassFish, add-on components plug in to this kernel. In the HK2 component model, the functions of an add-on component are declared through a contract-service implementation paradigm. An HK2 contract identifies and describes the building blocks or the extension points of an application. An HK2 service implements an HK2 contract.

For more information, see Writing HK2 Components.

The Administration Console is a browser-based tool for administering Eclipse GlassFish. It features an easy-to-navigate interface and online help. Extending the Administration Console enables you to provide a graphical user interface for administering your add-on component. You can use any of the user interface features of the Administration Console, such as tree nodes, links on the Common Tasks page, tabs and sub-tabs, property sheets, and JavaServer Faces pages. Your add-on component implements a marker interface and provides a configuration file that describes how your customizations integrate with the Administration Console.

For more information, see Extending the Administration Console.

The asadmin utility is a command-line tool for configuring and administering Eclipse GlassFish. Extending the asadmin utility enables you to provide administrative interfaces for an add-on component that are consistent with the interfaces of other Eclipse GlassFish components. A user can run asadmin subcommands either from a command prompt or from a script. For more information about the asadmin utility, see the asadmin(1M) man page.

For more information, see Extending the asadmin Utility.

Monitoring is the process of reviewing the statistics of a system to improve performance or solve problems. By monitoring the state of components and services that are deployed in the Eclipse GlassFish, system administrators can identify performance bottlenecks, predict failures, perform root cause analysis, and ensure that everything is functioning as expected. Monitoring data can also be useful in performance tuning and capacity planning.

An add-on component typically generates statistics that the Eclipse GlassFish can gather at run time. Adding monitoring capabilities enables an add-on component to provide statistics to Eclipse GlassFish in the same way as components that are supplied in Eclipse GlassFish distributions. As a result, system administrators can use the same administrative interfaces to monitor statistics from any installed Eclipse GlassFish component, regardless of the origin of the component.

For more information, see Adding Monitoring Capabilities.

The configuration data of a component determines the characteristics and runtime behavior of a component. Eclipse GlassFish provides interfaces to enable an add-on component to store its configuration data in the same way as other Eclipse GlassFish components. These interfaces are similar to interfaces that are defined in Jakarta XML Binding 3.0 (https://jakarta.ee/specifications/xml-binding/3.0/). By using these interfaces to store configuration data, you ensure that the add-on component is fully integrated with Eclipse GlassFish. As a result, administrators can configure an add-on component in the same way as they can configure other Eclipse GlassFish components.

For more information, see Adding Configuration Data for a Component.

Applications run on Eclipse GlassFish in containers. Eclipse GlassFish enables you to create containers that extend or replace the existing containers of Eclipse GlassFish. Adding container capabilities enables you to run new types of applications and to deploy new archive types in Eclipse GlassFish.

For more information, see Adding Container Capabilities.

Eclipse GlassFish enables you to create a session persistence module in the web container for high availability-related functionality by implementing the PersistenceStrategyBuilder interface . Using the PersistenceStrategyBuilder interface in an HK2 service makes the session manager extensible because you can implement a new persistence type without having to modify the web container code.

For information about other high-availability, session persistence solutions, see "Configuring High Availability Session Persistence and Failover" in Eclipse GlassFish High Availability Administration Guide.

For more information, see Creating a Session Persistence Module.

Packaging an add-on component enables the component to interact with the Eclipse GlassFish kernel in the same way as other components. Integrating a component with Eclipse GlassFish enables Eclipse GlassFish to discover the component at runtime. If an add-on component is an extension or update to existing installations of Eclipse GlassFish, deliver the component through Update Tool.

For more information, see Packaging, Integrating, and Delivering an Add-On Component.

You can specify the scope of a service by adding an org.jvnet.hk2.annotations.Scoped annotation to the class-level of your @Service implementation class. Scopes are also services, so they can be custom defined and added to the HK2 runtime before being used by other services. Each scope is responsible for storing the service instances to which it is tied; therefore, the HK2 runtime does not rely on predefined scopes (although it comes with a few predefined ones).

The following code fragment shows how to set the scope for a service to the predefined Singleton scope:

You can define a new Scope implementation and use that scope on your @Service implementations. You will see that the HK2 runtime uses the Scope instance to store and retrieve service instances tied to that scope.

Do not call the new method to instantiate components. Instead, retrieve components by using the Habitat instance. The simplest way to use the Habitat instance is through a getComponent(Class`T `contract) call:

More APIs are available at Habitat (http://hk2.java.net/auto-depends/apidocs/org/jvnet/hk2/component/Habitat.html).

Components can attach behaviors to their construction and destruction events by implementing the org.jvnet.hk2.component.PostConstruct (http://hk2.java.net/auto-depends/apidocs/org/jvnet/hk2/component/PostConstruct.html) interface, the org.jvnet.hk2.component.PreDestroy (http://hk2.java.net/auto-depends/apidocs/org/jvnet/hk2/component/PreDestroy.html) interface, or both. These are interfaces rather than annotations for performance reasons.

The PostConstruct interface defines a single method, postConstruct, which is called after a component has been initialized and all its dependencies have been injected.

The PreDestroy interface defines a single method, preDestroy, which is called just before a component is removed from the system.

Example 2-1 Example Implementation of PostContruct and PreDestroy

Services usually rely on other services to perform their tasks. The HK2 runtime identifies the @Contract implementations required by a service by using the org.jvnet.hk2.annotations.Inject (http://hk2.java.net/auto-depends/apidocs/org/jvnet/hk2/annotations/Inject.html) annotation. Inject can be placed on fields or setter methods of any service instantiated by the HK2 runtime. The target service is retrieved and injected during the calling service’s instantiation by the component manager.

The following example shows how to use @Inject at the field level:

The following example shows how to use @Inject at the setter level:

Injection can further qualify the intended injected service implementation by using a name and scope from which the service should be available:

Injection of instances that have not been already instantiated triggers more instantiation. You can see this as a component instantiation cascade where some code requests for a high-level service will, by using the @Inject annotation, require more injection and instantiation of lower level services. This cascading feature keeps the implementation as private as possible while relying on interfaces and the separation of contracts and providers.

Example 2-2 Example of Instantiation Cascading

The following example shows how the instantiation of DeploymentService as a Startup contract implementation will trigger the instantiation of the ConfigService.

The org.glassfish.api.admingui.ConsoleProvider interface has one required method, getConfiguration. The getConfiguration method returns the location of the console-config.xml file as a java.net.URL. If getConfiguration returns null, the default location, META-INF/admingui/console-config.xml, is used. The console-config.xml file is described in About Integration Points.

To implement the console provider for your add-on component, write a Java class that is similar to the following example.

Example 3-1 Example ConsoleProvider Implementation

This example shows a simple implementation of the ConsoleProvider interface:

This implementation of getConfiguration returns null to specify that the configuration file is in the default location. If you place the file in a nonstandard location or give it a name other than console-config.xml, your implementation of getConfiguration must return the URL where the file can be found.

You can add a node to the navigation tree, either at the top level or under another node. To add a node, use an integration point of type org.glassfish.admingui:navNode. Use the parentId attribute to specify where the new node should be placed. Any tree node, including those added by other add-on components, can be specified. Examples include the following:

If you do not specify a parentId, the new content is added to the root of the integration point, in this case the top level node, tree.

Example 3-2 Example Tree Node Integration Point

For example, the following integration-point element uses a parentId of tree to place the new node at the top level.

This example specifies the following values in addition to the parentId:

The example console-config.xml file provides other examples of tree nodes under the Resources and Configuration nodes.

You can add a tab to an existing tab set, or you can create a tab set for your own page. One way to add a tab or tab set is to use an integration point of type org.glassfish.admingui:serverInstTab, which adds a tab to the tab set on the main Eclipse GlassFish page of the Administration Console. You can also create sub-tabs. Once again, the parentId element specifies where to place the tab or tab set.

Example 3-4 Example Tab Integration Point

In the example, the following integration-point element adds a new tab on the main Eclipse GlassFish page of the Administration Console:

This example specifies the following values:

Example 3-5 Example Tab Set Integration Points

The following integration-point elements add a new tab with two sub-tabs, also on the main Eclipse GlassFish page of the Administration Console:

These examples specify the following values:

You can add either a single task or a group of tasks to the Common Tasks page of the Administration Console. To add a task or task group, use an integration point of type org.glassfish.admingui:commonTask.

See Adding a Task Group to the Common Tasks Page for information on adding a task group.

Example 3-7 Example Task Integration Point

In the example console-config.xml file, the following integration-point element adds a task to the Deployment task group:

This example specifies the following values:

You can add a new group of tasks to the Common Tasks page to display the most important tasks for your add-on component. To add a task group, use an integration point of type org.glassfish.admingui:commonTask.

Example 3-9 Example Task Group Integration Point

In the example console-config.xml file, the following integration-point element adds a new task group to the Common Tasks page:

This example specifies the following values:

You can add content for your add-on component to an existing top-level page, such as the Configuration page or the Resources page. To add content to one of these pages, use an integration point of type org.glassfish.admingui:configuration or org.glassfish.admingui:resources.

Example 3-11 Example Resources Page Implementation Point

In the example console-config.xml file, the following integration-point element adds new content to the top-level Resources page:

This example specifies the following values:

Another integration-point element in the console-config.xml file places similar content on the Configuration page.

Your add-on component may require new configuration tasks. In addition to implementing commands that accomplish these tasks (see Chapter 4, "Extending the asadmin Utility"), you can provide property sheets that enable users to configure your component or to perform tasks such as creating and editing resources for it.

Example 3-13 Example Jakarta Server Faces Page for a Property Sheet

Most of the user interface features used in the example reference the file testPage.jsf or (for tabs) the file tabPage.jsf. Both files are in the src/main/resources/page/ directory. The testPage.jsf file looks like this:

The page uses the composition directive to specify that the page uses the default.layout template and to specify a page title. The page uses additional directives, events, and tags to specify its content.

Each asadmin subcommand that you are adding must be represented as a Java class. To represent an asadmin subcommand as a Java class, write a Java class that implements the org.glassfish.api.admin.AdminCommand interface. Write one class for each subcommand that you are adding. Do not represent multiple asadmin subcommands in a single class.

Annotate the declaration of your implementations of the AdminCommand interface with the org.jvnet.hk2.annotations.Service annotation. The @Service annotation ensures that the following requirements for your implementations are met:

To specify the name of the subcommand, set the name element of the @Service annotation to the name.

Subcommands that are supplied in Eclipse GlassFish distributions typically create, delete, and list objects of a particular type. For consistency with the names of subcommands that are supplied in Eclipse GlassFish distributions, follow these conventions when specifying the name of a subcommand:

For example, Eclipse GlassFish provides the following subcommands for creating, deleting, and listing HTTP listeners:

You must also ensure that the name of your subcommand is unique. To obtain a complete list of the names of all asadmin subcommands that are installed, use the list-commands subcommand. For a complete list of asadmin subcommands that are supplied in Eclipse GlassFish distributions, see the Eclipse GlassFish Reference Manual.

To enable multiple clients to run a subcommand simultaneously, ensure that the implementation of the AdminCommand interface for the subcommand is stateless. To ensure that the implementation of the AdminCommand interface is stateless, annotate the declaration of your implementation with the org.jvnet.hk2.annotations.Scoped annotation. In the @Scoped annotation, set the scope as follows:

Example 4-1 Adding an asadmin Subcommand

This example shows the declaration of the class CreateMycontainer that represents an asadmin subcommand that is named create-mycontainer. The subcommand is instantiated for each lookup.

Represent each parameter of a subcommand in your implementation as a field or as the property of a JavaBeans specification setter method. Use the property of a setter method for the following reasons:

Identifying a parameter of an asadmin subcommand enables Eclipse GlassFish to perform the following operations at runtime on the parameter:

To identify a parameter of a subcommand, annotate the declaration of the item that is associated with the parameter with the org.glassfish.api.Param annotation. This item is either the field or setter method that is associated with the parameter.

To specify the properties of the parameter, use the elements of the @Param annotation as explained in the sections that follow.

Whether a parameter is an option or an operand determines how a user must specify the parameter when running the subcommand:

To specify whether a parameter is an option or an operand, set the primary element of the @Param annotation as follows:

The name of an option is the name that a user must type on the command line to specify the option when running the subcommand.

The name of each option that you add in your implementation of an asadmin subcommand can have a long form and a short form. When running the subcommand, the user specifies the long form and the short form as follows:

For example, the short form and the long form of the name of the option for specifying terse output are as follows:

When a user runs the subcommand, the Eclipse GlassFish validates option arguments and operands against the acceptable values that you specify in your implementation.

To specify the acceptable values of a parameter, set the acceptableValues element of the @Param annotation to a string that contains a comma-separated list of acceptable values. If you do not set this element, any string of characters is acceptable.

The default value of a parameter is the value that is applied if a user omits the parameter when running the subcommand.

To specify the default value of a parameter, set the defaultValue element of the @Param annotation to a string that contains the default value. You can also compute the default value dynamically by extending the ParamDefaultCalculator class and setting the defaultCalculator element of the @Param annotation to this class. If these elements are not set, the parameter has no default value.

Whether a parameter is required or optional determines how a subcommand responds if a user omits the parameter when running the subcommand:

To specify whether a parameter is optional or required, set the optional element of the @Param annotation as follows:

Specifying Whether a Parameter Can Be Used Multiple Times on the Command ==== Line

By default, each parameter can be used once on the command line. To use the parameter multiple times, set the multiple element of the @Param annotation to true. The type of the annotated parameter must be an array.

Example 4-2 Adding Parameters to an asadmin Subcommand

This example shows the code for adding parameters to an asadmin subcommand with the properties as shown in the table.

When you define a --target option by using the @Param annotation in the org.glassfish.api package, possible targets are as follows:

These possible targets are represented by the following CommandTarget elements of the @TargetType annotation in the org.glassfish.config.support package:

By default, the allowed targets are server (the DAS), standalone server instances, clusters, and configurations. Not specifying a @TargetType annotation is equivalent to specifying the following @TargetType annotation:

Subcommands that support other combinations of targets must specify @TargetType annotations. For example, the create-http-lb subcommand supports only standalone server instance and cluster targets. Its @TargetType annotation is as follows:

Most subcommands do not act on server instances that are part of a cluster. This ensures that all server instances in a cluster remain synchronized. Thus, the CommandTarget.CLUSTERED_INSTANCE element of the @TargetType annotation is rarely used.

An example exception is the enable subcommand. To perform a rolling upgrade of an application deployed to a cluster, you must be able to enable the new application (which automatically disables the old) on one clustered instance at a time. The @TargetType annotation for the enable subcommand is as follows, all on one line:

Note that the CommandTarget.CLUSTERED_INSTANCE element is specified.

The target name specified in the command line is injected into the subcommand implementation if the following annotation is present:

The Target utility is a service, present in the internal-api module, org.glassfish.internal.api package, which a command implementation can obtain by using the following annotation:

You can use this utility to avoid writing boiler plate code for actions such as getting the list of server instances for a cluster or checking if a server instance is part of a cluster. For example, here is an example of using the utility to obtain the configuration for a target cluster or server instance:

The Target utility is packaged in the as-install/modules/internal-api.jar file. Its methods are documented with comments.

By default, all asadmin subcommands are automatically replicated and run on the DAS and all Eclipse GlassFish instances specified in the --target option. To run a subcommand only on the DAS, use the following @ExecuteOn annotation in the org.glassfish.api.admin package:

The stop-domain subcommand and subcommands that list information are examples of subcommands that execute only on the DAS.

To run a subcommand only on applicable server instances, use the following @ExecuteOn annotation:

Not specifying an @ExecuteOn annotation is equivalent to specifying the following @ExecuteOn annotation:

In addition to RuntimeType, you can specify the following additional elements with the @ExecuteOn annotation:

Some asadmin subcommands may require preprocessing or postprocessing. For example, after an application is deployed to the DAS, references are created in all applicable server instances, which synchronize with the DAS. As another example, Message Queue or load balancer settings may have to be reconfigured whenever a server instance is added to a cluster.

For such cases, the command replication framework provides the @Supplemental annotation (in the org.glassfish.api.admin package). An implementation must use the value element of the @Supplemental annotation to express the supplemented command. This value is the name of the command as defined by the supplemented command’s @Service annotation (in the org.jvnet.hk2.annotations package).

For example, the deploy subcommand requires postprocessing. The deployment command implementation looks like this:

A supplemental command that is run after every successful deployment looks like this:

As another example, a subcommand to create a local server instance might look like this:

A supplemental command to change Message Queue or load balancer settings after local instance creation might look like this:

A supplemental command implements AdminCommand, thus it can use the @Param annotation and expect the corresponding asadmin command parameters to be injected at runtime. The parameter values available for injection are the same ones provided for the original command with which the supplemental command is associated. For example, the DeploymentSupplementalCommand has access to the parameter values available to the DeployCommand invocation.

An asadmin subcommand can be supplemented with multiple supplemental commands. In this case, all supplemental commands are run after completion of the main command but without any guarantee of the order in which they run.

To specify that a supplemental command is run before the main command, set the on element of the @Supplemental annotation to Supplemental.Timing.Before. For example:

Supplemental commands can use the @ExecuteOn annotation as described in Specifying asadmin Subcommand Execution.

An asadmin subcommand or supplemental command might need to run another subcommand. For example, a subcommand running on the DAS might need to run a different subcommand on one or more server instances. Such invocations might use the ClusterExecutor class (in the org.glassfish.api.admin package), which accepts a ParameterMap, to pass parameters and their values to the invoked command.

The ParameterMapExtractor utility is a service, present in the common-util module, org.glassfish.common.util.admin package, which creates a new ParameterMap populated using the parameters and values of another AdminCommand that has already been injected.

To list parameter names you want excluded from the ParameterMap, pass the following:

This is optional.

Create command pattern. The most basic create commands are implemented in the following pattern:

A generic create command implementation can do most of these tasks if the following information is provided:

Delete command pattern. The most basic delete commands are implemented in the following pattern:

A generic delete command implementation can do most of these tasks if the following information is provided:

List command pattern. The most basic list commands simply retrieve all configuration object instances of a given type.

A resolver retrieves a configuration object instance of a particular type. For a create command, it retrieves the parent of the object to be created. For a delete command, it retrieves the object to be deleted. A resolver implements the CrudResolver interface:

Given an AdminCommandContext, plus injection with the asadmin command line parameters (or any other HK2 services if necessary), the resolver should be able to determine the particular configuration object on which to act.

The following resolvers are provided in the org.glassfish.config.support package:

By placing the org.glassfish.config.support.Create annotation on a method, you provide the following information:

The only additional information needed is the resolver to use.

The following example specifies a create-cluster subcommand:

Because there is only one instance of the parent type, Clusters, in the configuration, this example uses the default resolver to retrieve it. Therefore, no resolver needs to be specified.

By placing the org.glassfish.config.support.Delete annotation on a method, you provide the following information:

The only additional information needed is the resolver to use.

The following example specifies a delete-cluster subcommand:

The TypeAndNameResolver uses the child type and the name operand passed through the command line to retrieve the specific cluster instance to be deleted.

By placing the org.glassfish.config.support.Listing annotation on a method, you provide the following information:

The default resolver retrieves all of the children of the specified type. Therefore, no resolver needs to be specified for a list command.

The following example specifies a list-clusters subcommand:

Most create commands must do more than create a single configuration object instance with default attribute values. For example, most create commands allow the user to specify non-default attribute values through command options. For another example, the create-cluster subcommand creates children of the Cluster object and copies a referenced Config object. A creation decorator provides the code necessary to perform such additional operations.

The interface that a creation decorator must implement is as follows:

The CreationDecorator interface is in the org.glassfish.config.support package.

A @Create annotation specifies a creation decorator using a decorator element. For example:

The @Create annotation is on a method of the parent class. However, the referenced creation decorator class is associated with the child class. For example:

The decorator class can optionally be an inner class of the child class. You can inject command options using the @Param annotation. You can also inject HK2 services or configuration instances.

Some delete commands must do more than delete a single configuration object instance. For example, the delete-cluster subcommand deletes the referenced Config object if no other Cluster or Instance objects reference it. A deletion decorator provides the code necessary to perform such additional operations.

The interface that a deletion decorator must implement is as follows:

The DeletionDecorator interface is in the org.glassfish.config.support package.

A @Delete annotation specifies a deletion decorator using a decorator element. For example:

The @Delete annotation is on a method of the parent class. However, the referenced deletion decorator class is associated with the child class. For example:

The decorator class can optionally be an inner class of the child class. You can inject command options using the @Param annotation. You can also inject HK2 services or configuration instances.

Commands specified with the @Create, @Delete, and @Listing annotations can use the @ExecuteOn annotation. The @ExecuteOn annotation specifies whether the command runs on the DAS, on server instances, or both (the default). For more information, see Specifying asadmin Subcommand Execution.

To add an @ExecuteOn annotation to a @Create or @Delete annotation, use the cluster element. For example:

You can specify multiple command annotations on the same method. The following example combines create, delete, and list commands for clusters:

You can also specify multiple create or delete command annotations for the same configuration object type using the @Creates or @Deletes annotation (both in the org.glassfish.config.support package). For example:

These commands create configuration object instances of the same type. Differences in the decorators and resolvers can produce differences in the options each command takes. The @Param annotated attributes of the created type define a superset of options for both commands.

An event provider defines the types of events for the operations that generate statistics for an add-on component.

Eclipse GlassFish enables you to define an event provider in the following ways:

At runtime, your add-on component might perform an operation that generates statistics. To provide statistics about the operation to Eclipse GlassFish, your component must send an event of the correct type when performing the operation.

To send an event, instantiate your event provider class and invoke the method of the event provider class for the type of the event. Instantiate the class and invoke the method in the class that represents your add-on component. Ensure that the method is invoked when your component performs the operation for which the event was defined. One way to meet this requirement is to invoke the method for sending the event in the body of the method for performing the operation.

Example 5-4 Sending an Event

This example shows the code for instantiating the TxManager class and invoking the onTxBegin method to send an event of type begin. This event indicates that a component is about to begin a transaction.

The TxManager class is instantiated in the constructor of the TransactionManagerImpl class. To ensure that the event is sent at the correct time, the onTxBegin method is invoked in the body of the begin method, which starts a transaction.

The declaration of the onTxBegin method in the event provider interface is shown in Example 5-1.

An event listener gathers statistics from events that an event provider sends. To enable an add-on component to gather statistics from events, create listeners to receive events from the event provider. The listener can receive events from the add-on component in which the listener is created and from other components.

To create an event listener, write a Java class to represent the listener. The listener can be any Java object.

An event listener also represents a component’s statistics. To enable the Application Server Management Extensions (AMX) to expose the statistics to client applications, annotate the declaration of the class with the org.glassfish.gmbal.ManagedObject annotation.

Ensure that the class that you write meets these requirements:

A listener is called in the same thread as the event method. As a result, the listener can use thread locals. If the monitored system allows access to thread locals, the listener can access thread locals of the monitored system.

Represent each statistic as the property of a JavaBeans specification getter method of your listener class. Methods in the listener class for processing events can then access the property through the getter method. For more information, see Subscribing to Events From Event Provider Classes.

To enable AMX to expose the statistic to client applications, annotate the declaration of the getter method with the org.glassfish.gmbal.ManagedAttribute annotation. Set the id element of the @ManagedAttribute annotation to the property name all in lowercase.

The data type of the property that represents a statistic must be a class that provides methods for computing the statistic from event data.

The org.glassfish.external.statistics.impl package provides the following classes to gather and compute statistics data:

Example 5-5 Representing a Component’s Statistics in an Event Listener Class

This example shows the code for representing the txcount statistic in the TxListener class.

To receive events from event provider classes, a listener must subscribe to the events. Subscribing to events also specifies the provider and the type of events that the listener will receive.

To subscribe to events from event provider classes, write one method in your listener class to process each type of event. To specify the provider and the type of event, annotate the method with the org.glassfish.external.probe.provider.annotations.ProbeListener annotation. In the @ProbeListener annotation, specify the provider and the type as follows:

Annotate each parameter in the method signature with the @ProbeParam annotation. Set the value element of the @ProbeParam annotation to the name of the parameter.

In the method body, provide the code to update monitoring statistics in response to the event.

Example 5-6 Subscribing to Events From Event Provider Classes

This example shows the code for subscribing to events of type begin from the tx component. The provider of the component is TxManager. The body of the begin method contains code to increase the transaction count txcount by 1 each time that an event is received.

The definition of the begin event type is shown in Example 5-1.

The code for sending begin events is shown in Example 5-4.

The instantiation of the txCount object is shown in Example 5-5.

gfProbes infrastructure allows clients to monitor glassfish even in the absence of provider classes. This is done by allowing clients to receive callbacks when a java methods are entered / exited. Note that while this approach allows a client to monitor legacy code, it may not always be possible to receive "high-level" events.

For example, while it is easy to monitor (through gfProbes) when TransactionManagerImpl.begin() entered / exited, the client cannot determine the transaction ID in this case.

Registering an event listener enables the listener to receive callbacks from the Eclipse GlassFish event infrastructure. The listener can then collect data from events and update monitorable objects in the object tree. These monitorable objects form the basis for monitoring statistics.

Registering an event listener also makes a component and its statistics monitorable objects by adding statistics for the component to the monitorable object tree.

At runtime, the Eclipse GlassFish event infrastructure registers listeners for an event provider when the event provider is started and unregisters them when the event provider is shut down. As a result, listeners have no dependencies on other components.

To register a listener, invoke the static org.glassfish.external.probe.provider.StatsProviderManager.register method in the class that represents your add-on component. In the method invocation, pass the following information as parameters:

Example 5-7 Registering an Event Listener

This example shows the code for registering the event listener TxListener for the add-on component that is represented by the class TransactionManagerImpl. The statistics that are defined in this listener are associated with the web-container configuration element. The listener is registered under the server/applications node. The path from this node to the statistics in the event listener is tx/txapp.

Code for the constructor of the TxListener class is beyond the scope of this example.

Example 6-1 Declaration of an Interface That Defines an Element

This example shows the declaration of the WombatContainerConfig interface that represents the wombat-container-config element. The parent of this element is the config element.

How Interfaces That Are Annotated With @Configured Are Implemented

You are not required to implement any interfaces that you annotate with the @Configured annotation. Eclipse GlassFish implements these interfaces by using the Dom class. Eclipse GlassFish creates a proxy for each Dom object to implement the interface.

Represent each attribute of an element as the property of a pair of JavaBeans specification getter and setter methods of the interface that defines the element. The component for which the configuration data is being defined can then access the attribute through the getter method. The setter method enables the attribute to be updated.

The data type of an attribute is the return type of the getter method that is associated with the attribute. To enable the attribute take properties in the form ${`property-name}` as values, specify the data type as String.

To identify an attribute of an element, annotate the declaration of the getter method that is associated with the attribute with the org.jvnet.hk2.config.Attribute annotation.

To specify the properties of the attribute, use the elements of the @Attribute annotation as explained in the sections that follow.

To specify the name of an attribute, set the value element of the @Attribute annotation to a string that specifies the name. If you do not set this element, the name is derived from the name of the property as follows:

For example, if the getter method getNumberOfInstances is defined for the property NumberOfInstances to represent an attribute, the name of the attribute is number-of-instances.

The default value of an attribute is the value that is applied if the attribute is omitted when the element is written to the domain configuration file.

To specify the default value of an attribute, set the defaultValue element of the @Attribute annotation to a string that contains the default value. If you do not set this element, the parameter has no default value.

Whether an attribute is required or optional determines how Eclipse GlassFish responds if the parameter is omitted when the element is written to the domain configuration file:

To specify whether an attribute is required or optional, set the required element of the @Attribute annotation as follows:

Example 6-2 Defining an Attribute of an Element

This example defines the attribute number-of-instances. To enable the attribute take properties in the form ${`property-name}` as values, the data type of this attribute is String.

Example 6-3 Declaring an Interface to Represent a Subelement

This example shows the declaration of the WombatElement interface to represent the wombat-element element.

Example 6-4 Identifying a Subelement to its Parent Element

This example identifies the wombat-element element as a subelement.

Example 6-7 XML Data Fragment

This example shows the XML data fragment for adding the wombat-container-config element to the domain.xml file. The wombat-container-config element contains the subelement wombat-element. The attributes of wombat-element are initialized as follows:

Add code to write the component’s initial configuration data in the class that represents your add-on component. If your add-on component is a container, add this code to the sniffer class. For more information about adding a container, see Adding Container Capabilities.

Example 6-8 Writing a Component’s Initial Configuration Data to the domain.xml File

This example writes the XML fragment in the file init.xml to the domain.xml file. The fragment is written only if the domain.xml file does not contain the wombat-container-config-element.

The wombat-container-config element is represented by the WombatContainerConfig interface. An optional dependency is set on an instance of a class that implements WombatContainerConfig.

Example 6-9 domain.xml File After Initialization

This example shows the domain.xml file after the setup method was invoked to add the wombat-container-config element under the config element.

Any transaction that you create to modify configuration data must use a configuration change transaction to ensure that the change is atomic, consistent, isolated, and durable (ACID).

Example 6-10 Creating a Transaction to Update Configuration Data

This example shows code in the execute method of an asadmin subcommand for updating the number-of-instances element of wombat-container-config element.

Add a com.jvnet.hk2.annotations.Service annotation at the class definition level to identify your class as a service implementation.

To avoid potential name collisions with other containers, use the fully qualified class name of your container class in the @Service annotation’s name element:

The org.glassfish.api.container.Container interface is the contract that defines a container implementation. Classes that implement Container can extend or replace the functionality in Eclipse GlassFish by allowing applications to be deployed and run within the Eclipse GlassFish runtime.

The Container interface consists of two methods, getDeployer and getName. The getDeployer method returns an implementation class of the org.glassfish.api.deployment.Deployer interface capable of managing applications that run within this container. The getName method returns a human-readable name for the container, and is typically used to display messages belonging to the container.

The Deployer interface defines the contract for managing a particular application that runs in the container. It consists of the following methods:

The DeploymentContext is the usual context object passed around deployer instances during deployment.

Example 7-1 Example Implementation of Container

This example shows a Java programming language class that implements the Container interface and is capable of extending the functionality of Eclipse GlassFish.

Example 7-2 Example Implementation of Deployer

An archive handler is responsible for handling the particular layout of an archive. Jakarta EE defines a set of archives (WAR, JAR, and RAR, for example), and each of these archives has an ArchiveHandler instance associated with the archive type.

Each layout should have one handler associated with it. There is no extension point support at this level; the archive handler’s responsibility is to give access to the classes and resources packaged in the archive, and it should not contain any container-specific code. The java.lang.ClassLoader returned by the handler is used by all the containers in which the application will be deployed.

ArchiveHandler defines the following methods:

Containers do not necessarily need to be installed on the local machine for Eclipse GlassFish to recognize the container’s application type. Eclipse GlassFish 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, Eclipse GlassFish 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:

The container component code is comprised of the classes and interfaces that are listed in the following table. The table also provides a cross-reference to the listing of each class or interface.

Example 7-3 Annotation to Denote a Container’s Component

This example shows the code for defining a component of the Greeter container.

Example 7-4 Application Container Class

This example shows the Java language class GreeterAppContainer, which implements the ApplicationContainer interface.

Example 7-5 Container Class

This example shows the Java language class GreeterContainer, which implements the Container interface.