com.sun.enterprise.admin.cli
Class CLICommand

java.lang.Object
  com.sun.enterprise.admin.cli.CLICommand

All Implemented Interfaces:

org.jvnet.hk2.component.PostConstruct

Direct Known Subclasses:

ExportCommand, HelpCommand, ListCommandsCommand, LocalServerCommand, MonitorCommand, MultimodeCommand, RemoteCommand, UnsetCommand, VersionCommand

@Contract
@Scoped(value=org.jvnet.hk2.component.PerLookup.class)
public abstract class CLICommand
extends java.lang.Object
implements org.jvnet.hk2.component.PostConstruct

Base class for a CLI command. An instance of a subclass of this class is created using the getCommand method with the name of the command and the information about its environment.

A command is executed with a list of arguments using the execute method. The implementation of the execute method in this class saves the arguments in the protected argv field, then calls the following protected methods in order: prepare, parse, validate, and executeCommand. A subclass must implement the prepare method to initialize the metadata that specified the valid options for the command, and the executeCommand method to actually perform the command. The parse and validate method may also be overridden if needed. Or, the subclass may override the execute method and provide the complete implementation for the command, including option parsing.

Author:

Bill Shannon

Field Summary

protected java.lang.String[]	argv The command line arguments for this execution.
protected CommandModel	commandModel The metadata describing the command's options and operands.
static int	CONNECTION_ERROR
protected Environment	env The environment for the command.
static int	ERROR
private static org.jvnet.hk2.component.InjectionManager	injectionMgr
static int	INVALID_COMMAND_ERROR
protected static java.util.logging.Logger	logger
protected java.lang.StringBuilder	metadataErrors
protected java.lang.String	name The name of the command.
protected java.util.List<java.lang.String>	operands The operands parsed from the command line.
protected ParameterMap	options The options parsed from the command line.
private static java.lang.String	PACKAGE_NAME
protected java.util.Map<java.lang.String,java.lang.String>	passwords The passwords read from the password file.
protected ProgramOptions	programOpts The program options for the command.
private static LocalStringsImpl	strings
static int	SUCCESS
private static java.util.Map<java.lang.String,java.lang.String>	systemProps
private static java.util.Set<java.lang.String>	unsupported
private static java.lang.String	UNSUPPORTED_CMD_FILE_NAME
static int	WARNING

Constructor Summary

protected	CLICommand() Constructor used by subclasses when instantiated by HK2.
protected	CLICommand(java.lang.String name, ProgramOptions programOpts, Environment env) Constructor used by subclasses to save the name, program options, and environment information into corresponding protected fields.

Method Summary

protected boolean	checkHelp() Check if the current request is a help request, either because --help was specified as a programoption or a command option.
private static void	checkUnsupportedLegacyCommand(java.lang.String cmd) If this is an unsupported command, throw an exception.
private java.lang.String	echoCommand() Return a string representing the command line used with this command.
int	execute(java.lang.String... argv) Execute this command with the given arguemnts.
protected abstract int	executeCommand() Execute the command using the options in options and the operands in operands.
private static void	file2Set(java.lang.String file, java.util.Set<java.lang.String> set) Read the named resource file and add the first token on each line to the set.
private java.lang.String	generateUsageText()
protected boolean	getBooleanOption(java.lang.String name) Get a boolean option value, that might come from the command line or from the environment.
static CLICommand	getCommand(org.jvnet.hk2.component.Habitat habitat, java.lang.String name) Get a CLICommand object representing the named command.
java.io.BufferedReader	getManPage() Return a BufferedReader for the man page for this command, or null if not found.
java.lang.String	getName() Return the name of this command.
protected CommandModel.ParamModel	getOperandModel() Get the ParamModel that corresponds to the operand (primary parameter).
protected java.lang.String	getOption(java.lang.String name) Get an option value, that might come from the command line or from the environment.
protected java.lang.String	getPassword(CommandModel.ParamModel opt, java.lang.String defaultPassword, boolean create) Get a password for the given option.
ProgramOptions	getProgramOptions() Returns the program options associated with this command.
protected java.util.Map<java.lang.String,java.lang.String>	getSystemProperties() Return all the system properties and properties set in asenv.conf.
protected java.lang.String	getSystemProperty(java.lang.String name) Return the named system property, or property set in asenv.conf.
java.lang.String	getUsage() Get the usage text.
private void	initializeCommandPassword() Initialize all the passwords required by the command.
protected void	initializeLogger() Initialize the state of the logger based on any program options.
protected void	initializePasswords() Initialize the passwords field based on the password file specified in the program options, and initialize the program option's password if available in the password file.
protected void	inject() Inject this instance with the final values of all the command parameters.
private static java.lang.String	lc(java.lang.String s)
protected static boolean	ok(java.lang.String s)
protected void	parse() The parse method sets the options and operands fields based on the content of the command line arguments.
void	postConstruct() Initialize the logger after being instantiated by HK2.
protected void	prepare() The prepare method must ensure that the commandModel field is set.
protected void	prevalidate() The prevalidate method supplies missing options from the environment.
protected void	printExceptionStackTrace(java.lang.Throwable e) Prints the exception message with level as FINER.
protected void	processProgramOptions() If the program options haven't already been set, parse them on the command line and remove them from the command line.
static java.lang.String	quote(java.lang.String value) Quote a value, if the value contains any special characters.
protected java.lang.String	readPassword(java.lang.String prompt) Display the given prompt and read a password without echoing it.
java.lang.String	toString()
protected java.util.Collection<CommandModel.ParamModel>	usageOptions() Subclasses can override this method to supply additional or different options that should be part of the usage text.
protected void	validate() The validate method can be used by a subclass to validate that the type and quantity of parameters and operands matches the requirements for this command.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ERROR

public static final int ERROR

See Also:

Constant Field Values

CONNECTION_ERROR

public static final int CONNECTION_ERROR

See Also:

Constant Field Values

INVALID_COMMAND_ERROR

public static final int INVALID_COMMAND_ERROR

See Also:

Constant Field Values

SUCCESS

public static final int SUCCESS

See Also:

Constant Field Values

WARNING

public static final int WARNING

See Also:

Constant Field Values

unsupported

private static final java.util.Set<java.lang.String> unsupported

UNSUPPORTED_CMD_FILE_NAME

private static final java.lang.String UNSUPPORTED_CMD_FILE_NAME

See Also:

Constant Field Values

PACKAGE_NAME

private static final java.lang.String PACKAGE_NAME

See Also:

Constant Field Values

strings

private static final LocalStringsImpl strings

systemProps

private static final java.util.Map<java.lang.String,java.lang.String> systemProps

logger

protected static final java.util.logging.Logger logger

injectionMgr

private static final org.jvnet.hk2.component.InjectionManager injectionMgr

name

protected java.lang.String name

The name of the command. Initialized in the constructor.

programOpts

protected ProgramOptions programOpts

The program options for the command. Initialized in the constructor.

env

protected Environment env

The environment for the command. Initialized in the constructor.

argv

protected java.lang.String[] argv

The command line arguments for this execution. Initialized in the execute method.

commandModel

protected CommandModel commandModel

The metadata describing the command's options and operands.

metadataErrors

protected java.lang.StringBuilder metadataErrors

options

protected ParameterMap options

The options parsed from the command line. Initialized by the parse method. The keys are the parameter names from the command model, not the "forced to all lower case" names that are presented to the user.

operands

protected java.util.List<java.lang.String> operands

The operands parsed from the command line. Initialized by the parse method.

passwords

protected java.util.Map<java.lang.String,java.lang.String> passwords

The passwords read from the password file. Initialized by the initializeCommandPassword method.

Constructor Detail

CLICommand

protected CLICommand()

Constructor used by subclasses when instantiated by HK2. ProgramOptions and Environment are injected. name is set here.

CLICommand

protected CLICommand(java.lang.String name,
                     ProgramOptions programOpts,
                     Environment env)

Constructor used by subclasses to save the name, program options, and environment information into corresponding protected fields. Finally, this constructor calls the initializeLogger method.

Method Detail

getCommand

public static CLICommand getCommand(org.jvnet.hk2.component.Habitat habitat,
                                    java.lang.String name)
                             throws CommandException

Get a CLICommand object representing the named command.

Throws:

CommandException

postConstruct

public void postConstruct()

Initialize the logger after being instantiated by HK2.

Specified by:

postConstruct in interface org.jvnet.hk2.component.PostConstruct

execute

public int execute(java.lang.String... argv)
            throws CommandException

Execute this command with the given arguemnts. The implementation in this class saves the passed arguments in the argv field and calls the initializePasswords method. Then it calls the prepare, parse, and validate methods, finally returning the result of calling the executeCommand method. Note that argv[0] is the command name.

Throws:

CommandException - if execution of the command fails

CommandValidationException - if there's something wrong with the options or arguments

getName

public java.lang.String getName()

Return the name of this command.

getProgramOptions

public ProgramOptions getProgramOptions()

Returns the program options associated with this command.

Returns:

the command's program options

getManPage

public java.io.BufferedReader getManPage()

Return a BufferedReader for the man page for this command, or null if not found.

getUsage

public java.lang.String getUsage()

Get the usage text.

Returns:

usage text

generateUsageText

private java.lang.String generateUsageText()

usageOptions

protected java.util.Collection<CommandModel.ParamModel> usageOptions()

Subclasses can override this method to supply additional or different options that should be part of the usage text. Most commands will never need to do this, but the create-domain command uses it to include the --user option as a required option.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

echoCommand

private java.lang.String echoCommand()

Return a string representing the command line used with this command.

quote

public static java.lang.String quote(java.lang.String value)

Quote a value, if the value contains any special characters.

Parameters:

value - value to be quoted

Returns:

the possibly quoted value

processProgramOptions

protected void processProgramOptions()
                              throws CommandException

If the program options haven't already been set, parse them on the command line and remove them from the command line. Subclasses should call this method in their prepare method after initializing commandOpts (so usage is available on failure) if they want to allow program options after the command name. Currently RemoteCommand does this, as well as the local commands that also need to talk to the server.

Throws:

CommandException

initializeLogger

protected void initializeLogger()

Initialize the state of the logger based on any program options.

initializePasswords

protected void initializePasswords()
                            throws CommandException

Initialize the passwords field based on the password file specified in the program options, and initialize the program option's password if available in the password file.

Throws:

CommandException

prepare

protected void prepare()
                throws CommandException

The prepare method must ensure that the commandModel field is set.

Throws:

CommandException

parse

protected void parse()
              throws CommandException

The parse method sets the options and operands fields based on the content of the command line arguments. If the program options say this is a help request, we set options and operands as if "--help" had been specified.

Throws:

CommandException - if execution of the command fails

CommandValidationException - if there's something wrong with the options or arguments

checkHelp

protected boolean checkHelp()
                     throws CommandException

Check if the current request is a help request, either because --help was specified as a programoption or a command option. If so, get the man page using the getManPage method, copy the content to System.out, and return true. Otherwise return false. Subclasses may override this method to perform a different check or to use a different method to display the man page. If this method returns true, the validate and executeCommand methods won't be called.

Throws:

CommandException

prevalidate

protected void prevalidate()
                    throws CommandException

The prevalidate method supplies missing options from the environment. It also supplies passwords from the password file or prompts for them if interactive.

Throws:

CommandException - if execution of the command fails

CommandValidationException - if there's something wrong with the options or arguments

inject

protected void inject()
               throws CommandException

Inject this instance with the final values of all the command parameters.

Throws:

CommandException - if execution of the command fails

CommandValidationException - if there's something wrong with the options or arguments

validate

protected void validate()
                 throws CommandException

The validate method can be used by a subclass to validate that the type and quantity of parameters and operands matches the requirements for this command.

Throws:

CommandException - if execution of the command fails

CommandValidationException - if there's something wrong with the options or arguments

executeCommand

protected abstract int executeCommand()
                               throws CommandException

Execute the command using the options in options and the operands in operands.

Returns:

the exit code

Throws:

CommandException - if execution of the command fails

CommandValidationException - if there's something wrong with the options or arguments

initializeCommandPassword

private void initializeCommandPassword()
                                throws CommandException

Initialize all the passwords required by the command.

Throws:

CommandException

getPassword

protected java.lang.String getPassword(CommandModel.ParamModel opt,
                                       java.lang.String defaultPassword,
                                       boolean create)
                                throws CommandValidationException

Get a password for the given option. First, look in the passwords map. If found, return it. If not found, and not required, return null; If not interactive, return null. Otherwise, prompt for the password. If create is true, prompt twice and compare the two values to make sure they're the same. If the password meets other validity criteria (i.e., length) returns the password. If defaultPassword is not null, "Enter" selects this default password, which is returned.

Throws:

CommandValidationException

readPassword

protected java.lang.String readPassword(java.lang.String prompt)

Display the given prompt and read a password without echoing it. Returns null if no console available.

getOperandModel

protected CommandModel.ParamModel getOperandModel()

Get the ParamModel that corresponds to the operand (primary parameter). Return null if none.

getOption

protected java.lang.String getOption(java.lang.String name)

Get an option value, that might come from the command line or from the environment. Return the default value for the option if not otherwise specified.

getBooleanOption

protected boolean getBooleanOption(java.lang.String name)

Get a boolean option value, that might come from the command line or from the environment.

getSystemProperty

protected java.lang.String getSystemProperty(java.lang.String name)

Return the named system property, or property set in asenv.conf.

getSystemProperties

protected java.util.Map<java.lang.String,java.lang.String> getSystemProperties()

Return all the system properties and properties set in asenv.conf. The returned Map may not be modified.

checkUnsupportedLegacyCommand

private static void checkUnsupportedLegacyCommand(java.lang.String cmd)
                                           throws CommandException

If this is an unsupported command, throw an exception.

Throws:

CommandException

printExceptionStackTrace

protected void printExceptionStackTrace(java.lang.Throwable e)

Prints the exception message with level as FINER.

Parameters:

e - the exception object to print

ok

protected static boolean ok(java.lang.String s)

lc

private static java.lang.String lc(java.lang.String s)

file2Set

private static void file2Set(java.lang.String file,
                             java.util.Set<java.lang.String> set)

Read the named resource file and add the first token on each line to the set. Skip comment lines.