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:

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


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 20 2004:2337 UTC