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 [christianc@granitepeaks.com], 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(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(String key)
          Return true if an element exists (not null)
 Boolean getBooleanVal(String key)
          Get an Boolean value from the map
 Boolean getBooleanVal(String key, Boolean dflt)
          Get the value for a given key, defaulting accordingly if the value is null.
 Date getDateVal(String key)
          Get an Date value from the map
 Date getDateVal(String key, Date dflt)
          Get the value for a given key, defaulting accordingly if the value is null.
 Double getDoubleVal(String key)
          Get an Double value from the map
 Double getDoubleVal(String key, Double dflt)
          Get the value for a given key, defaulting accordingly if the value is null.
 FormElement getElement(String key)
          Get an element by key
 Map getElements()
          return a map with containing all the elements in this form map
 Map getElementVals()
          return a map with containing the values for all the elements in this form map
 Float getFloatVal(String key)
          Get an Float value from the map
 Float getFloatVal(String key, Float dflt)
          Get the value for a given key, defaulting accordingly if the value is null.
 Integer getIntegerVal(String key)
          Get an Integer value from the map
 Integer getIntegerVal(String key, Integer dflt)
          Get the value for a given key, defaulting accordingly if the value is null.
 Long getLongVal(String key)
          Get an Long value from the map
 Long getLongVal(String key, Long dflt)
          Get the value for a given key, defaulting accordingly if the value is null.
 Short getShortVal(String key)
          Get an Short value from the map
 Short getShortVal(String key, Short dflt)
          Get the value for a given key, defaulting accordingly if the value is null.
 String getStringVal(String key)
          Get a String value from the map
 String getStringVal(String key, String dflt)
          Get the value for a given key, defaulting accordingly if the value is null.
 Object getVal(String key)
          Get the value for a given key.
 Object[] getVals(String key)
          Get an array of values 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, 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, 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, String prefix, 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, 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, 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, String prefix, 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(String key, Object origVal)
          This allows you to map a single value (as opposed to passing in a whole statemap or request).
 FormElement mapElement(String key, Object origVal, Locale loc)
          This allows you to map a single value (as opposed to passing in a whole statemap or request).
 void setVal(String key, 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.plankton.data.StateMap
clearState, 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(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,
                   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,
                   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,
                   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,
                   String prefix,
                   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,
                   String prefix,
                   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,
                   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(String key,
                              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(String key,
                              Object origVal,
                              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(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(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 Map getElements()
return a map with containing all the elements in this form map

Returns:
a copy of the Map that backs this FormMap

getElementVals

public Map getElementVals()
return a map with containing the values for all the elements in this form map

Returns:
a copy of the element values Map that backs this FormMap

setVal

public void setVal(String key,
                   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 Object getVal(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. Note that if the particular FormElement supports multiple values, then this call will only return the first value in the array; to get all the values, use the getVals() function.

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

getVals

public Object[] getVals(String key)
Get an array of values 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. You should only use this method if the particular FormElement has allowMultiples = true

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

getStringVal

public String getStringVal(String key)
Get a String value from the map

Parameters:
key - the form element key
Returns:
the value for the given key (may be null if the value is not set or the key does not match a known form element)

getStringVal

public String getStringVal(String key,
                           String dflt)
Get the value for a given key, defaulting accordingly if the value is null.

Parameters:
key - the key which uniquely identifies this FormElement
dflt - the default value to be used if the underlying value is null
Returns:
the value for this key (may be null)

getBooleanVal

public Boolean getBooleanVal(String key)
Get an Boolean value from the map

Parameters:
key - the form element key
Returns:
the value for the given key (may be null if the value is not set or the key does not match a known form element)

getBooleanVal

public Boolean getBooleanVal(String key,
                             Boolean dflt)
Get the value for a given key, defaulting accordingly if the value is null.

Parameters:
key - the key which uniquely identifies this FormElement
dflt - the default value to be used if the underlying value is null
Returns:
the value for this key (may be null)

getIntegerVal

public Integer getIntegerVal(String key)
Get an Integer value from the map

Parameters:
key - the form element key
Returns:
the value for the given key (may be null if the value is not set or the key does not match a known form element)

getIntegerVal

public Integer getIntegerVal(String key,
                             Integer dflt)
Get the value for a given key, defaulting accordingly if the value is null.

Parameters:
key - the key which uniquely identifies this FormElement
dflt - the default value to be used if the underlying value is null
Returns:
the value for this key (may be null)

getDateVal

public Date getDateVal(String key)
Get an Date value from the map

Parameters:
key - the form element key
Returns:
the value for the given key (may be null if the value is not set or the key does not match a known form element)

getDateVal

public Date getDateVal(String key,
                       Date dflt)
Get the value for a given key, defaulting accordingly if the value is null.

Parameters:
key - the key which uniquely identifies this FormElement
dflt - the default value to be used if the underlying value is null
Returns:
the value for this key (may be null)

getLongVal

public Long getLongVal(String key)
Get an Long value from the map

Parameters:
key - the form element key
Returns:
the value for the given key (may be null if the value is not set or the key does not match a known form element)

getLongVal

public Long getLongVal(String key,
                       Long dflt)
Get the value for a given key, defaulting accordingly if the value is null.

Parameters:
key - the key which uniquely identifies this FormElement
dflt - the default value to be used if the underlying value is null
Returns:
the value for this key (may be null)

getShortVal

public Short getShortVal(String key)
Get an Short value from the map

Parameters:
key - the form element key
Returns:
the value for the given key (may be null if the value is not set or the key does not match a known form element)

getShortVal

public Short getShortVal(String key,
                         Short dflt)
Get the value for a given key, defaulting accordingly if the value is null.

Parameters:
key - the key which uniquely identifies this FormElement
dflt - the default value to be used if the underlying value is null
Returns:
the value for this key (may be null)

getDoubleVal

public Double getDoubleVal(String key)
Get an Double value from the map

Parameters:
key - the form element key
Returns:
the value for the given key (may be null if the value is not set or the key does not match a known form element)

getDoubleVal

public Double getDoubleVal(String key,
                           Double dflt)
Get the value for a given key, defaulting accordingly if the value is null.

Parameters:
key - the key which uniquely identifies this FormElement
dflt - the default value to be used if the underlying value is null
Returns:
the value for this key (may be null)

getFloatVal

public Float getFloatVal(String key)
Get an Float value from the map

Parameters:
key - the form element key
Returns:
the value for the given key (may be null if the value is not set or the key does not match a known form element)

getFloatVal

public Float getFloatVal(String key,
                         Float dflt)
Get the value for a given key, defaulting accordingly if the value is null.

Parameters:
key - the key which uniquely identifies this FormElement
dflt - the default value to be used if the underlying value is null
Returns:
the value for this key (may be null)


Copyright © 2003 BarracudaMVC.org All Rights Reserved.