org.rhq.enterprise.communications.command
Class AbstractCommand

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

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

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