JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle GlassFish Server 3.1 Add-On Component Development Guide
search filter icon
search icon

Document Information


1.   Introduction to the Development Environment for GlassFish Server Add-On Components

2.  Writing HK2 Components

3.  Extending the Administration Console

4.  Extending the asadmin Utility

About the Administrative Command Infrastructure of GlassFish Server

Adding an asadmin Subcommand

Representing an asadmin Subcommand as a Java Class

Specifying the Name of an asadmin Subcommand

Ensuring That an AdminCommand Implementation Is Stateless

Example of Adding an asadmin Subcommand

Adding Parameters to an asadmin Subcommand

Representing a Parameter of an asadmin Subcommand

Identifying a Parameter of an asadmin Subcommand

Specifying Whether a Parameter Is an Option or an Operand

Specifying the Name of an Option

Specifying the Long Form of an Option Name

Specifying the Short Form of an Option Name

Specifying the Acceptable Values of a Parameter

Specifying the Default Value of a Parameter

Specifying Whether a Parameter Is Required or Optional

Example of Adding Parameters to an asadmin Subcommand

Making asadmin Subcommands Cluster-Aware

Specifying Allowed Targets

The Target Utility

Specifying asadmin Subcommand Execution

Subcommand Preprocessing and Postprocessing

Running a Command from Another Command

Adding Message Text Strings to an asadmin Subcommand

Enabling an asadmin Subcommand to Run

Setting the Context of an asadmin Subcommand

Changing the Brand in the GlassFish Server CLI

Examples of Extending the asadmin Utility

Implementing Create, Delete, and List Commands Using Annotations

Command Patterns


The @Create Annotation

The @Delete Annotation

The @Listing Annotation

Create Command Decorators

Delete Command Decorators

Specifying Command Execution

Using Multiple Command Annotations

5.  Adding Monitoring Capabilities

6.  Adding Configuration Data for a Component

7.  Adding Container Capabilities

8.  Creating a Session Persistence Module

9.  Packaging, Integrating, and Delivering an Add-On Component

A.  Integration Point Reference


Making asadmin Subcommands Cluster-Aware

The GlassFish Server asadmin command framework provides support for making asadmin subcommands work properly in a clustered environment or with standalone server instances. A command that changes a configuration is first executed on the domain administration server (DAS) and then executed on each of the server instances affected by the change. Annotations provided by the framework determine the instances on which the command should be replicated and executed. Commands that do not change a configuration need not be executed on the DAS at all, but only on the necessary instances. The framework provides support for collecting the output from the instances and sending a report back to the user.

Subcommands in a multi-instance environment can accept a --target option to specify the cluster or instance on which the command acts. From within the command, the Target utility allows the command to determine information about where it is running. For some commands, it may be desirable to have a main command that runs on the DAS and supplemental preprocessing or postprocessing commands that run on the instances.

The following topics are addressed here:

Specifying Allowed Targets

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 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:

    String target;

The Target Utility

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:

@Inject Target targetUtil;

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:

Config c = targetUtil.getConfig(target);

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

Specifying asadmin Subcommand Execution

By default, all asadmin subcommands are automatically replicated and run on the DAS and all GlassFish Server 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:

Subcommand Preprocessing and Postprocessing

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:

public DeployCommand implements AdminCommand {
//Do Actual Deployment

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

public DeploymentSupplementalCommand implements AdminCommand {
//Do logic that happens after deployment has been done

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

@Service(name = "create-local-instance")
public final class CreateLocalInstanceCommand implements AdminCommand {
//Do local instance creation

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

public CreateLocalInstanceSupplementalCommand implements AdminCommand {
//Change MQ/LB properties here

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(value="mycommand", on=Supplemental.Timing.Before)

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

Running a Command from Another Command

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.