10. Event Registration and Notification

Contents

10.1. Introduction

10.2. Database Events

10.3. Collection Events

10.4. Reference Events

10.5. Attribute Events

10.1. Introduction

VBSF supports the ability to register objects as listeners of certain supported types of events. VBSF can generate four types of events:

1. Database events that are triggered when an an object is about to, or has been, inserted, updated, or removed from the database.
2. Collection events that are triggered when the contents of a collection have changed in memory.
3. Reference events that are triggered when a reference is changed in memory.
4. Attribute events that are triggered when an attribute of a persistent object is changed in memory.

Each type of event is explained in more detail in each of the following sections.

10.2. Database Events

A Database event occurs when an object is updated in the database. There are three types of database operations for which VBSF generates a Database event:

1. Insertion of a row in the database.
2. Update of a row in the database.
3. Removal of a row in the database.

For each type of database operation above VBSF generates three different types of events:

1. A pre-operation event that is fired before the database operation is actually executed in the database.
2. A post-operation event that is fired right after the database operation, but before the next database operation in the same transaction.
3. A commit operation event that is fired after the transaction has been committed in the database.

When a Database event is fired, a DatabaseEvent object containing information about the event is passed to the listener. The following information can be obtained from a DatabaseEvent object:

1. The source, which is the Database object affected.
2. The target object, which is the actual object that was inserted, updated, or removed from the database.
3. The type of event that occurred. The event types listed below are defined as constants in the DatabaseEvent class:
   
   OBJECT_PRE_INSERT
   OBJECT_PRE_UPDATE
   OBJECT_PRE_REMOVE
   OBJECT_POST_INSERT
   OBJECT_POST_UPDATE
   OBJECT_POST_REMOVE
   OBJECT_COMMIT_INSERT
   OBJECT_COMMIT_UPDATE
   OBJECT_COMMIT_REMOVE

In order to be able to register an object as a DatabaseEvent listener, its class must implement the DatabaseListener interface. This interface only contains two methods whose signatures are shown below:

/**
* Called when an object is about to, or has just been, inserted, updated,
* or removed from the database, but while the transaction is still in
* progress (ie the transaction has not yet committed).
* Since this method is always called while the database is in the middle of
* a transaction, the implementation of this method can perform additional
* database operations while in the context of the current transaction, and
* can also terminate the current database operation by throwing a BODBException.
* A BODBException will terminate the transaction in progress, and propagate
* outwards to the client application. If implicit transactions are in effect,
* a rollback on the whole transaction is automatically performed.
* If transactions are controlled explicitly, then a rollback operation should
* be manually invoked when the exception is caught by the client program.
* The event type of the event argument can only be of one of
* the following types:
* <p>
* DatabaseEvent.OBJECT_PRE_INSERT, DatabaseEvent.OBJECT_PRE_UPDATE,
* DatabaseEvent.OBJECT_PRE_REMOVE, DatabaseEvent.OBJECT_POST_INSERT,
* DatabaseEvent.OBJECT_POST_UPDATE, DatabaseEvent.OBJECT_POST_REMOVE,
* </p>
* If the event is of any of the OBJECT_PRE_XXX types, then this method is called
* right before the object is updated in the database. This method should not
* make any changes to the object being updated, as any changes will be ignored.
* If the event is of any of the OBJECT_POST_XXX types, then this method is called
* right after the object has been updated in the database, and before performing any
* additional database operations that may be necessary in the current transaction.
* @param event event information.
*/
public void databaseUpdated( DatabaseEvent event ) throws BODBException;

/**
* Called when an object has been inserted, updated, or removed from the
* database after the transaction has committed.
* The event type of the event argument can only be of one of
* the following types:
* <p>
* DatabaseEvent.OBJECT_COMMIT_INSERT, DatabaseEvent.OBJECT_COMMIT_UPDATE,
* DatabaseEvent.OBJECT_COMMIT_REMOVE.
* </p>
* @param event event information.
*/
public void databaseCommitted( DatabaseEvent event );

A DatabaseListener object is registered by calling the addDatabaseListener method of the Database object. This method accepts as arguments the event listener object, the name of the persistent class the listener is interested in, and an array of event types of interest to the listener. The listener will only be notified of events of the specified types occurring on the specified persistent class. A DatabaseListener object can also be de-registered by calling the removeDatabaseListener method with the same arguments. See the company demo sample application for an example of defining and registering a DatabaseListener.

10.3. Collection Events

A Collection event occurs when when the contents of a collection are changed in memory. There are two main types of collection operations for which VBSF generates a collection event:

1. The addition to, removal from, or creation in the collection of a single object.
2. A collection wide operation that affects all objects in the collection, such as the collection being refreshed from the database.

When a Collection event is fired, a CollectionEvent object containing information about the event is passed to the listener. The following information can be obtained from a CollectionEvent object:

1. The source, which is the Database object in use by the client or thread that performed the collection operation.
2. The target object, which is the actual object that was added to, removed from, or created by the collection.
3. The OCollection object that the event actually occurred on.
4. The name of the persistent class affected.
5. The name of the collection affected.
6. The type of event that occurred. The event types listed below are defined as constants in the CollectionEvent class:
   
   OBJECT_CREATED
   OBJECT_ADDED
   OBJECT_REMOVED
   COLLECTION_LOADED
   COLLECTION_REFRESHED
   COLLECTION_MARKED_DELETED
   COLLECTION_UNDELETED
   COLLECTION_CHANGES_UNDONE

In order to be able to register an object as a CollectionEvent listener, its class must implement the CollectionListener interface. This interface only contains the method whose signature is shown below:

/**
* Called when an object is created by, added to, or removed from a
* collection, or when an operation is applied to the collection as
* a whole (e.g., it's refreshed).
* @param event collection event information.
*/
public void collectionUpdated( CollectionEvent event );

A CollectionListener object is registered by calling the addCollectionListener method of an OCollection object, or of a Database object. In the OCollection class this method accepts as arguments the CollectionListener object and an array of event types of interest to the listener. In the Database class, this method must also be provided with a reference to the object that holds the collection and the name of the collection. The listener will only be notified of events of the specified types occurring on the specified collection. A CollectionListener object can also be de-registered by calling the removeCollectionListener method of either class with the same arguments. See the company demo sample application for an example of defining and registering a CollectionListener.

10.4. Reference Events

A Reference event occurs when when a reference is changed in memory. This occurs when the set or setContained method of an OReference object is invoked, or when the setReference or setOwner method of a Database object is invoked.

When a reference event is fired, a ReferenceEvent object containing information about the event is passed to the listener. The following information can be obtained from a ReferenceEvent object:

1. The source, which is the Database object in use by the client or thread that performed the reference operation
2. The target object, which is the actual object that was the reference was set to.
3. The OReference object that the event actually occurred on.
4. The name of the persistent class affected.
5. The name of the reference attribute affected.
6. The type of event that occurred. The only event type supported is listed below and is defined as a constant in the ReferenceEvent class:
   
   OBJECT_CHANGED
   

In order to be able to register an object as a ReferenceEvent listener, its class must implement the ReferenceListener interface. This interface only contains the method whose signature is shown below:

/**
* Called when a reference to an object is changed.
* @param event reference event information.
*/
public void referenceUpdated( ReferenceEvent event );

A ReferenceListener object is registered by calling the addReferenceListener method of an OReference object, or of a Database object. In the OReference class this method accepts as arguments the ReferenceListener object and an array of event types of interest to the listener. In the Database class, this method must also be provided with a reference to the object that holds the reference and the name of the reference attribute. The listener will only be notified of events of the specified types occurring on the specified reference. A ReferenceListener object can also be de-registered by calling the removeReferenceListener method of either class with the same arguments. See the company demo sample application for an example of defining and registering a ReferenceListener.

10.5. Attribute Events

An Attribute event occurs when the value of an attribute in a persistent object has changed in memory. This event is generated when the attribute is changed in memory and VBSF becomes aware of it. The timing of the generation of this event is sometime in between the time the attribute value is directly changed in the object and the time the database is actually updated

When an attribute event is fired, an AttributeChangedEvent object containing information about the event is passed to the listener. The following information can be obtained from a AttributeChangedEvent object:

1. The source, which is the Database object in use by the client or thread that performed the attribute change operation
2. The target object, which is the persistent object whose attribute was changed.
3. The name of the attribute in target that was changed.
4. The previous value of the attribute before the change.
5. The current value of the attribute.
   

In order to be able to register an object as a AttributeChangedEvent listener, its class must implement the AttributeChangedListener interface. This interface only contains the method whose signature is shown below:

/**
* Called when an attribute of a persistent object is changed.
* @param event attribute changed event information.
*/
public void attributeChanged(AttributeChangedEvent e);

An AttributeChangedListener object is registered by calling the addAttributeChangedListener method of a Database object. An AttributeChangedListener object can also be de-registered by calling the removeAttributeChangedListener method of the Database object with the same argument.

Next Section

Return to Table of Contents