com.sssw.rt.event
Class AgoBindingManager

java.lang.Object
 |
 +--com.sssw.rt.event.AgoBindingManager

All Implemented Interfaces:

AgiRowCursorListener, AgiRowSetListener, EventListener, PropertyChangeListener, VetoableChangeListener

public class AgoBindingManager

extends Object

implements AgiRowCursorListener, AgiRowSetListener, VetoableChangeListener, PropertyChangeListener

AgoBindingManager is used in a SilverStream form or page to manage relationships between controls and data sources. A control can be bound to a data source column so that updates to the data source are automatically reflected in the control, and changes to the control automatically update the data source.

AgoBindingManager also manages any expressions that are entered at design time for values and properties of controls.

Every SilverStream form and page has an AgoBindingManager named agDataMgr which should be used for all binding services.

Constructor Summary

AgoBindingManager()

Method Summary

void	beginFind() Changes to "Find" mode.
void	bind(Object control, String controlPropName, String readMethod, String writeMethod, AgiRowCursor dataSource, Object dsProperty) Binds a property of a control to a property (a column) of a data source.
void	cancelFind() Cancels "Find" mode.
void	doFind() Performs a query-by-example, based on values entered into bound controls since the last call to beginFind().
void	evaluateAllExpressions() Re-evaluates all expressions on this form or page which are used as properties of controls.
void	propertyChange(PropertyChangeEvent evt) Property change listener method.
void	unbind(Object control, String propName) Breaks a binding between a control property and a data source property.
boolean	validateAll() Triggers the global validation process for a page or form.
void	vetoableChange(PropertyChangeEvent evt) Vetoable property change listener method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods implemented from interface com.sssw.rt.event.AgiRowCursorListener

cursorChanged, cursorPreChange

Methods implemented from interface com.sssw.rt.event.AgiRowSetListener

dataReceivedAsync, dataReloaded, rowDataChanged, rowDeleted, rowInserted, rowPreDelete, rowPreInsert

Constructor Detail

AgoBindingManager

public AgoBindingManager()

Method Detail

bind

public void bind(Object control,
                 String controlPropName,
                 String readMethod,
                 String writeMethod,
                 AgiRowCursor dataSource,
                 Object dsProperty)

Binds a property of a control to a property (a column) of a data source. The data source can be an agData, AgcData, AgpData or any object that implements AgiRowCursor. The control will display the value of the data source's property. If the user edits the control's value, the data source property will be updated accordingly.

Parameters:

control - the control to be used to display and edit the value of the bound property

controlPropName - the name of the control's property that is bound to the data source property. The control must fire a propertyChanged event using this property name when this property changes.

readMethod - the name of the method on the control that can be used to retrieve this property's value. This method must take no arguments.

writeMethod - the name of the method on the control that can be used to set the value of the bound property. This method must take exactly one argument, of the same type as the return value of the readMethod.

dataSource - the data source which provides a value for the bound property

dsProperty - the name or index (as java.lang.Integer) of the property (or column) of the data source that provides the value.

Example:

   // This code binds the "Date" property of a calendar control to the "Date of Hire" column
   // of a database table represented by agcData1
   agDataMgr.bind(ctrlCalendar, "Date", "getDate", "setDate", agcData1, "Date_of_hire");
 

unbind

public void unbind(Object control,
                   String propName)

Breaks a binding between a control property and a data source property. This can be a binding created with AgoBindingManager.bind() or a binding created at design time using the graphical user interface.

Parameters:

control - the control to be unbound

propName - the property to be unbound

Example:

    // This code disassociates the "Date" property of a calendar control from any data source property
    agDataMgr.unbind(ctrlCalendar, "Date");
 

beginFind

public void beginFind()

Changes to "Find" mode. In Find mode, control changes are cached until a call to doFind(), which translates the control values into a query-by-example. All bound controls on the form or page are cleared out. The end-user can enter data into the controls without affecting the underlying data.

When the application calls agDataMgr.doFind(), the binding manager uses the entered information to construct a query, which it then passes to the underlying data sources.

Example:

   agDataMgr.beginFind();
 

cancelFind

public void cancelFind()

Cancels "Find" mode.

doFind

public void doFind()
            throws AgoSecurityException,
                   AgoTransientSystemException,
                   AgoUnrecoverableSystemException

Performs a query-by-example, based on values entered into bound controls since the last call to beginFind().

Requeries all bound data sources, even those for which no values have been entered. This allows these data sources to retrieve all records.

Example:

   agDataMgr.doFind();
 

evaluateAllExpressions

public void evaluateAllExpressions()

Re-evaluates all expressions on this form or page which are used as properties of controls. This ensures that the expression values reflect the latest values of the controls and data sources.

Example:

   agDataMgr.evaluateAllExpressions();
 

propertyChange

public void propertyChange(PropertyChangeEvent evt)

Property change listener method.

Specified by:

propertyChange in interface PropertyChangeListener

vetoableChange

public void vetoableChange(PropertyChangeEvent evt)
                    throws PropertyVetoException

Vetoable property change listener method.

Specified by:

vetoableChange in interface VetoableChangeListener

validateAll

public boolean validateAll()
                    throws Exception

Triggers the global validation process for a page or form.

Returns:

true if all data passed validation successfully; false if the process ended with a validation failure

Usage:

The validation process does the following:

• Validates each control on the form or page. It checks validation rules and fires the validationTest event.
• Validates the controls on subforms or subpages.
• Fires the globalValidationTest event for the form or page.

Global validation can also be triggered by navigating to another row or updating data. A validation failure is handled in the same way regardless of how the process was triggered.

For more information about validation in forms, see Forms and data validation. For pages, see Validating user input.

Note, rather than returning false, in most cases validateAll() throws an exception. When you call validateAll(), you can catch the exception and handle it in any appropriate way.