Integrating JBI Commands into Application Server Admin CLI

__

I. Introduction__

In GlassFish V2, there will be a set of new JBI commands added to CLI, asadmin. Since JBI will be a permanent container in GlassFish, the decision is to tightly integrate the JBI commands in asadmin.

__

II. CLI Source Code Location__

The new JBI commands will be located in the same directory as GlassFish commands. The GlassFish commands module is in:
admin-cli/commands/src/com/sun/enterprise/cli/commands

Please see:
[https://glassfish.java.net/javaee5/admin-cli/admin-cli.html

The CLI Framework is located in admin-cli/framework. This framework is CLIP compliant. Since JBI commands are integrated in asadmin, the same framework will be used. The CLI Framework mandates the commands module to provide a descriptor file describing the options and commands. In GlassFish, this descriptor file is named CLIDescriptor.xml and it's located in the same directory as the commands module. The new JBI commands shall be added to the same CLIDescriptor.xml file shared by the GlassFish commands.
See CLI Framework Cookbook to get an idea on how to create commands using the CLI Framework. This document is fairly accurate but may need some update. Please follow the instruction on this document to create the JBI commands.

Before adding any new options, please make sure if the options are already defined.

__

IV. Changes to Build or asadmin script__

At the moment we don't anticipate any new libraries to be added to the build or asadmin script to build/execute JBI commands. Let admin@glassfish.java.net review the changes to the code. See http://wiki.java.net/bin/view/Projects/AdminDeveloperResources#CodeReviewProcess

__

V. Manpage Location__

The asadmin manpages are located in appserv-docs/sman/man1. All new SGML manpages for the JBI commands will be saved in the same location. The script, "convertSGML2Text" is used to convert the SGML files to text and the build script in admin-cli will package the text version of the manpages in admin-cli.jar.

__

VI. Unit Tests__

The unit tests are written in JUnit and they are located in admin-cli/commands/tests. Please provide unit tests for the new JBI command classes.
Steps to compile and execute the unit tests:

1. cd to admin-cli/commands
2. ant -f commandsbuild.xml -Dcut=AllTest test

__

VII. New JBI Commands with Detailed Synopsis__

The "jbi" in the name of the commands is still being debated. We will finalize this soon. We should make an attempt to make use of the generic names in a generic way. This is always a challenge, but we should try to use that model. So, we should try to reuse "start", "stop", "enable", "disable", "shutdown", "deploy", "undeploy" in the same generic fashion as far as possible. It won't be possible right away and to be pragmatic, we can start with specific names like "deploy-service-assembly" etc. because reusing the same command might become unwieldy if there are significant differences in options.

Please document the JBI commands, descriptions, all options, types of options, default values, operands etc as thorough as possible since the tech writer will use this information to write the manpages.

Use the following template to document the new JBI commands: AGlossaryOfNewCommandsWithDetailedSynopsis

As a reference, see http://www.glassfishwiki.org/gfwiki/attach/GlassFishAdminReferences/sjsas9_cli_commands.html.