com.bea.wlw.netui.databinding.form
Class RowSetForm

java.lang.Object
  org.apache.struts.action.ActionForm
      org.apache.struts.validator.ValidatorForm
          org.apache.beehive.netui.pageflow.internal.BaseActionForm
              org.apache.beehive.netui.pageflow.FormData
                  com.bea.wlw.netui.databinding.form.RowSetForm

All Implemented Interfaces:

Serializable

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 JdbcControl instance, the action form needs to be populated with values from this RowSet. This is done with one method, 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 applyInsertValuesToRowSet(javax.sql.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 applyUpdateValuesToRowSet(javax.sql.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 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.

See Also:

Serialized Form

Field Summary

Fields inherited from class org.apache.struts.validator.ValidatorForm

page, validatorResults

Fields inherited from class org.apache.struts.action.ActionForm

multipartRequestHandler, servlet

Constructor Summary

RowSetForm()
Construct a RowSetForm.

Method Summary

void	applyInsertValuesToRowSet(RowSet rowSet) Populate the provided RowSet with the properties that have changed since the last time the RowSetForm was initialized or clearChangedValues() was called.
void	applyUpdateValuesToRowSet(RowSet rowSet) Populate the provided RowSet with the properties that have changed since the last time the RowSetForm was initialized or clearChangedValues() was called.
void	applyValuesToForm(RowSet rowSet) Populate the JavaBean properties of the form with the column values from the first row in the RowSet.
void	clearChangedValues() Clear the list of changed values.
protected 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 inherited from class org.apache.beehive.netui.pageflow.internal.BaseActionForm

getAdditionalActionErrors, validate, validateBean

Methods inherited from class org.apache.struts.validator.ValidatorForm

getPage, getResultValueMap, getValidationKey, getValidatorResults, reset, setPage, setValidatorResults

Methods inherited from class org.apache.struts.action.ActionForm

getMultipartRequestHandler, getServlet, getServletWrapper, reset, setMultipartRequestHandler, setServlet, validate

Methods inherited 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

writeForm

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 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 writeRowSet(String, Object, Object). See 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

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 applyInsertValuesToRowSet(RowSet) or 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 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

applyInsertValuesToRowSet

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 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 ResultSet.insertRow() and ResultSet.moveToCurrentRow() lifecycle methods are called.

Parameters:

rowSet - the RowSet into which to insert the form's JavaBean properties

Throws:

RowSetFormException - if an error occurs whlie inserting values into a RowSet from the changed properties.

applyUpdateValuesToRowSet

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 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

Throws:

RowSetFormException - if an error occurs whlie inserting values into a RowSet from the changed properties.

applyValuesToForm

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

Throws:

RowSetFormException - if an error occurs whlie applying values to the form from the RowSet

clearChangedValues

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

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 applyUpdateValuesToRowSet(RowSet) or applyInsertValuesToRowSet(RowSet) are called