com.arsdigita.bebop
Class FormData

java.lang.Object
  extended bycom.arsdigita.bebop.FormData
All Implemented Interfaces:
Cloneable, Map

public class FormData
extends Object
implements Map, Cloneable

Manages the data associated with forms and other remote sources.

The basic task of a FormData object is to transform a set of key-value string pairs into a validated set of Java data objects for use in subsequent processing. In most cases the original data is an HTTP request.

To perform the transformation, a separate instance of FormModel is used to specify the name and basic data type of each expected parameter in the set, as well as any additional validation steps required. The FormData stores both the transformed data objects and any validation error messages associated with an individual parameter or the form as a whole. Once the data has been validated, individual data objects may be queried from a FormData using the standard get method of the Map interface.

FormData objects may also be used to control the entire lifecycle of self-validating forms, which report errors to the user in the context of the form itself, rather than on a separate page.

See the Forms API Developer Guide for details on using the FormData class.

Version:
$Id: //core-platform/dev/src/com/arsdigita/bebop/FormData.java#10 $
Author:
Karl Goldstein, Uday Mathur, Stas Freidin

Nested Class Summary
 
Nested classes inherited from class java.util.Map
Map.Entry
 
Field Summary
static String versionId
           
 
Constructor Summary
FormData(FormModel model, javax.servlet.http.HttpServletRequest request)
          Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.
FormData(FormModel model, javax.servlet.http.HttpServletRequest request, boolean isSubmission)
          Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.
FormData(FormModel model, javax.servlet.http.HttpServletRequest request, boolean isSubmission, FormData fallback)
          Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.
FormData(FormModel model, javax.servlet.http.HttpServletRequest request, Locale locale)
          Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.
FormData(FormModel model, javax.servlet.http.HttpServletRequest request, Locale locale, boolean isSubmission)
          Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.
FormData(FormModel model, javax.servlet.http.HttpServletRequest request, Locale locale, boolean isSubmission, FormData fallback)
          Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.
 
Method Summary
 void addError(GlobalizedMessage message)
          Reports a validation error on the form as a whole.
 void addError(String message)
          Reports a validation error on the form as a whole.
 void addError(String name, GlobalizedMessage message)
          Adds an error message to the ParameterData object associated with the parameter model identified by name.
 void addError(String name, String message)
          Adds an error message to the ParameterData object associated with the parameter model identified by name.
 String asString()
          Converts to a String.
 void clear()
           
 Object clone()
           
 boolean containsKey(Object key)
           
 boolean containsValue(Object value)
           
 Set entrySet()
           
 void forceValidate(PageState state)
          Validates this FormData object against its form model, regardless of whether the object is currently valid.
 Object get(Object key)
          Returns the value contained by the ParameterData object named by key.
 Object get(ParameterModel m)
          Deprecated. Use get(m.getName()) instead, and then manually check for model identity
 Iterator getAllErrors()
          Returns an iterator over all of the errors on this form.
 Date getDate(Object key)
          Retrieves a date object for the specified parameter name.
 Iterator getErrors()
          Returns an iterator over all the errors on this form that are not associated with any particular parameter.
 Iterator getErrors(String name)
          Returns the errors associated with the specified parameter.
 Integer getInteger(Object key)
          Retrieves an integer object for the specified parameter name.
 ParameterData getParameter(String name)
          Gets the specified ParameterData object.
 Collection getParameters()
          Returns a collection of all the ParameterData objects.
 String getString(Object key)
          Retrieves a String object for the specified parameter name.
 void invalidate()
          Set isValid to false.
 boolean isEmpty()
           
 boolean isSubmission()
          Determines whether this request represents a submission event.
 boolean isTransformed()
          Determines whether the key-value string pairs in the request have been transformed into Java data objects.
 boolean isValid()
          Determines whether any errors were found during validation of a form submission.
 Set keySet()
           
 Object put(Object key, Object value)
           
 void putAll(Map t)
           
 Object remove(Object key)
           
 void setInvalid()
          Deprecated. Use invalidate() instead
 void setParameter(String name, ParameterData value)
          Sets the ParameterData object identified by the name in this FormData Object.
 int size()
           
 String toString()
           
 void validate(PageState state)
          Validates this FormData object according to its form model.
 Collection values()
           
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values
Constructor Detail

FormData

public FormData(FormModel model,
                javax.servlet.http.HttpServletRequest request)
         throws FormProcessException
Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.

Parameters:
model - a FormModel describing the parameters and validation constraints for this request
request - an HTTP request object passed from the servlet container
Throws:
FormProcessException - if an error occurs.

FormData

public FormData(FormModel model,
                javax.servlet.http.HttpServletRequest request,
                boolean isSubmission)
         throws FormProcessException
Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.

Parameters:
model - a FormModel describing the parameters and validation constraints for this request
request - an HTTP request object passed from the servlet container
isSubmission - true if the request should be treated as a form submission by the user
Throws:
FormProcessException - if an error occurs.

FormData

public FormData(FormModel model,
                javax.servlet.http.HttpServletRequest request,
                boolean isSubmission,
                FormData fallback)
         throws FormProcessException
Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request.

Parameters:
model - a FormModel describing the parameters and validation constraints for this request
request - an HTTP request object passed from the servlet container
isSubmission - true if the request should be treated as a form submission by the user
fallback - a fallback FormData object. If a value for a parameter in the form model model is not in the current request parameters, the fallback object is searched.
Throws:
FormProcessException - if an error occurs

FormData

public FormData(FormModel model,
                javax.servlet.http.HttpServletRequest request,
                Locale locale)
         throws FormProcessException
Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request. Error messages are provided in the specified locale.

Parameters:
model - A FormModel describing the parameters and validation constraints for this request.
request - An HTTP request object passed from the servlet container.
locale - The locale for which all error messages will be prepared. This may be used in a multilingual environment to tailor the output to the preferences or geographic location of individual users on a per-request basis.
Throws:
FormProcessException - if an error occurs

FormData

public FormData(FormModel model,
                javax.servlet.http.HttpServletRequest request,
                Locale locale,
                boolean isSubmission)
         throws FormProcessException
Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request. Error messages are provided in the specified locale.

Parameters:
model - A FormModel describing the parameters and validation constraints for this request.
request - An HTTP request object passed from the servlet container.
locale - The locale for which all error messages will be prepared. This may be used in a multilingual environment to tailor the output to the preferences or geographic location of individual users on a per-request basis.
isSubmission - true if the request should be treated as a form submission by the user.
Throws:
FormProcessException - if an error occurs

FormData

public FormData(FormModel model,
                javax.servlet.http.HttpServletRequest request,
                Locale locale,
                boolean isSubmission,
                FormData fallback)
         throws FormProcessException
Constructs a new FormData object containing the transformed and validated query parameters from an HTTP request. Error messages are provided in the specified locale.

Parameters:
model - A FormModel describing the parameters and validation constraints for this request.
request - An HTTP request object passed from the servlet container.
locale - The locale for which all error messages will be prepared. This may be used in a multilingual environment to tailor the output to the preferences or geographic location of individual users on a per-request basis.
isSubmission - true if the request should be treated as a form submission by the user.
fallback - a fallback FormData object. If a value for a parameter in the form model model is not in the current request parameters, the fallback object is searched.
Throws:
FormProcessException - if an error occurs
Method Detail

validate

public void validate(PageState state)
Validates this FormData object according to its form model. If the FormData is already valid, does nothing.

Parameters:
state - describes the current page state

forceValidate

public void forceValidate(PageState state)
Validates this FormData object against its form model, regardless of whether the object is currently valid.

Parameters:
state - describes the current page state

addError

public void addError(String message)
Reports a validation error on the form as a whole.

Parameters:
message - a String of the error message

addError

public void addError(GlobalizedMessage message)
Reports a validation error on the form as a whole.

Parameters:
message - the error message

addError

public void addError(String name,
                     String message)
Adds an error message to the ParameterData object associated with the parameter model identified by name.

Parameters:
name - the name of the parameter model to whose ParameterData the error message will be added
message - the text of the error message to add

addError

public void addError(String name,
                     GlobalizedMessage message)
Adds an error message to the ParameterData object associated with the parameter model identified by name.

Parameters:
name - the name of the parameter model to whose ParameterData the error message will be added
message - the text of the error message to add

getErrors

public Iterator getErrors(String name)
Returns the errors associated with the specified parameter.

Parameters:
name - the name of the parameter whose errors we are interested in
Returns:
an iterator of errors. Each error is just a string for now.

getErrors

public Iterator getErrors()
Returns an iterator over all the errors on this form that are not associated with any particular parameter. Such errors may have been generated by a FormValidationListener.

Returns:
an iterator over error messages.

getAllErrors

public Iterator getAllErrors()
Returns an iterator over all of the errors on this form. This includes both errors associated with particular parameters and errors associated with the form as a whole.

Returns:
an iterator over all error messages.

getParameter

public ParameterData getParameter(String name)
Gets the specified ParameterData object.

Parameters:
name - the name of the parameterModel to retrieve
Returns:
the parameter data object specified.

setParameter

public void setParameter(String name,
                         ParameterData value)
Sets the ParameterData object identified by the name in this FormData Object.

Parameters:
name - the name of the parameterModel

getParameters

public final Collection getParameters()
Returns a collection of all the ParameterData objects.

Returns:
a collection of all the ParameterData objects.

isSubmission

public final boolean isSubmission()
Determines whether this request represents a submission event.

Returns:
true if this request represents a submission event; false if it represents an initialization event.

isTransformed

public final boolean isTransformed()
Determines whether the key-value string pairs in the request have been transformed into Java data objects.

Returns:
true if the key-value string pairs have been transformed into Java data objects; false otherwise.

isValid

public final boolean isValid()
Determines whether any errors were found during validation of a form submission.

Returns:
true if no errors were found; false otherwise.

setInvalid

public void setInvalid()
Deprecated. Use invalidate() instead

Sets isValid to false. We do not allow programmers to manually toggle the isValid value to true. Hence this method takes no arguments and only sets isValid flag to false


invalidate

public final void invalidate()
Set isValid to false. We do not allow programmers to manually toggle the isValid value to true.


clear

public void clear()
Specified by:
clear in interface Map

containsKey

public boolean containsKey(Object key)
Specified by:
containsKey in interface Map

containsValue

public boolean containsValue(Object value)
Specified by:
containsValue in interface Map

entrySet

public Set entrySet()
Specified by:
entrySet in interface Map

get

public Object get(Object key)
           throws IllegalArgumentException
Returns the value contained by the ParameterData object named by key. If no key is found, throws IllegalArgumentException.

Specified by:
get in interface Map
Parameters:
key - the parameter data object to retrieve
Returns:
the value in the specified parameter data object.
Throws:
IllegalArgumentException - thrown when the key is not a valid parameter.

get

public Object get(ParameterModel m)
Deprecated. Use get(m.getName()) instead, and then manually check for model identity


getDate

public Date getDate(Object key)
Retrieves a date object for the specified parameter name.

Parameters:
key - the object to retrieve
Returns:
a date object for the specified parameter name.

getInteger

public Integer getInteger(Object key)
Retrieves an integer object for the specified parameter name.

Parameters:
key - the object to retrieve
Returns:
an integer object for the specified parameter name.

getString

public String getString(Object key)
Retrieves a String object for the specified parameter name.

Parameters:
key - the object to retrieve
Returns:
a string object for the specified parameter name.

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface Map

keySet

public Set keySet()
Specified by:
keySet in interface Map

put

public Object put(Object key,
                  Object value)
Specified by:
put in interface Map

putAll

public void putAll(Map t)
Specified by:
putAll in interface Map

remove

public Object remove(Object key)
Specified by:
remove in interface Map

size

public int size()
Specified by:
size in interface Map

values

public Collection values()
Specified by:
values in interface Map

clone

public Object clone()
             throws CloneNotSupportedException
Throws:
CloneNotSupportedException

toString

public String toString()

asString

public String asString()
Converts to a String. The method toString() returns all errors.

Returns:
a human-readable representation of this.


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