Adding an asadmin Subcommand

An asadmin subcommand identifies the operation or task that a user is to perform. Adding an asadmin subcommand enables the user to perform these tasks and operations through the asadmin utility.

The following topics are addressed here:

• 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

Representing an asadmin Subcommand as a Java Class

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:

• The implementations are eligible for resource injection and resource extraction.

• The implementations are location independent, provided that the component that contains them is made known to the GlassFish Server runtime.

  For information about how to make a component known to the GlassFish Server runtime, see Integrating an Add-On Component With GlassFish Server.

Specifying the Name of an asadmin Subcommand

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

Subcommand names are case-sensitive.

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

• For subcommands that create an object of a particular type, use the name create-object.

• For subcommands that delete an object of a particular type, use the name delete-object.

• For subcommands that list all objects of a particular type, use the name list-objects.

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

• create-http-listener

• delete-http-listener

• list-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(1) subcommand. For a complete list of asadmin subcommands that are supplied in GlassFish Server distributions, see Oracle GlassFish Server 3.0.1 Reference Manual.

Ensuring That an AdminCommand Implementation Is Stateless

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:

• To instantiate the subcommand for each lookup, set the scope to PerLookup.class.

• To instantiate the subcommand only once for each session, set the scope to Singleton.

Example of Adding an asadmin Subcommand

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.

package com.example.mycontainer;

import org.glassfish.api.admin.AdminCommand;
...
import org.jvnet.hk2.annotations.Service;
...
import org.jvnet.hk2.annotations.Scoped;
import org.jvnet.hk2.component.PerLookup;

/**
 * Sample subcommand
 */
@Service(name="create-mycontainer")
@Scoped(PerLookup.class)
public Class CreateMycontainer implements AdminCommand {
…
}