org.enhydra.barracuda.core.forms
Interface FormMap

All Superinterfaces:
StateMap
All Known Implementing Classes:
DefaultFormMap

public interface FormMap
extends StateMap

A FormMap is used to provide a virtual representation of a form. It can contain any number of unique FormElements, and it can also be associated with FormValidators. The primary function of a form map is to:

Since:
1.0
Version:
%I%, %G%
Author:
Christian Cryder
, Diez B. Roggisch , Jacob Kjome

Method Summary
 void defineElement(FormElement element)
          This defines an element to be mapped by this form, using the key from the FormElement.
 void defineElement(java.lang.String key, FormElement element)
          This defines an element to be mapped by this form.
 void defineValidator(FormValidator validator)
          This defines a validator for the entire form.
 boolean exists(java.lang.String key)
          Return true if an element exists (not null)
 FormElement getElement(java.lang.String key)
          Get an element by key
 java.util.Map getElements()
          return a map with containing all the elements in this form map
 java.lang.Object getVal(java.lang.String key)
          Get the value for a given key.
 FormMap map(javax.servlet.ServletRequest req)
          This is where we actually take an incoming form (in the form of a ServletRequest) and map it using the definitions supplied by all the FormElements.
 FormMap map(javax.servlet.ServletRequest req, java.util.Locale loc)
          This is where we actually take an incoming form (in the form of a ServletRequest) and map it using the definitions supplied by all the FormElements.
 FormMap map(javax.servlet.ServletRequest req, java.lang.String prefix)
          This is where we actually take an incoming form (in the form of a ServletRequest) and map it using the definitions supplied by all the FormElements.
 FormMap map(javax.servlet.ServletRequest req, java.lang.String prefix, java.util.Locale loc)
          This is where we actually take an incoming form (in the form of a ServletRequest) and map it using the definitions supplied by all the FormElements.
 FormMap map(StateMap map)
          This is where we actually take an incoming form (in the form of a StateMap) and map it using the definitions supplied by all the FormElements.
 FormMap map(StateMap map, java.util.Locale loc)
          This is where we actually take an incoming form (in the form of a StateMap) and map it using the definitions supplied by all the FormElements.
 FormMap map(StateMap map, java.lang.String prefix)
          This is where we actually take an incoming form (in the form of a StateMap) and map it using the definitions supplied by all the FormElements.
 FormMap map(StateMap map, java.lang.String prefix, java.util.Locale loc)
          This is where we actually take an incoming form (in the form of a StateMap) and map it using the definitions supplied by all the FormElements.
 FormElement mapElement(java.lang.String key, java.lang.Object origVal)
          This allows you to map a single value (as opposed to passing in a whole statemap or request).
 FormElement mapElement(java.lang.String key, java.lang.Object origVal, java.util.Locale loc)
          This allows you to map a single value (as opposed to passing in a whole statemap or request).
 void setVal(java.lang.String key, java.lang.Object val)
          Manually set the value of an element.
 FormMap validate(boolean deferExceptions)
          Validate the entire form (both form level and elements).
 FormMap validateElements(boolean deferExceptions)
          Validate just the elements (not the form)
 FormMap validateForm(boolean deferExceptions)
          Validate just the form (not the individual elements)
 
Methods inherited from interface org.enhydra.barracuda.core.util.data.StateMap
getState, getStateKeys, getStateValues, putState, removeState
 

Method Detail

defineElement

public void defineElement(FormElement element)
This defines an element to be mapped by this form, using the key from the FormElement. You would invoke this method for each element in the form.

Parameters:
element - a FormElement to be mapped by this form

defineElement

public void defineElement(java.lang.String key,
                          FormElement element)
This defines an element to be mapped by this form. You would invoke this method for each element in the form.

Parameters:
key - the key which uniquely identifies this FormElement
element - a FormElement to be mapped by this form

defineValidator

public void defineValidator(FormValidator validator)
This defines a validator for the entire form. This validator will be invoked prior to validating specific form element validators. Calling this method multiple times will result in multiple form validators being added to the form (they will be invoked in the order they were added)

Parameters:
validator - a form validator to be applied to the entire form

map

public FormMap map(javax.servlet.ServletRequest req)
This is where we actually take an incoming form (in the form of a ServletRequest) and map it using the definitions supplied by all the FormElements. If there are multiple parameters for a given key, the values will be mapped into List structures The DefaultLocale will be used.

Parameters:
req - the ServletRequest to map paramters from based on all defined FormElements
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
MappingException - if for some reason the value cannot be mapped successfully

map

public FormMap map(javax.servlet.ServletRequest req,
                   java.util.Locale loc)
This is where we actually take an incoming form (in the form of a ServletRequest) and map it using the definitions supplied by all the FormElements. If there are multiple parameters for a given key, the values will be mapped into List structures

Parameters:
req - the ServletRequest to map paramters from based on all defined FormElements
loc - the locale to use when parsing Dates and other locale dependend values.
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
MappingException - if for some reason the value cannot be mapped successfully

map

public FormMap map(StateMap map)
This is where we actually take an incoming form (in the form of a StateMap) and map it using the definitions supplied by all the FormElements. The DefaultLocale will be used.

Parameters:
map - the StateMap to map properties from based on all defined FormElements
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
MappingException - if for some reason the value cannot be mapped successfully

map

public FormMap map(StateMap map,
                   java.util.Locale loc)
This is where we actually take an incoming form (in the form of a StateMap) and map it using the definitions supplied by all the FormElements.

Parameters:
map - the StateMap to map properties from based on all defined FormElements
loc - the locale to use when parsing Dates and other locale dependend values.
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
MappingException - if for some reason the value cannot be mapped successfully

map

public FormMap map(StateMap map,
                   java.lang.String prefix)
This is where we actually take an incoming form (in the form of a StateMap) and map it using the definitions supplied by all the FormElements. A given prefix is also taken into account.

Parameters:
map - the StateMap to map properties from based on all defined FormElements
prefix - the prefix to use when mapping parameters
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
MappingException - if for some reason the value cannot be mapped successfully

map

public FormMap map(StateMap map,
                   java.lang.String prefix,
                   java.util.Locale loc)
This is where we actually take an incoming form (in the form of a StateMap) and map it using the definitions supplied by all the FormElements. if a prefix is given, only the parameters which start with that prefix are mapped. Important: They are mapped to their name without that prefix.

Parameters:
map - the StateMap to map properties from based on all defined FormElements
prefix - the prefix to use when mapping parameters
loc - the locale to use when parsing Dates and other locale dependend values.
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
MappingException - if for some reason the value cannot be mapped successfully

map

public FormMap map(javax.servlet.ServletRequest req,
                   java.lang.String prefix,
                   java.util.Locale loc)
This is where we actually take an incoming form (in the form of a ServletRequest) and map it using the definitions supplied by all the FormElements. If there are multiple parameters for a given key, the values will be mapped into List structures if a prefix is given, only the parameters which start with that prefix are mapped. Important: They are mapped to their name without that prefix.

Parameters:
req - the ServletRequest to map paramters from based on all defined FormElements
prefix - the prefix to use when mapping parameters
loc - the locale to use when parsing Dates and other locale dependend values.
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
MappingException - if for some reason the value cannot be mapped successfully

map

public FormMap map(javax.servlet.ServletRequest req,
                   java.lang.String prefix)
This is where we actually take an incoming form (in the form of a ServletRequest) and map it using the definitions supplied by all the FormElements. If there are multiple parameters for a given key, the values will be mapped into List structures A given prefix is also taken into account.

Parameters:
req - the ServletRequest to map paramters from based on all defined FormElements
prefix - the prefix to use when mapping parameters
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
MappingException - if for some reason the value cannot be mapped successfully

mapElement

public FormElement mapElement(java.lang.String key,
                              java.lang.Object origVal)
This allows you to map a single value (as opposed to passing in a whole statemap or request).

Parameters:
key - the name of the element we wish to map to
origVal - the original value to be mapped
Returns:
the newly mapped form element

mapElement

public FormElement mapElement(java.lang.String key,
                              java.lang.Object origVal,
                              java.util.Locale loc)
This allows you to map a single value (as opposed to passing in a whole statemap or request).

Parameters:
key - the name of the element we wish to map to
origVal - the original value to be mapped
loc - the locale to use when parsing Dates and other locale dependant values.
Returns:
the newly mapped form element

validate

public FormMap validate(boolean deferExceptions)
                 throws ValidationException
Validate the entire form (both form level and elements). We start by invoking form validators which apply to individual form elements, then we invoke any which apply to the entire form

Parameters:
deferExceptions - do we want to deferValidation exceptions and attempt to validate all elements so that we can process all the exceptions at once
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
ValidationException - if the form (or any element within it) is invalid

validateElements

public FormMap validateElements(boolean deferExceptions)
                         throws ValidationException
Validate just the elements (not the form)

Parameters:
deferExceptions - do we want to deferValidation exceptions and attempt to validate all elements so that we can process all the exceptions at once
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
ValidationException - if the form (or any element within it) is invalid

validateForm

public FormMap validateForm(boolean deferExceptions)
                     throws ValidationException
Validate just the form (not the individual elements)

Parameters:
deferExceptions - do we want to deferValidation exceptions and attempt to validate all elements so that we can process all the exceptions at once
Returns:
a reference to the FormMap (we do this so you can inline map/validate requests if you desire: form.map(req).validate())
Throws:
ValidationException - if the form (or any element within it) is invalid

exists

public boolean exists(java.lang.String key)
Return true if an element exists (not null)

Parameters:
key - the key which uniquely identifies this FormElement
Returns:
true if an element exists (not null)

getElement

public FormElement getElement(java.lang.String key)
Get an element by key

Parameters:
key - the key which uniquely identifies this FormElement
Returns:
the FormElement for this key (may be null)

getElements

public java.util.Map getElements()
return a map with containing all the elements in this form map

Returns:
a copy of the Map that backs this FormMap

setVal

public void setVal(java.lang.String key,
                   java.lang.Object val)
Manually set the value of an element. If an element does not exist for this key one will be created.

Parameters:
key - the key
val - the value for the key

getVal

public java.lang.Object getVal(java.lang.String key)
Get the value for a given key. This is basically a convenience method. You could manually grab the FormElement using getElement and then retrieve the value that way as well.

Parameters:
key - the key which uniquely identifies this FormElement
Returns:
the value for this key (may be null)


Copyright © 2001 Enhydra.org