AbstractCommand (RHQ Enterprise Agent-Server Communications Layer 4.9.0 API)

java.lang.Object
- org.rhq.enterprise.communications.command.AbstractCommand

All Implemented Interfaces:

Serializable, Command

Direct Known Subclasses:

EchoCommand, GenericCommand, IdentifyCommand, RemoteInputStreamCommand, RemoteOutputStreamCommand, RemotePojoInvocationCommand, StartCommand
```
public abstract class AbstractCommand
extends Object
implements Command
```
Superclass to all Command objects that may be executed by a command processor.

Author:

John Mazzitelli

See Also:
Serialized Form

Constructor Summary

Constructors
Constructor and Description
`AbstractCommand()` Constructor for `AbstractCommand` that defines just the type without any parameters.
`AbstractCommand(Command commandToTransform)` Constructor for `AbstractCommand` that acts as a pseudo-copy constructor and a command decorator/transformer.
`AbstractCommand(Map<String,Object> commandParameters)` Constructor for `AbstractCommand` that allows the caller to define both the name and parameter default values.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`allowAnyParameter()` Returns `true` if this command does not utilize `parameter definitions` to restrict what parameters it can accept.
`protected abstract CommandType`	`buildCommandType()` Builds the command type of this command.
`protected abstract ParameterDefinition[]`	`buildParameterDefinitions()` Builds the set of parameter definitions that this command will use.
`void`	`checkParameterValidity(boolean convertIfNecessary)` This method verifies the validity of the parameters.
`void`	`convertParameters()` This method will attempt to convert all parameters whose types did not match that of its corresponding parameter definition.
`CommandType`	`getCommandType()` Returns an object that identifies the type of command.
`Properties`	`getConfiguration()` Returns a map of name/value pairs that can be used to configure this particular instance of the command.
`ParameterDefinition`	`getParameterDefinition(String paramName)` Returns the definition of the named parameter.
`ParameterDefinition[]`	`getParameterDefinitions()` Returns the set of parameter definitions for all allowable parameters this command accepts.
`Object`	`getParameterValue(String paramName)` Returns the value of a parameter that is to be passed to the command.
`Map<String,Object>`	`getParameterValues()` Returns the values of all parameters that are to be passed to the command in a `Map`, with the keys in the map being the parameter names.
`protected Map`	`getParameterValuesInternalMap()` Returns a `Map` containing all optional parameters set on this command.
`boolean`	`hasParameterValue(String paramName)` Checks to see if the given parameter has explicitly been given a value (`null` or otherwise).
`protected void`	`initializeMetadata()` Initializes the newly constructed command so its type and parameter definition metadata are built properly.
`boolean`	`isCommandInResponse()` If `true` is returned, then this `Command` that was executed will be included in the returned response.
`void`	`removeParameterValue(String paramName)` Removes a parameter from this command.
`void`	`removeParameterValues()` Removes all parameters from this command.
`void`	`setCommandInResponse(boolean flag)` Sets a flag to determine if this `Command` object is to be returned with the response after the command has executed.
`void`	`setParameterValue(String paramName, Object paramValue)` Adds a parameter value under the given parameter name.
`protected void`	`setParameterValuesInternalMap(Map<String,Object> commandParameters)` Sets the parameter map, overwriting any previously existing map of parameters.
`String`	`toString()` Returns the string representation of this command that includes the parameter values but not the parameter definitions.
`String`	`toString(boolean includeParameters, boolean includeParameterDefs)` Returns a toString representation of the command but provides the caller the option to include or omit the parameters values and/or the parameter definitions.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - AbstractCommand
```
public AbstractCommand()
                throws IllegalArgumentException,
                       InvalidParameterDefinitionException
```
    Constructor for AbstractCommand that defines just the type without any parameters.
    
    Throws:
    
    IllegalArgumentException - if commandType was not defined by the command subclass
    
    InvalidParameterDefinitionException - if more than one parameter is defined with the same name
    See Also:
    buildCommandType(), buildParameterDefinitions(), AbstractCommand(Map)
  - AbstractCommand
```
public AbstractCommand(Map<String,Object> commandParameters)
                throws IllegalArgumentException,
                       InvalidParameterDefinitionException
```
    Constructor for AbstractCommand that allows the caller to define both the name and parameter default values.
    
    Parameters:
    commandParameters - optional set of parameters to be passed with the command (may be empty or null)
    
    Throws:
    
    IllegalArgumentException - if commandType was not defined by the command subclass
    
    InvalidParameterDefinitionException - if more than one parameter is defined with the same name
    See Also:
    buildCommandType(), buildParameterDefinitions()
  - AbstractCommand
```
public AbstractCommand(Command commandToTransform)
                throws InvalidParameterValueException
```
    Constructor for AbstractCommand that acts as a pseudo-copy constructor and a command decorator/transformer. The given command's parameter values will be copied to this new command object. However, the command type and the parameter definitions will be those defined by the subclass' buildParameterDefinitions(), not those of the given command.
    So, as you can see, this isn't truely a follower of the Decorator pattern or a copy-constructor; instead, think of this constructor as a transformer from one command implementation to another, while maintaining the command's original parameter values (as well as the flag).
    
    This is typically used when the given command is a generic command (one with no parameter definitions for example) and the caller wants to convert it to a more concrete command implementation. This is usually due to the fact that the creator of the given command object did not know at compile time the specific concrete command type it needed.
    
    Transforming a command allows the caller to "decorate" the given command with a concrete command implementation's API (which typically has more strongly typed methods to extract out command parameters).
    
    If the given commandToTransform allowed any and all parameters but the newly transformed command (this object) does not, this method forces the current set of parameters to be validated (after possibly being converted to the appropriate types). If the parameters do not validate, an exception will be thrown.
    
    The only thing a subclass must do in order to support this transformer constructor is to override it and call it via super.
    
    Parameters:
    commandToTransform - the command object to transform into this class type
    
    Throws:
    
    InvalidParameterValueException - if the original command's parameters are not valid for this command
- Method Detail
  - getCommandType
```
public CommandType getCommandType()
```
    Description copied from interface: Command
    
    Returns an object that identifies the type of command.
    
    Specified by:
    
    getCommandType in interface Command
    
    Returns:
    command type identifier (will never be null)
    See Also:
    Command.getCommandType()
  - isCommandInResponse
```
public boolean isCommandInResponse()
```
    Description copied from interface: Command
    
    If true is returned, then this Command that was executed will be included in the returned response. This is useful if executed asynchronously and the command requestor will need to know the command and the parameters that were issued. If false, then the response returned by the server after the command has executed will be unavailable (i.e. null).
    
    Specified by:
    
    isCommandInResponse in interface Command
    
    Returns:
    true if this object will be returned in the response to the command execution
    See Also:
    Command.isCommandInResponse()
  - setCommandInResponse
```
public void setCommandInResponse(boolean flag)
```
    Description copied from interface: Command
    
    Sets a flag to determine if this Command object is to be returned with the response after the command has executed. Using this will affect performance as it requires not only for the actual response data to be (un)marshalled, but also the Command must be (un)marshalled and set over the network as well. Use this if the command was executed asynchronously and the original Command object is no longer available on the client.
    
    Specified by:
    
    setCommandInResponse in interface Command
    
    Parameters:
    flag - true to get this object returned with the command response.
    See Also:
    Command.setCommandInResponse(boolean)
  - allowAnyParameter
```
public boolean allowAnyParameter()
```
    Description copied from interface: Command
    
    Returns true if this command does not utilize parameter definitions to restrict what parameters it can accept. true means this command will accept any and all parameter values and types. false means that this command restricts the kinds of parameters it will accept. The definitions of the allowable parameters are determined by a call to Command.getParameterDefinitions().
    
    Specified by:
    
    allowAnyParameter in interface Command
    
    Returns:
    true if there are no restrictions to the number, types and names of parameters accepted by the command; false means all parameters must pass validity checks based on parameter definitions found in Command.getParameterDefinitions()
    See Also:
    Command.allowAnyParameter()
  - getParameterDefinition
```
public ParameterDefinition getParameterDefinition(String paramName)
                                           throws IllegalArgumentException,
                                                  NoParameterDefinitionsException
```
    Description copied from interface: Command
    
    Returns the definition of the named parameter. You can use this method to determine if a command accepts a parameter with a given name. If a command does not accept a parameter with the specified name, null is returned. If a command does not define parameter definitions (e.g. Command.allowAnyParameter() returns true}), an exception is thrown.
    
    Specified by:
    
    getParameterDefinition in interface Command
    
    Parameters:
    paramName - the name of the parameter whose definition is to be returned (must not be null)
    
    Returns:
    definition of the named parameter or null if the command does not accept a parameter with the given name
    
    Throws:
    
    IllegalArgumentException - if paramName is null
    
    NoParameterDefinitionsException - if the command has not defined any parameter definitions
    See Also:
    Command.getParameterDefinition(String)
  - getParameterDefinitions
```
public ParameterDefinition[] getParameterDefinitions()
                                              throws NoParameterDefinitionsException
```
    Description copied from interface: Command
    
    Returns the set of parameter definitions for all allowable parameters this command accepts. If a command does not accept any parameters, an empty array must be returned. If a command has not defined any definitions (i.e. will accept any and all parameters), an exception is thrown.
    Whether a command accepts any and all parameters can also be determined by calling Command.allowAnyParameter().
    
    Command implementations may choose to make the order of the returned array significant.
    
    Specified by:
    
    getParameterDefinitions in interface Command
    
    Returns:
    array of parameter definitions (may be null)
    
    Throws:
    
    NoParameterDefinitionsException - if no parameter definitions have been defined by the command; this indicates the command will accept any and all parameters
    See Also:
    Command.getParameterDefinitions()
  - hasParameterValue
```
public boolean hasParameterValue(String paramName)
                          throws IllegalArgumentException
```
    Description copied from interface: Command
    
    Checks to see if the given parameter has explicitly been given a value (null or otherwise).
    
    Specified by:
    
    hasParameterValue in interface Command
    
    Parameters:
    paramName - the name of the parameter whose existence is to be checked
    
    Returns:
    true if a parameter named paramName has a value explicitly defined in this command; false if there is no parameter of that name defined
    
    Throws:
    
    IllegalArgumentException - if paramName is null
    See Also:
    Command.hasParameterValue(String)
  - getParameterValues
```
public Map<String,Object> getParameterValues()
                                      throws IllegalArgumentException
```
    Description copied from interface: Command
    
    Returns the values of all parameters that are to be passed to the command in a Map, with the keys in the map being the parameter names.
    Note that the returned Map is a copy - changes to the Map will not reflect back into the command. However, each individual value object is the original reference; it is recommended that the caller not modify the underlying value objects found in the returned map; instead, Command.setParameterValue(String, Object) should be used.
    
    Specified by:
    
    getParameterValues in interface Command
    
    Returns:
    the parameter name/value pairs (will not be null but may be empty)
    
    Throws:
    
    IllegalArgumentException
    See Also:
    Command.getParameterValues()
  - getParameterValue
```
public Object getParameterValue(String paramName)
```
    Description copied from interface: Command
    
    Returns the value of a parameter that is to be passed to the command.
    
    Specified by:
    
    getParameterValue in interface Command
    
    Parameters:
    paramName - the name of the parameter whose value is to be returned (must not be null)
    
    Returns:
    the parameter value (may be null)
    See Also:
    Command.getParameterValue(String)
  - setParameterValue
```
public void setParameterValue(String paramName,
                     Object paramValue)
                       throws IllegalArgumentException
```
    Description copied from interface: Command
    
    Adds a parameter value under the given parameter name. If a parameter already exists under the given name, it's value is overwritten with the given paramValue. Note that any parameter name or value may be added with this method - validity checking is not performed. To ensure a command's parameters are valid, call Command.checkParameterValidity(boolean).
    Note that implementations should not rely on clients using this method - instead, implementations of this interface should provide additional, more strongly typed, setter methods. This provides two things: first, it does not ask the client to know the actual parameter name and second it provides stronger type checking (as opposed to being able to just pass in an Object as this method allows).
    
    Specified by:
    
    setParameterValue in interface Command
    
    Parameters:
    paramName - the name of the new parameter
    paramValue - the value of the new parameter
    
    Throws:
    
    IllegalArgumentException - if paramName is null
    See Also:
    Command.setParameterValue(String, Object)
  - removeParameterValue
```
public void removeParameterValue(String paramName)
```
    Description copied from interface: Command
    
    Removes a parameter from this command. Validity checks are not made - to validate the parameter values after this call is made, see Command.checkParameterValidity(boolean).
    Also see Command.setParameterValue(String, Object) for the recommendation of defining strongly-typed methods in implementation classes.
    
    Specified by:
    
    removeParameterValue in interface Command
    
    Parameters:
    paramName - a key to identify the parameter to remove (may be null)
    See Also:
    Command.removeParameterValue(String)
  - removeParameterValues
```
public void removeParameterValues()
```
    Description copied from interface: Command
    
    Removes all parameters from this command. Validity checks are not made - to validate the empty command after this call is made, see Command.checkParameterValidity(boolean).
    
    Specified by:
    
    removeParameterValues in interface Command
    
    See Also:
    Command.removeParameterValues()
  - toString
```
public String toString()
```
    Returns the string representation of this command that includes the parameter values but not the parameter definitions. See toString(boolean, boolean) if you want the string to include the definitions or omit the parameter values.
    
    Overrides:
    
    toString in class Object
    
    See Also:
    Object.toString()
  - toString
```
public String toString(boolean includeParameters,
              boolean includeParameterDefs)
```
    Returns a toString representation of the command but provides the caller the option to include or omit the parameters values and/or the parameter definitions.
    Parameter definitions are noisy and can make the string very verbose.
    
    Parameters:
    includeParameters - if true, show the parameter values in the returned string
    includeParameterDefs - if true, show the parameter definitions in the returned string
    
    Returns:
    string describing the command
    See Also:
    Object.toString()
  - checkParameterValidity
```
public void checkParameterValidity(boolean convertIfNecessary)
                            throws InvalidParameterValueException
```
    Description copied from interface: Command
    
    This method verifies the validity of the parameters. If one or more parameters are invalid for some reason (e.g. a required parameter is missing or parameters exist that are not used by the command) this method will throw an exception, with the exception message describing the erroneous condition (i.e. identifying the invalid parameter(s)). When this occurs, the command should not be invoked.
    If convertIfNecessary is true, this method will attempt to convert a parameter whose value did not match that of its parameter definition. This conversion is not guaranteed to be successful; if the conversion fails, the original parameter value remains intact and the validity check fails. If the conversion succeeds, the newly converted parameter value replaces the invalid value.
    
    If all parameters are deemed valid and the command can be invoked, this method does nothing.
    
    Specified by:
    
    checkParameterValidity in interface Command
    
    Parameters:
    convertIfNecessary - if true, then attempt to convert any invalid parameter values
    
    Throws:
    
    InvalidParameterValueException - if one or more parameters are invalid
    See Also:
    Command.checkParameterValidity(boolean)
  - convertParameters
```
public void convertParameters()
```
    Description copied from interface: Command
    
    This method will attempt to convert all parameters whose types did not match that of its corresponding parameter definition. This conversion is not guaranteed to be successful; if the conversion fails, the original parameter value remains intact. If the conversion succeeds, the newly converted parameter value replaces the invalid value.
    
    Specified by:
    
    convertParameters in interface Command
    
    See Also:
    Command.convertParameters()
  - getConfiguration
```
public Properties getConfiguration()
```
    Description copied from interface: Command
    
    Returns a map of name/value pairs that can be used to configure this particular instance of the command. This is useful when you need to relate the execution of a particular command instance to something else (like an asynchronous response to the command) or if you need some out-of-band metadata that is required to configure the command. Nothing necessarily has to be defined in this map, but all commands must have a configuration properties map available.
    
    Specified by:
    
    getConfiguration in interface Command
    
    Returns:
    this instance's configuration map of name/value properties
    See Also:
    Command.getConfiguration()
  - getParameterValuesInternalMap
```
protected Map getParameterValuesInternalMap()
```
    Returns a Map containing all optional parameters set on this command. This may return null in which case no parameters will be sent along with the command when it is to be executed.
    Note: the returned Map is not a copy - changes made to the returned object are reflected back into this command object.
    
    Returns:
    map containing all parameters (may be empty or null)
  - setParameterValuesInternalMap
```
protected void setParameterValuesInternalMap(Map<String,Object> commandParameters)
```
    Sets the parameter map, overwriting any previously existing map of parameters. Note the scope is protected - users of commands should not be allowed to insert a new map of parameters; rather, subclasses should provide setters for individual parameter values.
    
    Parameters:
    commandParameters - the new map of parameters (may be null)
  - initializeMetadata
```
protected void initializeMetadata()
                           throws IllegalArgumentException,
                                  InvalidParameterDefinitionException
```
    Initializes the newly constructed command so its type and parameter definition metadata are built properly.
    This method is called from the constructors. However, it is protected to allow for specialized command implementations to be able to re-initialize the command metadata.
    
    Throws:
    
    IllegalArgumentException - if the command type was not specified by the command subclass
    
    InvalidParameterDefinitionException - if more than one parameter is defined with the same name
    See Also:
    buildCommandType(), buildParameterDefinitions(), AbstractCommand(Map)
  - buildCommandType
```
protected abstract CommandType buildCommandType()
```
    Builds the command type of this command. It must not be null.
    This method is called by the command's constructors.
    
    Returns:
    the command's type definition; must not be null
  - buildParameterDefinitions
```
protected abstract ParameterDefinition[] buildParameterDefinitions()
```
    Builds the set of parameter definitions that this command will use. Parameter definitions define what parameters this command accepts. Implementors must return one of the following:
    - An array of one or more definitions if the command accepts required and/or optional parameters
    - An empty array if the command does not accept any parameters (i.e. a no-arg command)
    - null if the command accepts any and all parameters, regardless of name or type
    This method is called by the command's constructors.
    Returns:
    an array of parameter definitions or null

Class AbstractCommand

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

AbstractCommand

AbstractCommand

AbstractCommand

Method Detail

getCommandType

isCommandInResponse

setCommandInResponse

allowAnyParameter

getParameterDefinition

getParameterDefinitions

hasParameterValue

getParameterValues

getParameterValue

setParameterValue

removeParameterValue

removeParameterValues

toString

toString

checkParameterValidity

convertParameters

getConfiguration

getParameterValuesInternalMap

setParameterValuesInternalMap

initializeMetadata

buildCommandType

buildParameterDefinitions