Skip Navigation Links | |
Exit Print View | |
Oracle GlassFish Server 3.1 Add-On Component Development Guide |
1. Introduction to the Development Environment for GlassFish Server Add-On Components
3. Extending the Administration Console
4. Extending the asadmin Utility
About the Administrative Command Infrastructure of GlassFish Server
Representing an asadmin Subcommand as a Java Class
Specifying the Name of 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 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
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
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:
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.
To specify the name of the subcommand, set the name element of the @Service annotation to the name.
Note - 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.1-3.1.1 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:
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 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 { … }