Package com.sun.enterprise.admin.cli

Class CLICommand

java.lang.Object
com.sun.enterprise.admin.cli.CLICommand
All Implemented Interfaces:
org.glassfish.hk2.api.PostConstruct
Direct Known Subclasses:
ExportCommand, HelpCommand, ListCommandsCommand, LoginCommand, MultimodeCommand, RemoteCLICommand, RemoteCommand, UnsetCommand, VersionCommand
@Contract @PerLookup public abstract class CLICommand extends Object implements org.glassfish.hk2.api.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

    Fields
    Modifier and Type
    Field
    Description
    protected String[]
    argv
    The command line arguments for this execution.
    protected org.glassfish.api.admin.CommandModel
    commandModel
    The metadata describing the command's options and operands.
    static final int
    CONNECTION_ERROR
     
    protected Environment
    env
    The environment for the command.
    static final int
    ERROR
     
    static final int
    INVALID_COMMAND_ERROR
     
    protected static final Logger
    logger
     
    protected StringBuilder
    metadataErrors
     
    protected String
    name
    The name of the command.
    protected List<String>
    operands
    The operands parsed from the command line.
    protected org.glassfish.api.admin.ParameterMap
    options
    The options parsed from the command line.
    protected Map<String,String>
    passwords
    The passwords read from the password file.
    protected ProgramOptions
    programOpts
    The program options for the command.
    static final int
    SUCCESS
     
    static final int
    WARNING
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    CLICommand()
    Constructor used by subclasses when instantiated by HK2.
    protected
    CLICommand(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

    Modifier and Type
    Method
    Description
    protected boolean
    checkHelp()
    Check if the current request is a help request, either because --help was specified as a program option or a command option.
    protected void
    checkSanity()
    Does some basic checks of the current environment to verify that the command can work on the system.
    int
    execute(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.
    BufferedReader
    expandManPage(Reader r)
    Return a man page for this command that has the tokens substituted
    protected boolean
    getBooleanOption(String name)
    Get a boolean option value, that might come from the command line or from the environment.
    String
    getBriefCommandUsage()
     
    static CLICommand
    getCommand(CLIContainer cLIContainer, String name)
     
    static CLICommand
    getCommand(org.glassfish.hk2.api.ServiceLocator serviceLocator, String name)
    Get a CLICommand object representing the named command.
    static String
    getCommandScope()
    Return the command scope for this command.
    String
    getCommandUsage()
    Get the usage text for the command.
    BufferedReader
    getManPage()
    Return a BufferedReader for the man page for this command, or null if not found.
    String
    getName()
    Return the name of this command.
    protected org.glassfish.api.admin.CommandModel.ParamModel
    getOperandModel()
    Get the ParamModel that corresponds to the operand (primary parameter).
    protected String
    getOption(String name)
    Get an option value, that might come from the command line or from the environment.
    protected List<String>
    getOptions(String name)
    Get option values, that might come from the command line or from the environment.
    protected char[]
    getPassword(String paramname, String localizedPrompt, String localizedPromptConfirm, boolean create)
     
    protected char[]
    getPassword(org.glassfish.api.admin.CommandModel.ParamModel opt, String defaultPassword, boolean create)
    Get a password for the given option.
    ProgramOptions
    getProgramOptions()
    Returns the program options associated with this command.
    protected Map<String,String>
    getSystemProperties()
    Return all the system properties and properties set in asenv.conf.
    protected String
    getSystemProperty(String name)
    Return the named system property, or property set in asenv.conf.
    String
    getUsage()
    Get the usage text for the subcommand.
    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.
    protected static boolean
    ok(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
    processProgramOptions()
    If the program options haven't already been set, parse them on the command line and remove them from the command line.
    static String
    quote(String value)
    Quote a value, if the value contains any special characters.
    protected char[]
    readPassword(String prompt)
    Display the given prompt and read a password without echoing it.
    static void
    setCommandScope(String ctx)
    Set the command scope for this command.
    String
    toString()
     
    protected Collection<org.glassfish.api.admin.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 Details

    • ERROR

      public static final int ERROR
      See Also:

    • CONNECTION_ERROR

      public static final int CONNECTION_ERROR
      See Also:

    • INVALID_COMMAND_ERROR

      public static final int INVALID_COMMAND_ERROR
      See Also:

    • SUCCESS

      public static final int SUCCESS
      See Also:

    • WARNING

      public static final int WARNING
      See Also:

    • logger

      protected static final Logger logger

    • name

      protected String name
      The name of the command. Initialized in the constructor.

    • programOpts

      @Inject protected ProgramOptions programOpts
      The program options for the command. Initialized in the constructor.

    • env

      @Inject protected Environment env
      The environment for the command. Initialized in the constructor.

    • argv

      protected String[] argv
      The command line arguments for this execution. Initialized in the execute method.

    • commandModel

      protected org.glassfish.api.admin.CommandModel commandModel
      The metadata describing the command's options and operands.

    • metadataErrors

      protected StringBuilder metadataErrors

    • options

      protected org.glassfish.api.admin.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 List<String> operands
      The operands parsed from the command line. Initialized by the parse method.

    • passwords

      protected Map<String,String> passwords
      The passwords read from the password file. Initialized by the initializeCommandPassword method.

  • Constructor Details

    • CLICommand

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

    • CLICommand

      protected CLICommand(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 Details

    • getCommand

      public static CLICommand getCommand(org.glassfish.hk2.api.ServiceLocator serviceLocator, String name) throws org.glassfish.api.admin.CommandException
      Get a CLICommand object representing the named command.
      Throws:
      org.glassfish.api.admin.CommandException

    • getCommand

      public static CLICommand getCommand(CLIContainer cLIContainer, String name) throws org.glassfish.api.admin.CommandException
      Throws:
      org.glassfish.api.admin.CommandException

    • postConstruct

      public void postConstruct()
      Initialize the logger after being instantiated by HK2.
      Specified by:
      postConstruct in interface org.glassfish.hk2.api.PostConstruct

    • execute

      public int execute(String... argv) throws org.glassfish.api.admin.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:
      org.glassfish.api.admin.CommandException - if execution of the command fails
      org.glassfish.api.admin.CommandValidationException - if there's something wrong with the options or arguments

    • getName

      public String getName()
      Return the name of this command.

    • getCommandScope

      public static String getCommandScope()
      Return the command scope for this command. The command scope is a name space in which commands are defined. Command clients can specify a scope to use in looking up a command. Currently this is only used for remote commands. By default, the context is null.

    • setCommandScope

      public static void setCommandScope(String ctx)
      Set the command scope for this command.

    • getProgramOptions

      public ProgramOptions getProgramOptions()
      Returns the program options associated with this command.
      Returns:
      the command's program options

    • getManPage

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

    • expandManPage

      public BufferedReader expandManPage(Reader r)
      Return a man page for this command that has the tokens substituted

    • getUsage

      public String getUsage()
      Get the usage text for the subcommand. This method shows the details for the subcommand options but does not provide details about the command options.
      Returns:
      usage text

    • usageOptions

      protected Collection<org.glassfish.api.admin.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.

    • getCommandUsage

      public String getCommandUsage()
      Get the usage text for the command. This usage text shows the details of the command options but does not show the details for the subcommand options. The subcommand argument is used to fill in the subcommand name in the usage text.
      Returns:
      usage text for the command

    • getBriefCommandUsage

      public String getBriefCommandUsage()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • quote

      public static String quote(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 org.glassfish.api.admin.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:
      org.glassfish.api.admin.CommandException

    • initializeLogger

      protected void initializeLogger()
      Initialize the state of the logger based on any program options.

    • initializePasswords

      protected void initializePasswords() throws org.glassfish.api.admin.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:
      org.glassfish.api.admin.CommandException

    • prepare

      protected void prepare() throws org.glassfish.api.admin.CommandException
      The prepare method must ensure that the commandModel field is set.
      Throws:
      org.glassfish.api.admin.CommandException

    • parse

      protected void parse() throws org.glassfish.api.admin.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:
      org.glassfish.api.admin.CommandException - if execution of the command fails
      org.glassfish.api.admin.CommandValidationException - if there's something wrong with the options or arguments

    • checkSanity

      protected void checkSanity()
      Does some basic checks of the current environment to verify that the command can work on the system. Can produce warnings, errors or throw exceptions.

    • checkHelp

      protected boolean checkHelp() throws org.glassfish.api.admin.CommandException
      Check if the current request is a help request, either because --help was specified as a program option 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:
      org.glassfish.api.admin.CommandException

    • prevalidate

      protected void prevalidate() throws org.glassfish.api.admin.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:
      org.glassfish.api.admin.CommandException - if execution of the command fails
      org.glassfish.api.admin.CommandValidationException - if there's something wrong with the options or arguments

    • inject

      protected void inject() throws org.glassfish.api.admin.CommandException
      Inject this instance with the final values of all the command parameters.
      Throws:
      org.glassfish.api.admin.CommandException - if execution of the command fails
      org.glassfish.api.admin.CommandValidationException - if there's something wrong with the options or arguments

    • validate

      protected void validate() throws org.glassfish.api.admin.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:
      org.glassfish.api.admin.CommandException - if execution of the command fails
      org.glassfish.api.admin.CommandValidationException - if there's something wrong with the options or arguments

    • executeCommand

      protected abstract int executeCommand() throws org.glassfish.api.admin.CommandException
      Execute the command using the options in options and the operands in operands.
      Returns:
      the exit code
      Throws:
      org.glassfish.api.admin.CommandException - if execution of the command fails
      org.glassfish.api.admin.CommandValidationException - if there's something wrong with the options or arguments

    • getPassword

      protected char[] getPassword(String paramname, String localizedPrompt, String localizedPromptConfirm, boolean create) throws org.glassfish.api.admin.CommandValidationException
      Throws:
      org.glassfish.api.admin.CommandValidationException

    • getPassword

      protected char[] getPassword(org.glassfish.api.admin.CommandModel.ParamModel opt, String defaultPassword, boolean create) throws org.glassfish.api.admin.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:
      org.glassfish.api.admin.CommandValidationException

    • readPassword

      protected char[] readPassword(String prompt)
      Display the given prompt and read a password without echoing it.
      Returns:
      null if no console available, read password otherwise.

    • getOperandModel

      protected org.glassfish.api.admin.CommandModel.ParamModel getOperandModel()
      Get the ParamModel that corresponds to the operand (primary parameter). Return null if none.

    • getOption

      protected String getOption(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.

    • getOptions

      protected List<String> getOptions(String name)
      Get option values, that might come from the command line or from the environment. Return the default value for the option if not otherwise specified. This method works with options for with multiple() is true.

    • getBooleanOption

      protected boolean getBooleanOption(String name)
      Get a boolean option value, that might come from the command line or from the environment.

    • getSystemProperty

      protected String getSystemProperty(String name)
      Return the named system property, or property set in asenv.conf.

    • getSystemProperties

      protected Map<String,String> getSystemProperties()
      Return all the system properties and properties set in asenv.conf. The returned Map may not be modified.

    • ok

      protected static boolean ok(String s)