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

Preface

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

Resolvers

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

Index

Adding Parameters to an asadmin Subcommand

The parameters of an asadmin subcommand are the options and operands of the subcommand.

The following topics are addressed here:

Representing a Parameter of an asadmin Subcommand

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

Identifying a parameter of an asadmin subcommand enables GlassFish Server 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.

Specifying Whether a Parameter Is an Option or an Operand

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:

Specifying the Name of an Option

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:


Note - Option names are case-sensitive.


Specifying the Long Form of an Option Name

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.

Specifying the Short Form of an Option Name

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.

Specifying the Acceptable Values of a Parameter

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.

Specifying the Default Value of a Parameter

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.

Specifying Whether a Parameter Is Required or Optional

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:

Example of Adding Parameters to an asadmin Subcommand

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.

Name
Represented As
Acceptable Values
Default Value
Optional or Required
Short Name
Option or Operand
--originator
A field that is named originator
Any character string
None defined
Required
None
Option
--description
A field that is named mycontainerDescription
Any character string
None defined
Optional
None
Option
--enabled
A field that is named enabled
true or false
false
Optional
None
Option
--containername
A field that is named containername
Any character string
None defined
Required
None
Operand
...
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;
…
}