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
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
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
The parameters of an asadmin subcommand are the options and operands of the subcommand.
Options control how the asadmin utility performs a subcommand.
Operands are the objects on which a subcommand acts. For example, the operand of the start-domain(1) subcommand is the domain that is to be started.
The following topics are addressed here:
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:
To provide data encapsulation for the parameter
To add code for validating the parameter before the property is set
Identifying a parameter of an asadmin subcommand enables GlassFish Server to perform the following operations at runtime on the parameter:
Validation. The GlassFish Server determines whether all required parameters are specified and returns an error if any required parameter is omitted.
Injection. Before the subcommand runs, the GlassFish Server injects each parameter into the required field or method before the subcommand is run.
Usage message generation. The GlassFish Server uses reflection to obtain the list of parameters for a subcommand and to generate the usage message from this list.
Localized string display. If the subcommand supports internationalization and if localized strings are available, the GlassFish Server can automatically obtain the localized strings for a subcommand and display them to the user.
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:
If the parameter is an option, the user must specify the option with the parameter name.
If the parameter is an operand, the user may omit the parameter name.
To specify whether a parameter is an option or an operand, set the primary element of the @Param annotation as follows:
If the parameter is an option, set the primary element to false. This value is the default.
If the parameter is an operand, set the primary element to true.
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:
The short form of an option name has a single dash (-) followed by a single character.
The long form of an option name has two dashes (--) followed by an option word.
For example, the short form and the long form of the name of the option for specifying terse output are as follows:
Short form: -m
Long form: --monitor
Note - Option names are case-sensitive.
To specify the long form of an option name, set the name element of the @Param annotation to a string that specifies the name. If you do not set this element, the default name depends on how you represent the option.
If you represent the option as a field, the default name is the field name.
If you represent the option as the property of a JavaBeans specification setter method, the default name is the property name from the setter method name. For example, if the setter method setPassword is associated with an option, the property name and the option name are both password.
To specify the short form of an option name, set the shortName element of the @Param annotation to a single character that specifies the short form of the parameter. The user can specify this character instead of the full parameter name, for example -m instead of --monitor. If you do not set this element, the option has no short form.
When a user runs the subcommand, the GlassFish Server 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. If you do not set this element, 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:
If the parameter is required, the subcommand returns an error.
If the parameter is optional, the subcommand runs successfully.
To specify whether a parameter is optional or required, set the optional element of the @Param annotation as follows:
If the parameter is required, set the optional element to false. This value is the default.
If the parameter is optional, set the optional element to true.
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.
|
... import org.glassfish.api.Param; ... { … @Param String originator; @Param(name="description", optional=true) … String mycontainerDescription @Param (acceptableValues="true,false", defaultValue="false", optional=true) String enabled @Param(primary=true) String containername; … }