RowSetForm Class

com.bea.wlw.netui.databinding.form
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

Field Summary

   
Fields from  org.apache.struts.validator.ValidatorForm
page, validatorResults
 
Fields from  org.apache.struts.action.ActionForm
multipartRequestHandler, servlet
 

Constructor Summary

RowSetForm()

Construct a RowSetForm.
 

Method Summary

public void
applyInsertValuesToRowSet(RowSet rowSet)
Populate the provided RowSet with the properties that have changed since the last time the RowSetForm was initialized or RowSetForm.clearChangedValues() was called.
public void
applyUpdateValuesToRowSet(RowSet rowSet)
Populate the provided RowSet with the properties that have changed since the last time the RowSetForm was initialized or RowSetForm.clearChangedValues() was called.
public void
applyValuesToForm(RowSet rowSet)
Populate the JavaBean properties of the form with the column values from the first row in the RowSet.
public void
clearChangedValues()
Clear the list of changed values.
protected final void
registerChange(String propertyName)
Register a change on a property with the name propertyName.
protected Object
writeForm(String columnName, Object rowSetValue)

A callback that is executed before a value is applied to the form from a RowSet.

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.

 
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
   

Constructor Detail

RowSetForm

public RowSetForm()
Construct a RowSetForm.
 

Method Detail

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