com.arsdigita.bebop
Class FormModel

java.lang.Object
  extended bycom.arsdigita.bebop.FormModel
All Implemented Interfaces:
Lockable

public class FormModel
extends Object
implements Lockable

A container for two classes of objects: ParameterModels and ValidationListeners.

Instances of this class provide a specification for transforming a set of key-value string pairs into a set of validated Java data objects. A single instance of this class can handle all submissions to a particular form.

The most common usage for this class is is to use a private variable in a servlet to store the model, and to construct it in the servlet init method. That way, the model persists for the lifetime of the servlet, reducing the memory and processing overhead for each request.

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

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

Field Summary
protected  EventListenerList m_listenerList
           
static String versionId
           
 
Constructor Summary
FormModel(String name)
          Constructs a new form model.
 
Method Summary
 void addFormParam(ParameterModel parameter)
          Adds a parameter model to the form model.
 void addInitListener(FormInitListener listener)
          Adds a listener for form initialization events.
 void addProcessListener(FormProcessListener listener)
          Adds a listener for form processing events.
 void addSubmissionListener(FormSubmissionListener listener)
          Adds a listener that is called as soon as the FormData has been initialized with the request parameters, but before any of the init, validation, or process listeners are run.
 void addValidationListener(FormValidationListener listener)
          Adds a validation listener, implementing a custom validation check that applies to the form as a whole.
 boolean containsFormParam(ParameterModel p)
          Determines whether the form model contains the specified parameter model.
 void excludeFormParameterFromExport(ParameterModel parameter)
          Adds a parameter model to the list of parameters that should not be exported when the form is rendered.
protected  void fireFormInit(FormSectionEvent e)
          Calls a form initialization listener.
protected  void fireParameterValidation(FormSectionEvent e)
          Private helper method that validates the individual parameters by calling ParameterValidationListeners from the individual parameterModels.
protected  void fireSubmitted(FormSectionEvent e)
           
 String getName()
          Returns the name of this form model.
 Iterator getParameters()
          Returns an iterator over the parameter models contained within the form model.
 Iterator getParametersToExclude()
          Returns an iterator over the parameter models that are contained within the form model but should not be exported as part of the form's state.
 boolean isLocked()
          Checks whether this FormModel is locked.
 void lock()
          Locks this FormModel and all of its ParameterModels.
 FormData process(PageState state)
          Creates a new FormData object that is populated with default values (for an initial request) or values from the request (for a submission).
 FormData process(PageState state, boolean isSubmission)
          Creates a new FormData object that is populated with default values (for an initial request) or values from the request (for a submission).
 void setName(String name)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values

m_listenerList

protected EventListenerList m_listenerList
Constructor Detail

FormModel

public FormModel(String name)
Constructs a new form model.

Parameters:
name - a URL-encoded keyword used to identify this form model
Method Detail

getName

public final String getName()
Returns the name of this form model.

Returns:
a URL-encoded keyword used to identify requests conforming to this form model.

setName

public final void setName(String name)

addFormParam

public final void addFormParam(ParameterModel parameter)
Adds a parameter model to the form model. The parameter model should be fully configured before adding it to the form model.

Parameters:
parameter - a parameter model object

excludeFormParameterFromExport

public final void excludeFormParameterFromExport(ParameterModel parameter)
Adds a parameter model to the list of parameters that should not be exported when the form is rendered. Useful examples of this are for forms that loop back on themselves such as search forms or a control bar. The parameter model should be fully configured and have been added to the form model before adding it to the list of items to exclude

Parameters:
parameter - a parameter model object

containsFormParam

public final boolean containsFormParam(ParameterModel p)
Determines whether the form model contains the specified parameter model.

Parameters:
p - the parameter model to check for
Returns:
true if the form model contains the specified parameter model; false otherwise.

getParameters

public final Iterator getParameters()
Returns an iterator over the parameter models contained within the form model.

Returns:
an iterator over the parameter models contained within the form model.

getParametersToExclude

public final Iterator getParametersToExclude()
Returns an iterator over the parameter models that are contained within the form model but should not be exported as part of the form's state. This is important for situations where the form loops back on itself (e.g. a ControlBar or a Search form).


addSubmissionListener

public void addSubmissionListener(FormSubmissionListener listener)
Adds a listener that is called as soon as the FormData has been initialized with the request parameters, but before any of the init, validation, or process listeners are run. The listener's submitted method may throw a FormProcessException to signal that any further processing of the form should be aborted.

Parameters:
listener - a FormSubmissionListener value

addValidationListener

public void addValidationListener(FormValidationListener listener)
Adds a validation listener, implementing a custom validation check that applies to the form as a whole. Useful for checks that require examination of the values of more than one parameter.

Parameters:
listener - an instance of a class that implements the FormValidationListener interface

addInitListener

public void addInitListener(FormInitListener listener)
Adds a listener for form initialization events.

Initialization events occur when a form is initially requested by the user, but not when the form is subsequently submitted. They typically perform actions such as querying the database for existed values to set up an edit form or obtaining a sequence value to set up a create form.

Parameters:
listener - an instance of a class that implements the FormInitListener interface

addProcessListener

public void addProcessListener(FormProcessListener listener)
Adds a listener for form processing events.

Process events only occur after a form submission has been successfully validated. They are typically used to perform a database transaction or other operation based on the submitted data.

Process listeners are executed in the order in which they are added.

Parameters:
listener - an instance of a class that implements the FormProcessListener interface

process

public FormData process(PageState state)
                 throws FormProcessException
Creates a new FormData object that is populated with default values (for an initial request) or values from the request (for a submission).

If this is a submission, validates the data and (if the data is valid) calls the process listeners. Returns a FormData object.

Parameters:
state - the PageState object holding request-specific information
Returns:
a FormData object.
Throws:
FormProcessException

process

public FormData process(PageState state,
                        boolean isSubmission)
                 throws FormProcessException
Creates a new FormData object that is populated with default values (for an initial request) or values from the request (for a submission).

If this is a submission, validates the data and (if the data is valid) calls the process listeners. Returns a FormData object.

Parameters:
state - the PageState object holding request specific information
isSubmission - true if the request is a submission; false if this is the first request to the form data.
Throws:
FormProcessException

fireSubmitted

protected void fireSubmitted(FormSectionEvent e)
                      throws FormProcessException
Throws:
FormProcessException

fireFormInit

protected void fireFormInit(FormSectionEvent e)
                     throws FormProcessException
Calls a form initialization listener.

Parameters:
e - a FormSectionEvent originating from the form
Throws:
FormProcessException

fireParameterValidation

protected void fireParameterValidation(FormSectionEvent e)
Private helper method that validates the individual parameters by calling ParameterValidationListeners from the individual parameterModels.

Parameters:
e - a FormSectionEvent originating from the form

lock

public void lock()
Locks this FormModel and all of its ParameterModels.

Specified by:
lock in interface Lockable

isLocked

public final boolean isLocked()
Checks whether this FormModel is locked.

Specified by:
isLocked in interface Lockable
Returns:
true if this FormModel is locked; false otherwise.


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