The asadmin supports many subcommands that are developed by different people. These guidelines are intended to help with getting consistent output across the various commands. 

Output Forms 

NOTE: This section describes the long term direction for command output forms. For the 3.1 release, these guidelines will only be partially implemented. Current list commands that take a verbose option will be changed to take long instead. Implementation of the guidelines beyond that will be on a case-by-case basis. 

Command output is controlled by several input options: terse, header (short form: h), output (short form: o), and long (short form: l).  The header, output and long options are intended for the various list commands, and they control whether a header is included in the output, which columns are output, and the list of columns, respectively. Each command that supports the output option has a default set of columns. With the long option, the default set of columns can be longer, possibly including all available columns. The long option is shorthand for an output option with more columns. When the terse option is used, the output is intended to be used by a program, so the header is turned off (unless it is explicitly requested using --header=true). 

1. If a command supports columnar output, it must support the header and output options. It may support the long option.
2. All columnar output is formatted so that each column is wide enough for the largest data item (or column heading) in that column plus two spaces. 
3. Column headings and data items are left aligned in the columns.
4. Column headings are in all uppercase with no spaces (because they are used with the output option.)
5. Columns are formatted without any column separators and there is no line between the column headings and the data.
6. The order of the columns listed in the output option determines the order in the output.
7. Columns may be designated as "key" fields, which causes the output to be sorted based on the order of the key fields (left to right, i.e., the data is sorted by the leftmost key column first, then the next key column, and so forth). 
8. Since the column separator is whitespace, data items that contain blanks can cause parsing problems for the output.  If possible, avoid blanks in data items, for example, by using dashes between words.  If a column must have blanks, make it the last column in default output. 
9. Column names are case insensitive when passed to the output option. The name of the column for the input is the same as the column heading in the output.
10. When a list has no items, then output a "Nothing to list" message if and only if column headings are turned on. If there are no column headings, then output nothing for an empty list.

A class, com.sun.enterprise.admin.util.ColumnFormatter in the admin-util.jar file, has been implemented to help with formatting in this way. Currently, it only formats data with column headings and it omits many of the features listed above (sorting, etc.).  This class will be expanded as more of the guidelines are implemented.

Here is an example of some forms of the list-instances command output:

list-instances --terse:

i1  running
i2  not-running

list-instances --terse --header=true

NAME  STATE
i1    running
i2    not-running

list-instances (default columns are name and state):

NAME  STATE
i1    running
i2    not-running
Command list-instances executed successfully.

list-instances -o name,host,port,cluster,state,uptime

NAME  HOST       PORT   CLUSTER  STATE        UPTIME
i1    localhost  24848  c1       running      1:37
i2    localhost  24849  c1       not-running  0:00
Command list-instances executed successfully.

The verbose option (short form: v) is only used for the non-list commands such as: start-domain,  start-cluster, start-local-instance, stop-cluster, version,  validate-multicast, backup-domain, and restore-domain. In these cases, the terse and verbose options should not be allowed together. 

Confirmation Messages

The asadmin command itself generates a "Command such-and-such executed successfully." message (unless the terse option is used), and the exit code of the command indicates success for failure.  Therefore, a command must not output its own confirmation message that an operation succeeded, unless that message provides additional information. For example, the create-instance command outputs the list of port assignments that were made for the instance. However, the command stop-instance should not output a message saying "The instance, i1, was stopped." This message does not add any additional information to the message that is already output by asadmin. 

Blank Lines

Command output must not have blank lines in a list, especially at the end. This is especially important for terse output so that programs that consume the output of a command do not have to deal with blank lines. 

States

1. Use lowercase.
2. Use the following values: 
   1. running 
   2. not-running 
   3. running:requires-restart (a more detailed form of running, meaning that a configuration change has been made but not applied to the instance, so a restart is required to get the instance to see that change)
   4. running:started-at:TIME (a more detailed form of running, with an indication of the time that the server was started)
   5. running:rejoined-at:TIME (a more detailed form of running, with an indication of when the server restarted after a brief outage)
   6. not-running:stopped-at:TIME (a more detailed form of not running, with an indication of the time that the server was stopped)
   7. not-running:failed-at:TIME (a more detail form of not running, with an indication of the time that the server failed)

TODO: need to add more states for quiesed

Question: should we use "up" and "down" rather than "running" and "not-running" (or operational/nonoperational, functional/nonfunctional)

No Class Names in Output

No command output, including that for error messages, should reference any Java package or class names, unless they are user entered values. This information should be in a server.log entry.  For example, the following output is incorrect:

remote failure: Error during deployment : org.jvnet.hk2.config.ValidationException: Constraints for this bean violated. 
Message = ref must match "[\p{L}\p{N}_][\p{L}\p{N}\-_./;:#]*"
Command deploy failed.

because it references the org.jvnet.hk2.config.ValidationException. The text from the ValidationException and name of the exception can be output to the server.log file, but a user friendly message should be output from the command, potentially with a hint to check the server log for more details. 

An example of a user entered value is a class name that is input to the create-jdbc-connection-pool command via the driverclassname argument. The value that the user entered can be echoed back to the user in an error message, list output, etc.

Hidden Commands and Options

No command output should mention a hidden command or use a hidden option. For example, if the _delete-instance-filesystem command that is run by delete-instance fails, the error message must not tell the user that the _delete-instance-filesystem failed or request the user to run the _delete-instance-filesystem command. The server.log file message should have the details about what command actually failed with exception messages, if any. 

Compatibility vs. Consistency

For 3.1 only, consistency of command output is preferred over backward compatibility of output. For example, the 3.0 list-domains command has output like this: 

Name: domain1 Status: Not Running
Command list-domains executed successfully.

This is inconsistent with the list-instances, list-clusters, and list-nodes commands in 3.1, and it is inconsistent with the 2.1.1 list-domains command. So in 3.1, the list-domains output has been changed to the following:

domain1 running
Command list-domains executed successfully.

Terse output should be changed in compatible ways, because programs may be depending on the output. 

Internationalization

All of the output from asadmin subcommands must be based on format strings in properties files so that it can be localized. This is the case even for terse output that is intended for programs. When a program is reading the output from asadmin, it is expected that the developer has set up the environment for asadmin so that it produces output in the language that the program is expecting. The one exception to this is column headings.  See the paragraph below for more details.

The input for asadmin is not localized, e.g., the create-instance command is called "create-instance" and the host option is called "host" in all locales. This means that commands that output recommendations about other commands to execute generate the output for the command itself the way that the input is expected. The input for column names in the output option is not localized. This is the reason why column names are also not localized on output.

Open Issues

• What type of debugging information should be printed out when user sets AS_DEBUG?
• Should there be guidelines about what goes to stderr vs. stdout?