org.rhq.enterprise.communications.command
Interface Command

All Superinterfaces:

Serializable

All Known Implementing Classes:

AbstractCommand, EchoCommand, GenericCommand, IdentifyCommand, RemoteInputStreamCommand, RemoteOutputStreamCommand, RemotePojoInvocationCommand, StartCommand

public interface Command
extends Serializable

Defines a command that can be executed. A command consists of a type (e.g. the command name) and an optional set of parameters, whose values can be obtained via getParameterValue(String).

If a command accepts any and all parameter types and values, it does not need to define a set of parameter definitions. However, if a command accepts only a certain set of parameters, it must define a set of parameter definitions that determine the validity of a command's parameter values.

Note that command implementors are recommended to provide a set of parameter setter methods should they require parameters in order to be able to execute. This will allow a strongly-typed mechanism to be available in order to set parameters (as opposed to asking the client to add Object values to a weakly-typed map and/or checking the parameter definitions to ensure the parameter values are valid). It is highly recommended that the implementors of this interface define setter methods that take Objects as opposed to primitives (e.g. Integer vs. int) to make it easier for cmdline clients to convert from text-based input to the Java representations of the actual data types needed.

Author:

John Mazzitelli

Method Summary

boolean	allowAnyParameter() Returns true if this command does not utilize parameter definitions to restrict what parameters it can accept.
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.
boolean	hasParameterValue(String paramName) Checks to see if the given parameter has explicitly been given a value (null or otherwise).
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.

Method Detail

getCommandType

CommandType getCommandType()

Returns an object that identifies the type of command.

Returns:

command type identifier (will never be null)

allowAnyParameter

boolean allowAnyParameter()

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 getParameterDefinitions().

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 getParameterDefinitions()

getParameterDefinitions

ParameterDefinition[] getParameterDefinitions()
                                              throws NoParameterDefinitionsException

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 allowAnyParameter().

Command implementations may choose to make the order of the returned array significant.

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

getParameterDefinition

ParameterDefinition getParameterDefinition(String paramName)
                                           throws IllegalArgumentException,
                                                  NoParameterDefinitionsException

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. allowAnyParameter() returns true}), an exception is thrown.

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

hasParameterValue

boolean hasParameterValue(String paramName)
                          throws IllegalArgumentException

Checks to see if the given parameter has explicitly been given a value (null or otherwise).

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

getParameterValues

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.

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, setParameterValue(String, Object) should be used.

Returns:

the parameter name/value pairs (will not be null but may be empty)

getParameterValue

Object getParameterValue(String paramName)
                         throws IllegalArgumentException

Returns the value of a parameter that is to be passed to the 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)

Throws:

IllegalArgumentException - if paramName is null

setParameterValue

void setParameterValue(String paramName,
                       Object paramValue)
                       throws IllegalArgumentException

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 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).

Parameters:

paramName - the name of the new parameter

paramValue - the value of the new parameter

Throws:

IllegalArgumentException - if paramName is null

removeParameterValue

void removeParameterValue(String paramName)
                          throws IllegalArgumentException

Removes a parameter from this command. Validity checks are not made - to validate the parameter values after this call is made, see checkParameterValidity(boolean).

Also see setParameterValue(String, Object) for the recommendation of defining strongly-typed methods in implementation classes.

Parameters:

paramName - a key to identify the parameter to remove (may be null)

Throws:

IllegalArgumentException - if paramName is null

removeParameterValues

void removeParameterValues()

Removes all parameters from this command. Validity checks are not made - to validate the empty command after this call is made, see checkParameterValidity(boolean).

isCommandInResponse

boolean isCommandInResponse()

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).

Returns:

true if this object will be returned in the response to the command execution

setCommandInResponse

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. 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.

Parameters:

flag - true to get this object returned with the command response.

checkParameterValidity

void checkParameterValidity(boolean convertIfNecessary)
                            throws InvalidParameterValueException

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.

Parameters:

convertIfNecessary - if true, then attempt to convert any invalid parameter values

Throws:

InvalidParameterValueException - if one or more parameters are invalid

See Also:

convertParameters()

convertParameters

void convertParameters()

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.

See Also:

checkParameterValidity(boolean)

getConfiguration

Properties getConfiguration()

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.

Returns:

this instance's configuration map of name/value properties