com.arsdigita.bebop
Class FormData

java.lang.Object
  com.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.