org.barracudamvc.core.forms
Class DefaultFormMap

java.lang.Object
  extended byorg.barracudamvc.core.forms.DefaultFormMap
All Implemented Interfaces:
FormMap, StateMap
Direct Known Subclasses:
ErrorFormMap

public class DefaultFormMap
extends Object
implements FormMap

This class provides the default implementation of a FormMap.

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:

The FormMap uses a pluggable FormMapper to actually control how elements are mapped.

Since:
1.0
Version:
%I%, %G%
Author:
Christian Cryder [christianc@granitepeaks.com], Diez B. Roggisch , Jacob Kjome

Field Summary
protected static Locale defaultLoc
           
protected  Map elements
           
protected  FormMapper formMapper
           
protected static org.apache.log4j.Logger localLogger
           
protected  StateMap statemap
           
protected  List validators
           
protected  Locale zloc
           
 
Constructor Summary
DefaultFormMap()
          Default constructor (uses DefaultFormMapper)
DefaultFormMap(String iprefix)
          Prefix constructor (uses PrefixFormMapper)
 
Method Summary
 void clearState()
          clear all state information
 FormElement defineElement(FormElement element)
          This defines an element to be mapped by this form, using the key from the FormElement.
 FormElement defineElement(String key, FormElement element)
          This defines an element to be mapped by this form, using a manually specified key.
 FormValidator defineValidator(FormValidator validator)
          This defines a validator for the entire form.
 boolean exists(String key)
          Return true if an element exists and its value is not null
 FormElement getElement(String key)
          Get an element by key
 Map getElements()
          return a List with containing all the defined elements in this FormMap
 FormMapper getFormMapper()
          Get the FormMapper for this map
 Locale getLocale()
          Get the working locale for this form
 Object getState(Object key)
          get a property in this StateMap
 Set getStateKeys()
          get a keyset for this StateMap (whether or not the set is backed by the data store depends on the implementation)
 Map getStateStore()
          get a copy of the underlying Map
 Object getVal(String key)
          Get the value for a given key.
 Object getVal(String key, Object dflt)
           
 Object[] getVals(String key)
          Get an array of values for a given key.
 Object[] getVals(String key, Object[] dflt)
           
 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(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.
 FormElement mapElement(String key, Object origVal)
          Map an individual element by specifiying the key and origVal.
 void putState(Object key, Object val)
          set a property in this StateMap
 Object removeState(Object key)
          remove a property in this StateMap
 void setFormMapper(FormMapper imapper)
          Set the FormMapper for this map
 void setLocale(Locale iloc)
          Set the working locale for mapping the elements (null indicates the default locale will be used)
 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 class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

localLogger

protected static final org.apache.log4j.Logger localLogger

elements

protected Map elements

validators

protected List validators

statemap

protected StateMap statemap

defaultLoc

protected static final Locale defaultLoc

zloc

protected Locale zloc

formMapper

protected FormMapper formMapper
Constructor Detail

DefaultFormMap

public DefaultFormMap()
Default constructor (uses DefaultFormMapper)


DefaultFormMap

public DefaultFormMap(String iprefix)
Prefix constructor (uses PrefixFormMapper)

Method Detail

defineElement

public FormElement 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.

Specified by:
defineElement in interface FormMap
Parameters:
element - a FormElement to be mapped by this form
Returns:
a reference to the newly defined FormElement

defineElement

public FormElement defineElement(String key,
                                 FormElement element)
This defines an element to be mapped by this form, using a manually specified key. Generally, you won't need to use this method unless you are writing some kind of framwork that maps multiple elements into a for (ie. with different variations on a name), all via the same fundamental key.

Specified by:
defineElement in interface FormMap
Parameters:
key - a manually specified key
element - a FormElement to be mapped by this form
Returns:
a reference to the newly defined FormElement

defineValidator

public FormValidator 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)

Specified by:
defineValidator in interface FormMap
Parameters:
validator - a form validator to be applied to the entire form
Returns:
a reference to the newly defined FormValidator

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

Specified by:
map in interface FormMap
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(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.

Specified by:
map in interface FormMap
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

mapElement

public FormElement mapElement(String key,
                              Object origVal)
Map an individual element by specifiying the key and origVal. Normally, you'll just map the whole form all at once, but if for some reason you desire to manually map an element at a time, this method gives you the ability to do that.

Specified by:
mapElement in interface FormMap
Parameters:
key - the form map key
origVal - the orig val to be mapped
Returns:
a reference to the FormElement which got mapped (null if it mapper doesn't handle this key)
Throws:
MappingException - if for some reason the value cannot be mapped successfully

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

Specified by:
validate in interface FormMap
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)

Specified by:
validateElements in interface FormMap
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)

Specified by:
validateForm in interface FormMap
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 and its value is not null

Specified by:
exists in interface FormMap
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

Specified by:
getElement in interface FormMap
Parameters:
key - the key which uniquely identifies this FormElement
Returns:
the FormElement for this key (may be null)

getElements

public Map getElements()
return a List with containing all the defined elements in this FormMap

Specified by:
getElements in interface FormMap
Returns:
a copy of the defined elements in 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.

Specified by:
setVal in interface FormMap
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.

Specified by:
getVal in interface FormMap
Parameters:
key - the key which uniquely identifies this FormElement
Returns:
the value for this key (may be null)

getVal

public Object getVal(String key,
                     Object dflt)
Specified by:
getVal in interface FormMap

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

Specified by:
getVals in interface FormMap
Parameters:
key - the key which uniquely identifies this FormElement
Returns:
the value for this key (may be null)

getVals

public Object[] getVals(String key,
                        Object[] dflt)
Specified by:
getVals in interface FormMap

setLocale

public void setLocale(Locale iloc)
Set the working locale for mapping the elements (null indicates the default locale will be used)

Specified by:
setLocale in interface FormMap

getLocale

public Locale getLocale()
Get the working locale for this form

Specified by:
getLocale in interface FormMap

setFormMapper

public void setFormMapper(FormMapper imapper)
Set the FormMapper for this map

Specified by:
setFormMapper in interface FormMap

getFormMapper

public FormMapper getFormMapper()
Get the FormMapper for this map

Specified by:
getFormMapper in interface FormMap

putState

public void putState(Object key,
                     Object val)
set a property in this StateMap

Specified by:
putState in interface StateMap
Parameters:
key - the state key object
val - the state value object

getState

public Object getState(Object key)
get a property in this StateMap

Specified by:
getState in interface StateMap
Parameters:
key - the state key object
Returns:
the value for the given key

removeState

public Object removeState(Object key)
remove a property in this StateMap

Specified by:
removeState in interface StateMap
Parameters:
key - the key object
Returns:
the object which was removed

getStateKeys

public Set getStateKeys()
get a keyset for this StateMap (whether or not the set is backed by the data store depends on the implementation)

Specified by:
getStateKeys in interface StateMap
Returns:
a Set of keys for this StateMap

getStateStore

public Map getStateStore()
get a copy of the underlying Map

Specified by:
getStateStore in interface StateMap
Returns:
a copy of the underlying state Map

clearState

public void clearState()
clear all state information

Specified by:
clearState in interface StateMap


Copyright © 2004 BarracudaMVC.org All Rights Reserved.