Simple Data Binding

Simple data binding refers to the relationship between a field in a recordset and the property of a WFC component. When a property is bound, data is automatically transferred between the field and the property:

• If the value of the field changes, the new value is propagated to the property.
  
  
• If a new row in the recordset is navigated to, the current field value is propagated to the property.
  
  
• If the value of the property changes and the component supports a property change notification, the new value is propagated to the field in the recordset. Note that the recordset is immediately updated when the property changes (unlike the Visual Basic simple data binding model, which postpones all property change notifications until a new row is navigated to).

  Note   If an attempt is made to update a read-only recordset, the recordset will generate an ADO exception. You can then catch this exception and set the bound property back to its previous value; otherwise, the value of the property and the value of the field will be inconsistent.

Bindable Properties

Simple data binding in WFC is performed by the DataBinder component. This component creates and manages the binding between the field and the property. The DataBinder component can bind any property that is accessible through methods matching the following design patterns:

public <PropertyType> get<PropertyName>()
public void set<PropertyName>(<PropertyType>)

If a property is marked with the NotBindable attribute, then it is not enumerated in the DataBinder componentÆs design page and cannot be bound within the Designer; however, you can still bind the property programmatically. The NotBindable attribute is specified in the componentÆs ClassInfo. Typically, the name property is marked as NotBindable.

Note   The DataBinder component does not support indexed properties. The DataBinder component will not enumerate indexed properties in its design page, and will generate a Java exception if you attempt to bind an indexed property programmatically.

Property Change Requests and Notifications

The component of a bound property can provide events that signal when a property is about to be changed (a request) and when the property has been changed (a notification):

• To support a property change request, the component provides a <PropertyName>Changing event. This event is triggered before the property is actually changed, and can be canceled to prevent the change.
  
  
• To support a property change notification, the component provides a <PropertyName>Changed event. This event is triggered after the property has been changed, and causes the associated field in the recordset to be updated with the new value.

  Note   By default, no data validation is performed before the recordset is updated. However, you can use the Changing events on the recordset to validate the new property value.