# 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