org.rhq.enterprise.communications.command.param
Class ParameterDefinition

java.lang.Object
  org.rhq.enterprise.communications.command.param.ParameterDefinition

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

FixedValuesParameterDefinition, MapValueParameterDefinition

public class ParameterDefinition
extends Object
implements Serializable

Defines a parameter that is accepted by a Command. This class also provides some convienence methods to check if a value conforms to this parameter and to convert a value so it does conform.

Note that a parameter definition is equal to another parameter definition if they have the same name. Equality is based solely on name, irregardless of any other metadata defined in this object.

Author:

John Mazzitelli

See Also:

Serialized Form

Field Summary

static boolean	HIDDEN Indicator that says a parameter should be hidden from a user's view.
static boolean	NOT_HIDDEN Indicator that says a parameter should be visible to a user.
static boolean	NOT_NULLABLE Indicator that says a parameter is not nullable (the parameter's value must not be null)
static boolean	NULLABLE Indicator that says a parameter is nullable (the parameter's value may be null)
static boolean	OPTIONAL Indicator that says a parameter is optional
static boolean	REQUIRED Indicator that says a parameter is required

Constructor Summary

ParameterDefinition(String name, String type, boolean required, boolean nullable, boolean hidden, String description)
Constructor for ParameterDefinition that allows for a description string.

ParameterDefinition(String name, String type, boolean required, boolean nullable, boolean hidden, String description, ParameterRenderingInformation renderingInfo)
Constructor for ParameterDefinition that allows for a description string.

ParameterDefinition(String name, String type, boolean hidden, String description)
Constructor for ParameterDefinition that defines a parameter whose value is optional and may be nullable.

ParameterDefinition(String name, String type, boolean hidden, String description, ParameterRenderingInformation renderingInfo)
Constructor for ParameterDefinition that defines a parameter whose value is optional and may be nullable.

ParameterDefinition(String name, String type, ParameterRenderingInformation renderingInfo)
Constructor for ParameterDefinition that defines a parameter whose value is optional and may be nullable.

Method Summary

Object	convertObject(Object objectToConvert) This method converts the given objectToConvert value into an instance of this parameter's type.
boolean	equals(Object obj) Equality is based solely on name - a definition is the same as another if their names are the same.
protected ParameterRenderingInformation	getDefaultRenderingInfo() Returns this definition's default rendering information.
String	getDescription() Returns a description indicating the purpose and function of the parameter.
String	getName() Returns the value of the name of the parameter.
ParameterRenderingInformation	getRenderingInfo() Get the rendering information that can be used to render the parameter in a user interface.
String	getType() Returns the type of the parameter's value.
int	hashCode() The hash code for a parameter definition is the same hash code as the parameter definition name.
boolean	isHidden() Returns a flag to indicate if this parameter should be hidden from user interfaces.
boolean	isNullable() Defines whether or not the parameter's value is allowed to be null.
boolean	isRequired() Defines whether or not the parameter value is required to exist in order to be able to successfully execute a command.
boolean	isValidValue(Object valueToCheck) Checks the validity of the given object to ensure it conforms to this parameter definition.
protected void	setDefaultRenderingAttributes(ParameterRenderingInformation renderingInfo) Sets the label, description and isHidden fields on the passed in renderingInfo object using this definition for the default values.
void	setRenderingInfo(ParameterRenderingInformation renderingInfo) Sets the rendering information that can be used to render the parameter in a user interface.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

REQUIRED

public static final boolean REQUIRED

Indicator that says a parameter is required

See Also:

Constant Field Values

OPTIONAL

public static final boolean OPTIONAL

Indicator that says a parameter is optional

See Also:

Constant Field Values

NULLABLE

public static final boolean NULLABLE

Indicator that says a parameter is nullable (the parameter's value may be null)

See Also:

Constant Field Values

NOT_NULLABLE

public static final boolean NOT_NULLABLE

Indicator that says a parameter is not nullable (the parameter's value must not be null)

See Also:

Constant Field Values

HIDDEN

public static final boolean HIDDEN

Indicator that says a parameter should be hidden from a user's view. Used by user interfaces.

See Also:

Constant Field Values

NOT_HIDDEN

public static final boolean NOT_HIDDEN

Indicator that says a parameter should be visible to a user. Used by user interfaces.

See Also:

Constant Field Values

Constructor Detail

ParameterDefinition

public ParameterDefinition(String name,
                           String type,
                           ParameterRenderingInformation renderingInfo)
                    throws IllegalArgumentException

Constructor for ParameterDefinition that defines a parameter whose value is optional and may be nullable. The rendering information is used for other metadata (such as if the parameter is hidden and its description).

Parameters:

name - the name of the parameter (this is the name you use to look up the parameter value via Command.getParameterValue(String) (must not be null)

type - the parameter data type specified "the Java way"; e.g. "java.lang.String" (must not be null)

renderingInfo - information relating to how the parameter should be rendered by clients. See ParameterRenderingInformation

Throws:

IllegalArgumentException - if name or type is null

ParameterDefinition

public ParameterDefinition(String name,
                           String type,
                           boolean hidden,
                           String description)
                    throws IllegalArgumentException

Constructor for ParameterDefinition that defines a parameter whose value is optional and may be nullable.

Parameters:

name - the name of the parameter (this is the name you use to look up the parameter value via Command.getParameterValue(String) (must not be null)

type - the parameter data type specified "the Java way"; e.g. "java.lang.String" (must not be null)

hidden - if true, this parameter should be hidden from any user interface - the user should not know about this parameter (although true values do not prohibit users from setting this parameter's value should they choose to)

description - a human readable description string that describes the function of the parameter (may be null)

Throws:

IllegalArgumentException - if name or type is null

ParameterDefinition

public ParameterDefinition(String name,
                           String type,
                           boolean hidden,
                           String description,
                           ParameterRenderingInformation renderingInfo)
                    throws IllegalArgumentException

Constructor for ParameterDefinition that defines a parameter whose value is optional and may be nullable. Note that hidden and description are default values and can be overridden by the analogous values found in the getRenderingInfo().

Parameters:

name - the name of the parameter (this is the name you use to look up the parameter value via Command.getParameterValue(String) (must not be null)

type - the parameter data type specified "the Java way"; e.g. "java.lang.String" (must not be null)

hidden - if true, this parameter should be hidden from any user interface - the user should not know about this parameter (although true values do not prohibit users from setting this parameter's value should they choose to)

description - a human readable description string that describes the function of the parameter (may be null)

renderingInfo - information relating to how the parameter should be rendered by clients. See ParameterRenderingInformation

Throws:

IllegalArgumentException - if name or type is null

ParameterDefinition

public ParameterDefinition(String name,
                           String type,
                           boolean required,
                           boolean nullable,
                           boolean hidden,
                           String description)
                    throws IllegalArgumentException

Constructor for ParameterDefinition that allows for a description string.

Parameters:

name - the name of the parameter (this is the name you use to look up the parameter value via Command.getParameterValue(String) (must not be null)

type - the parameter data type specified "the Java way"; e.g. "java.lang.String" (must not be null)

required - if true, the parameter's value is required to successfully execute a command

nullable - if true, the parameter's value is allowed to be null

hidden - if true, this parameter should be hidden from any user interface - the user should not know about this parameter (although true values do not prohibit users from setting this parameter's value should they choose to)

description - a human readable description string that describes the function of the parameter (may be null)

Throws:

IllegalArgumentException - if name or type is null

ParameterDefinition

public ParameterDefinition(String name,
                           String type,
                           boolean required,
                           boolean nullable,
                           boolean hidden,
                           String description,
                           ParameterRenderingInformation renderingInfo)
                    throws IllegalArgumentException

Constructor for ParameterDefinition that allows for a description string. Note that hidden and description are default values and can be overridden by the analogous values found in the getRenderingInfo()

Parameters:

name - the name of the parameter (this is the name you use to look up the parameter value via Command.getParameterValue(String) (must not be null)

type - the parameter data type specified "the Java way"; e.g. "java.lang.String" (must not be null)

required - if true, the parameter's value is required to successfully execute a command

nullable - if true, the parameter's value is allowed to be null

hidden - if true, this parameter should be hidden from any user interface - the user should not know about this parameter (although true values do not prohibit users from setting this parameter's value should they choose to)

description - a human readable description string that describes the function of the parameter (may be null)

renderingInfo - information relating to how the parameter should be rendered by clients. See ParameterRenderingInformation

Throws:

IllegalArgumentException - if name or type is null

Method Detail

getName

public String getName()

Returns the value of the name of the parameter.

Returns:

parameter name

getType

public String getType()

Returns the type of the parameter's value. The returned type string follows the Java conventions on type specification strings (i.e. java.lang.Integer). See java.lang.Class javadocs for more information.

Returns:

the type of the paramter's value

isRequired

public boolean isRequired()

Defines whether or not the parameter value is required to exist in order to be able to successfully execute a command.

Returns:

if true, this parameter must be specified when invoking a command

isNullable

public boolean isNullable()

Defines whether or not the parameter's value is allowed to be null.

Returns:

if true, the parameter's value is allowed to be null

isHidden

public boolean isHidden()

Returns a flag to indicate if this parameter should be hidden from user interfaces. If true, this parameter should not be known to the user and thus the user interfaces should not show this parameter's existence. If false, this parameter should be visible to users and hence can be shown to users via a user interface (which is typically the case).

Returns:

flag to indicate if this parameter should be hidden from a user or if it should be visible to the user

getDescription

public String getDescription()

Returns a description indicating the purpose and function of the parameter. This may be null if it was never defined.

Returns:

human readable description string

getRenderingInfo

public ParameterRenderingInformation getRenderingInfo()

Get the rendering information that can be used to render the parameter in a user interface.

Returns:

the rendering info

setRenderingInfo

public void setRenderingInfo(ParameterRenderingInformation renderingInfo)

Sets the rendering information that can be used to render the parameter in a user interface.

Parameters:

renderingInfo - the new rendering info

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()

equals

public boolean equals(Object obj)

Equality is based solely on name - a definition is the same as another if their names are the same.

Overrides:

equals in class Object

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

The hash code for a parameter definition is the same hash code as the parameter definition name.

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

isValidValue

public boolean isValidValue(Object valueToCheck)

Checks the validity of the given object to ensure it conforms to this parameter definition. The given object's type is compared to the parameter's desired type. If the given object is an instance of the parameter's type, this method returns true. The actual type check is performed via java.lang.Class.isInstance(Object).

Nullability is also checked (that is, if the given object is null, this parameter definition must allow for null.

Note that if the parameter type class (i.e. java.lang.Class.forName(getType()) is unknown or unloadable, this method returns false.

Parameters:

valueToCheck - checking the type validity of this object

Returns:

true if the given object conforms to this parameter definition, false otherwise

convertObject

public Object convertObject(Object objectToConvert)
                     throws InvalidParameterValueException

This method converts the given objectToConvert value into an instance of this parameter's type. If the object to convert is not already of the parameter's type, a constructor is called to build one. It will be assumed that this parameter's type class has a constructor that takes a single argument of the same type as objectToConvert. If this constructor does exist, it is used to create the new instance by passing objectToConvert to it. The resulting object is returned (this object will be of the parameter's defined type. The original objectToConvert will be returned as-is (i.e. no conversion will be performed) if either of the following is true:

• objectToConvert is null
• objectToConvert is already an instance of this parameter's type

Note that if objectToConvert is null, but this parameter definition does not allow for null, an exception is thrown.

This method is useful when needing to convert text-based command line parameters to their actual Java type representations.

Parameters:

objectToConvert - the object to convert to the given type

Returns:

the converted object

Throws:

InvalidParameterValueException - if the given object is null but this parameter definition does not allow for null, or the parameter's type specifies a primitive type, or the conversion failed due to a problem occurring while instantiating the new typed object

getDefaultRenderingInfo

protected ParameterRenderingInformation getDefaultRenderingInfo()

Returns this definition's default rendering information. If no rendering information is provided to this object's constructors, then the returned rendering info from this method is used. Subclasses are free to override this method to define their own default rendering information.

This method implementation will by default render all

Returns:

a default rendering information object that can be used by this parameter definition object

setDefaultRenderingAttributes

protected void setDefaultRenderingAttributes(ParameterRenderingInformation renderingInfo)

Sets the label, description and isHidden fields on the passed in renderingInfo object using this definition for the default values. The purpose of this method is to allow this class (or subclasses) to populate a given rendering info object with a set of appropriate default values. Subclasses are free to use this method or override it to fill in rendering info with their own set of defaults.

Parameters:

renderingInfo - the rendering information that is to be populated with default attribute values