|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.arsdigita.bebop.FormModel
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.
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 |
public static final String versionId
protected EventListenerList m_listenerList
Constructor Detail |
public FormModel(String name)
name
- a URL-encoded keyword used to identify this form modelMethod Detail |
public final String getName()
public final void setName(String name)
public final void addFormParam(ParameterModel parameter)
parameter
- a parameter model objectpublic final void excludeFormParameterFromExport(ParameterModel parameter)
parameter
- a parameter model objectpublic final boolean containsFormParam(ParameterModel p)
p
- the parameter model to check for
true
if the form model contains the specified
parameter model; false
otherwise.public final Iterator getParameters()
public final Iterator getParametersToExclude()
public void addSubmissionListener(FormSubmissionListener listener)
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.
listener
- a FormSubmissionListener
valuepublic void addValidationListener(FormValidationListener listener)
listener
- an instance of a class that implements the
FormValidationListener
interfacepublic void addInitListener(FormInitListener listener)
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.
listener
- an instance of a class that implements the
FormInitListener
interfacepublic void addProcessListener(FormProcessListener listener)
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.
listener
- an instance of a class that implements the
FormProcessListener
interfacepublic FormData process(PageState state) throws FormProcessException
If this is a submission, validates the data and (if the data is valid) calls the process listeners. Returns a FormData object.
state
- the PageState object holding request-specific information
FormProcessException
public FormData process(PageState state, boolean isSubmission) throws FormProcessException
If this is a submission, validates the data and (if the data is valid) calls the process listeners. Returns a FormData object.
state
- the PageState object holding request specific informationisSubmission
- true
if the request is a submission;
false
if this is the first request to the form data.
FormProcessException
protected void fireSubmitted(FormSectionEvent e) throws FormProcessException
FormProcessException
protected void fireFormInit(FormSectionEvent e) throws FormProcessException
e
- a FormSectionEvent originating from the form
FormProcessException
protected void fireParameterValidation(FormSectionEvent e)
e
- a FormSectionEvent originating from the formpublic void lock()
lock
in interface Lockable
public final boolean isLocked()
isLocked
in interface Lockable
true
if this FormModel is locked;
false
otherwise.
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |