com.arsdigita.bebop.parameters
Class ParameterModel

java.lang.Object
  extended bycom.arsdigita.bebop.parameters.ParameterModel
All Implemented Interfaces:
Lockable
Direct Known Subclasses:
ArrayParameter, BigDecimalParameter, BigIntegerParameter, BitSetParameter, BooleanParameter, DateParameter, DateRangeParameter, DateTimeParameter, NumberParameter, OIDParameter, StringParameter, TimeParameter

public abstract class ParameterModel
extends Object
implements Lockable

Represents the abstract model for a form parameter object. This class must be subclassed for each specific data type.

Version:
$Id: //core-platform/dev/src/com/arsdigita/bebop/parameters/ParameterModel.java#9 $
Author:
Karl Goldstein, Uday Mathur

Field Summary
protected  Object m_defaultValue
          The default value of this ParameterModel.
protected  boolean m_locked
          A boolean indicating if this ParameterModel is locked, as per the Lockable interface
protected  String m_name
          The name of this ParameterModel.
protected  List m_parameterListeners
          A List of Listeners to validate this parameter.
static String versionId
           
 
Constructor Summary
protected ParameterModel(String name)
          Construct a new Parameter Model with the specified name
 
Method Summary
 void addParameterListener(ParameterListener listener)
          Adds a validation listener, implementing a custom validation check that applies to this Parameter.
 ParameterData createParameterData(javax.servlet.http.HttpServletRequest request)
           
 ParameterData createParameterData(javax.servlet.http.HttpServletRequest request, boolean isSubmission)
          Create a ParameterData for this ParameterModel with the supplied request If this tranformation throws an exception, mark the corresponding ParameterData as unTransformed and set its value to null.
 ParameterData createParameterData(javax.servlet.http.HttpServletRequest request, Object defaultValue, boolean isSubmission)
          Create a ParameterData for this ParameterModel with the supplied request If this tranformation throws an exception, mark the corresponding ParameterData as unTransformed and set its value to null.
 boolean getDefaultOverridesNull()
          Return true if default values are used when the value in the request is null.
 Object getDefaultValue()
          Get the default value for this parameter.
 String getName()
          Returns the name of this parameterModel
 Class getValueClass()
          Return the class that all values produced by the model will have.
 boolean isLocked()
          Return whether an object is locked and thus immutable, or can still be modified.
 boolean isPassIn()
          The "pass in" property determines whether the value for this parameter is generally passed in from the outside.
 void lock()
          Lock the model, blocking any further modifications.
 String marshal(Object value)
          Produce a string representation of the given value.
 void setDefaultOverridesNull(boolean v)
          Controls how default values are used.
 void setDefaultValue(Object defaultValue)
          Sets a default value for this parameter.
 void setName(String name)
          Sets the name of this ParmeterModel.
 void setPassIn(boolean v)
          Set whether this parameter should be treated as a "pass in" parameter.
protected  Object transformSingleValue(javax.servlet.http.HttpServletRequest request)
          Helper method for implementing transformValue.
abstract  Object transformValue(javax.servlet.http.HttpServletRequest request)
          Transform string parameter values in the HTTP request into an appropriate Java object associated with the particular implementing class.
 Object unmarshal(String encoded)
          Reconstruct the parameter value from an encoded string produced by marshal.
protected  void validate(ParameterData data)
          Call parameter validation listeners that have been added to this ParameterModel.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values

m_name

protected String m_name
The name of this ParameterModel. The constructor will throw an exception if the specified name is null


m_defaultValue

protected Object m_defaultValue
The default value of this ParameterModel. This value is used when the request is not a submission, and the transformValue returns null.


m_parameterListeners

protected List m_parameterListeners
A List of Listeners to validate this parameter.


m_locked

protected boolean m_locked
A boolean indicating if this ParameterModel is locked, as per the Lockable interface

Constructor Detail

ParameterModel

protected ParameterModel(String name)
Construct a new Parameter Model with the specified name

Parameters:
name - String used to identify this parameter. Name is used as the name of the associated widget, and is the name of the variable in the request
Method Detail

setDefaultOverridesNull

public final void setDefaultOverridesNull(boolean v)
Controls how default values are used. If this property is false (which it is initially), default values are only used for requests that are not user submissions as indicated by the isSubmission parameter to createParameterData(javax.servlet.http.HttpServletRequest). This is the behavior that is useful for forms, since it makes it possible for the user to get rid of default form entries by erasing them.

If this property is set to true, the default value is used whenever transformValue(javax.servlet.http.HttpServletRequest) returns null. This behavior is mainly useful for processing requests that are generated automatically, and is used by PageState to maintain state information across requests.

Parameters:
v - true if default values should be used when the value in the request is null.
See Also:
setDefaultValue(java.lang.Object)

isPassIn

public final boolean isPassIn()
The "pass in" property determines whether the value for this parameter is generally passed in from the outside. If this property is true, the model always tries to get the parameter value from the request, no matter whether the isSubmission parameter to createParameterData(javax.servlet.http.HttpServletRequest) is true or not.

If this property is false, the parameter value is only read from the request if the isSubmission parameter to createParameterData(javax.servlet.http.HttpServletRequest) is true.

By default, this property is true.

Returns:
true if an attempt should always be made to retrieve the parameter value from the request.

setPassIn

public final void setPassIn(boolean v)
Set whether this parameter should be treated as a "pass in" parameter.

This defaults to true; if a passed-in value is available, it should be used.

Parameters:
v - true if this parameter is a pass in parameter.
See Also:
isPassIn()

getDefaultOverridesNull

public final boolean getDefaultOverridesNull()
Return true if default values are used when the value in the request is null. This property is initially false.

Returns:
true if default values are used when the value in the request is null.
See Also:
setDefaultOverridesNull(boolean), setDefaultValue(java.lang.Object)

getName

public final String getName()
Returns the name of this parameterModel

Returns:
The name of this parameter model.

setName

public final void setName(String name)
Sets the name of this ParmeterModel. Asserts that this ParameterModel is not locked.

Parameters:
name - The name of this parameter model.

addParameterListener

public void addParameterListener(ParameterListener listener)
Adds a validation listener, implementing a custom validation check that applies to this Parameter. Useful for checks that require examination of the values of only this parameter. Asserts that this ParameterModel is not locked.

Parameters:
listener - An instance of a class that implements the FormValidationListener interface.

setDefaultValue

public void setDefaultValue(Object defaultValue)
Sets a default value for this parameter. This default value is superceded by values set in the initialization listeners and in the request object. Asserts that this ParameterModel is not locked.

Parameters:
defaultValue - a default value for this parameter that appears if there is no value in the request or specified by an initialization listener

getDefaultValue

public final Object getDefaultValue()
Get the default value for this parameter. This value is used if this request is not a submission and transformValue returns null.

Returns:
a default value for this parameter

transformValue

public abstract Object transformValue(javax.servlet.http.HttpServletRequest request)
                               throws IllegalArgumentException
Transform string parameter values in the HTTP request into an appropriate Java object associated with the particular implementing class. If there is an error transforming the passed-in URL/form variables into a Java object, then implementing classes should throw IllegalArgumentException.

Parameters:
request - The HttpServletRequest of the form submission.
Throws:
IllegalArgumentException - if there is an error transforming form/URL variables to an object.

transformSingleValue

protected final Object transformSingleValue(javax.servlet.http.HttpServletRequest request)
Helper method for implementing transformValue. Calls unmarshal, passing in the request parameter, if there is a nonempty request parameter with the models name, and returns null otherwise.

Parameters:
request - the current request
Returns:
the value returned by unmarshalling the request parameter, or null if there is no nonempty request parameter with the model's name.

createParameterData

public ParameterData createParameterData(javax.servlet.http.HttpServletRequest request)

createParameterData

public ParameterData createParameterData(javax.servlet.http.HttpServletRequest request,
                                         boolean isSubmission)
Create a ParameterData for this ParameterModel with the supplied request If this tranformation throws an exception, mark the corresponding ParameterData as unTransformed and set its value to null. If this request is not a submission and transformValue returns null then construct the ParameterData with the default value for this ParameterModel.

Parameters:
request - the HttpServletRequest from which to extract and transform the value
isSubmission - boolean indicating whether this ParameterData is being created as part of a form submission. If this is part of a form submission, we do not want default values to overwrite null values from the submission.

createParameterData

public ParameterData createParameterData(javax.servlet.http.HttpServletRequest request,
                                         Object defaultValue,
                                         boolean isSubmission)
Create a ParameterData for this ParameterModel with the supplied request If this tranformation throws an exception, mark the corresponding ParameterData as unTransformed and set its value to null. If this request is not a submission and transformValue returns null then construct the ParameterData with the default value for this ParameterModel.

Parameters:
request - the HttpServletRequest from which to extract and transform the value
defaultValue - an additional default value that may be specified dynamically, to override the static default value associated with this ParameterModel object.
isSubmission - boolean indicating whether this ParameterData is being created as part of a form submission. If this is part of a form submission, we do not want default values to overwrite null values from the submission.

lock

public void lock()
Lock the model, blocking any further modifications. Cached form models should always be locked to ensure that they remain unchanged across requests.

Specified by:
lock in interface Lockable

validate

protected void validate(ParameterData data)
                 throws FormProcessException
Call parameter validation listeners that have been added to this ParameterModel. Note that this is decoupled from the getValue method because the form data object may be initialized with data prior to processing the HTTP request.

Parameters:
data - A ParameterData object associated with this parameterModel for a given request. The ParameterData contains the value and errors of this parameter
Throws:
FormProcessException

marshal

public String marshal(Object value)
Produce a string representation of the given value. The parameter model has to be able to read the resulting string back into the right object o so that value.equals(o).

Parameters:
value - a value previously produced by this parameter model
Returns:
the value as a readable string, may be null

unmarshal

public Object unmarshal(String encoded)
Reconstruct the parameter value from an encoded string produced by marshal. This is an optional operation, which needs to be implemented by specific subclasses; this implementation just throws an UnsupportedOperationException.

The contract between marshal and unmarshal is that for any possible object obj this parameter model can produce obj.equals(unmarshal(marshal(obj)).

Parameters:
encoded - a string produced by marshal
Returns:
the object represented by encoded

getValueClass

public Class getValueClass()
Return the class that all values produced by the model will have. This should be the most specific common base class of all classes of which the model will ever produce values. This implementation returns Object.class

Returns:
the class that all values produced by the model will have.

isLocked

public final boolean isLocked()
Description copied from interface: Lockable
Return whether an object is locked and thus immutable, or can still be modified.

Specified by:
isLocked in interface Lockable
Returns:
true if this ParameterModel is locked to prevent modification.


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