RowSetForm Class
- public abstract class RowSetForm
extends FormData
A RowSetForm is a FormData
base class that provides support for RowSet
data sets.
This support allows an extension of this class to specify strongly-typed JavaBean properties
that map to data in the RowSet; this base class is then able to populate these JavaBean properties
from a RowSet and populate a RowSet from the JavaBean properties.
This two-way population ability is important because of the PageFlow request lifecyle. If in an
action a RowSet is created or is returned by a
instance, the action form needs to be populated with values from this RowSet. This is done with
one method, RowSetForm.applyValuesToForm(RowSet)
. This method inspects the RowSetMetaData
for the RowSet and for every column whose name matches a JavaBean property name on an instance
of this class, that property is populated with the value from the RowSet. Note, the types
in the RowSet and the type of the property in this form must match.
Then, on a request, the parameters from the request are populated into an instance of this form. Then,
the instance of the form can be used to populate a row in the RowSet. This can be done with one
of two methods depending on how the RowSet is being used. The RowSetForm.applyInsertValuesToRowSet(RowSet)
should be used when a new row is being added to the RowSet. The values will be inserted
into the RowSet's insert row. The RowSetForm.applyUpdateValuesToRowSet(RowSet)
should be used
when the "current" row in the RowSet should be updated. In both cases, the properties
in the form that have changed as a result of being populated with request data will
be applied to the RowSet.
In order to populate a RowSet with exactly the data that has changed, a subclass of the
RowSetForm can track the changes in the JavaBean setter methods by using the
RowSetForm.registerChange(String)
method. This method allows the RowSetForm base class to
keep track of all of the setters which have been called before populating a RowSet
with the changed data. Once a RowSet has been populated with the data, the list of
changed values is cleared.
-
Hierarchy
-
Object
ActionForm
ValidatorForm
FormData
RowSetForm
-
All Implemented Interfaces
-
Serializable
Fields from org.apache.struts.validator.ValidatorForm |
page, validatorResults |
Fields from org.apache.struts.action.ActionForm |
multipartRequestHandler, servlet |
Methods from org.apache.struts.validator.ValidatorForm |
getPage, getResultValueMap, getValidatorResults, log, log, reset, setPage, setValidatorResults, validate |
Methods from org.apache.struts.action.ActionForm |
getMultipartRequestHandler, getServlet, getServletWrapper, reset, reset, setMultipartRequestHandler, setServlet, validate, validate |
Methods from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
RowSetForm
public RowSetForm()
- Construct a RowSetForm.
applyInsertValuesToRowSet(RowSet) Method
public void applyInsertValuesToRowSet(RowSet
rowSet)
throws RowSetFormException
Populate the provided RowSet with the properties that have changed since the last
time the RowSetForm was initialized or RowSetForm.clearChangedValues()
was called. These
values will be applied to the RowSet in the "insert" row. This method expects the RowSet
to be in "default" state. Then, the values will be inserted into the RowSet and the
RowSet's RowSet.insertRow()
and RowSet.moveToCurrentRow()
lifecycle methods are called.
Parameters
-
rowSet
- the RowSet into which to insert the form's JavaBean properties
Exceptions
-
RowSetFormException
- if an error occurs whlie inserting values into a RowSet from the changed properties.
applyUpdateValuesToRowSet(RowSet) Method
public void applyUpdateValuesToRowSet(RowSet
rowSet)
throws RowSetFormException
Populate the provided RowSet with the properties that have changed since the last
time the RowSetForm was initialized or RowSetForm.clearChangedValues()
was called. These
values will be applied to the RowSet in the "current" row. This method expects the
RowSet to be in its "default" state. Then, the values will be set on the RowSet in
order to update the values of the "current" row.
Parameters
-
rowSet
- the RowSet into which to insert the form's JavaBean properties
Exceptions
-
RowSetFormException
- if an error occurs whlie inserting values into a RowSet from the
changed properties.
applyValuesToForm(RowSet) Method
public void applyValuesToForm(RowSet
rowSet)
throws RowSetFormException
Populate the JavaBean properties of the form with the column values from the first row
in the RowSet. This will populate the properties whose names match, in a case insensitive way,
each column name in the RowSet's RowSetMetaData
. The values that will populate
the bean will be taken from the first row of the RowSet.
Parameters
-
rowSet
- the RowSet from which to read values that are set on the RowSetForm's JavaBean properties
Exceptions
-
RowSetFormException
- if an error occurs whlie applying values to the form from the RowSet
clearChangedValues() Method
public void clearChangedValues()
Clear the list of changed values. This method can be used so that a RowSetForm
instance may be reused multiple times for multiple RowSet instances.
registerChange(String) Method
protected final void registerChange(String
propertyName)
Register a change on a property with the name propertyName
. This method
should be called from any setter whose value changes should be tracked so that
a RowSet is updated with the correctly changed values. Implementing a JavaBean setter
that does not call this method will result in the changed value of the property never
being updated on a RowSet
if either RowSetForm.applyUpdateValuesToRowSet(RowSet)
or
RowSetForm.applyInsertValuesToRowSet(RowSet)
are called
writeForm(String, Object) Method
protected Object
writeForm(String
columnName,
Object
rowSetValue)
A callback that is executed before a value is applied to the form
from a RowSet. When using an instance of a RowSetForm via the
RowSetForm.applyValuesToForm(RowSet)
method, this callback is invoked
for each of the columns in the RowSet when the column's value is
applied to the form.
Any changes to the type of a column's value done here should be paired
with the inverse change in the RowSetForm.writeRowSet(String, Object, Object)
.
See RowSetForm.writeRowSet(String, Object, Object)
for more information on
how to use this feature.
Comparisons against the column name should be done using the String.equalsIgnoreCase(String)
method as the capitalization of the column from the database and the name of the
property in the form may be different.
Parameters
-
columnName
- the name of the column that is being set
-
rowSetValue
- the value of the column in the RowSet
Returns
- the object to set on the form
writeRowSet(String, Object, Object) Method
protected Object
writeRowSet(String
columnName,
Object
formValue,
Object
oldRowSetValue)
A callback that is executed before a value is applied to a RowSet from
one of the form's properties. When using an instance of a RowSetForm via
the RowSetForm.applyInsertValuesToRowSet(RowSet)
or RowSetForm.applyUpdateValuesToRowSet(RowSet)
methods, the properties of an extending class are must be set on the RowSet.
These are set based on a case-insensitive String comparison of the column
names in the RowSet and the property names in the form. Each column that
will be set on the RowSet is passed through this method using the value matching
the column name from the form and that from the current row in the RowSet.
In this method, custom type conversion logic can be implemented to coerce the type
of the form's value into one that the RowSet can handle. For example, the Timestamp
class mandates a specific time format, but often a different format is used
for entering dates in a web page. The value can be stored as a String
in the form and converted into the Timestamp
in this
method by using a date formatter to switch between the two. Note, in
order to set properties on the RowSet which are different types than the form,
the RowSetForm.writeForm(String, Object)
method must be implemented to convert
from the database / RowSet specifc type to the type in the form.
Comparisons against the column name should be done using the String.equalsIgnoreCase(String)
method as the capitalization of the column from the database and the name of the
property in the form may be different.
Parameters
-
columnName
- the name of the column that is being set
-
formValue
- the value of this column's value from the form
-
oldRowSetValue
- the value of this column in the RowSet
Returns
- the value to set on the RowSet