com.arsdigita.util.parameter
Interface Parameter

All Known Implementing Classes:

AbstractParameter

public interface Parameter

Subject to change. Describes a named property that can read, write, and validate its own value. See the documentation on read(com.arsdigita.util.parameter.ParameterReader, com.arsdigita.util.parameter.ErrorList), write(com.arsdigita.util.parameter.ParameterWriter, java.lang.Object), and validate(java.lang.Object, com.arsdigita.util.parameter.ErrorList) for details. They have the following features as well:

• Multiplicity. A parameter can be nullable (0..x) or required (1..x) and singular (x..1) or multiple (x..n). The current parameter implementation only models nullablel vs. required parameters.
• Defaulting. A parameter can have a value to fall back on if none is set.
• Optional metadata. Optional extra "info" can be associated with a parameter.

The read and validate phases of a parameter collect errors into a list so that calling code can control error handling. This is in lieu of throwing exceptions that are not useful in creating error-recovery UIs. In contrast, the write phase of a parameter is expected to complete successfully or fail outright. Parameters are stateless "messages". They do not store their own values. Instead, a ParameterContext manages a set of parameters and keeps their values. Here's what it typically looks like to use a parameter:

Properties props = System.getProperties(); ParameterReader reader = JavaPropertyReader(props); ParameterWriter writer = JavaPropertyWriter(props); ErrorList errors = new ErrorList(); Object value = param.read(reader, errors); errors.check(); // If errors is not empty, fails param.validate(value, errors); errors.check(); // If errors is not empty, fails // We now have a valid unmarshaled value, so code of actual use can // go here. param.write(writer, value);

Version:

$Id: //core-platform/dev/src/com/arsdigita/util/parameter/Parameter.java#7 $

Author:

Rafael H. Schloming <rhs@mit.edu>, Justin Ross <jross@redhat.com>

See Also:

AbstractParameter, ParameterContext

Field Summary

static int	OPTIONAL Flag to indicate the parameter value is nullable.
static int	REQUIRED Flag to indicate the parameter value cannot be null.
static String	versionId

Method Summary

Object	getDefaultValue() Gets the default value of the parameter.
ParameterInfo	getInfo() Gets metadata associated with the parameter if it is available.
String	getName() Gets the name of the parameter.
boolean	isRequired() Tells wether the parameter is nullable or not.
Object	read(ParameterReader reader, ErrorList errors) Gets the parameter value as a Java object.
void	setInfo(ParameterInfo info) Sets the optional parameter metadata to info.
void	validate(Object value, ErrorList errors) Validates the parameter value, value.
void	write(ParameterWriter writer, Object value) Writes the parameter value as a string literal.

Field Detail

versionId

public static final String versionId

See Also:

Constant Field Values

OPTIONAL

public static final int OPTIONAL

Flag to indicate the parameter value is nullable.

See Also:

Constant Field Values

REQUIRED

public static final int REQUIRED

Flag to indicate the parameter value cannot be null.

See Also:

Constant Field Values

Method Detail

isRequired

public boolean isRequired()

Tells wether the parameter is nullable or not.

Returns:

true if the parameter cannot be null; false if it can be null

getName

public String getName()

Gets the name of the parameter.

Returns:

The String parameter name; it cannot be null

getDefaultValue

public Object getDefaultValue()

Gets the default value of the parameter. Implementations may choose to substitute this value for null.

Returns:

The fallback value; it may be null

getInfo

public ParameterInfo getInfo()

Gets metadata associated with the parameter if it is available.

Returns:

The ParameterInfo object; it may be null

setInfo

public void setInfo(ParameterInfo info)

Sets the optional parameter metadata to info.

Parameters:

info - The ParameterInfo to associate; it may be null

read

public Object read(ParameterReader reader,
                   ErrorList errors)

Gets the parameter value as a Java object. The value will have a specific runtime type and so may be appropriately cast. Reading typically follows the following procedure:

• Read the literal string value associated with the parameter from reader
• Convert the literal string value into an approprite Java object

If at any point in the process an error is encountered, it is added to errors. Callers of this method will typically construct an ErrorList in which to collect errors.

Parameters:

reader - The ParameterReader from which to recover a string literal value; it cannot be null

errors - The ErrorList in which to collect any errors encountered; it cannot be null

Returns:

The Java object value of the parameter

validate

public void validate(Object value,
                     ErrorList errors)

Validates the parameter value, value. Any validation errors encountered are added to errors.

Parameters:

value - The value to validate; this is typically the value returned by read(com.arsdigita.util.parameter.ParameterReader, com.arsdigita.util.parameter.ErrorList); it may be null

errors - The ErrorList in which to collect any errors encountered; it cannot be null

write

public void write(ParameterWriter writer,
                  Object value)

Writes the parameter value as a string literal. The parameter marshals he object value to a string and sends it to writer.

Parameters:

writer - The ParameterWriter that will take the marshaled value and store it; it cannot be null

value - The Java object value of the parameter