Customizing Session Events

Sessions, such as database sessions, Units of Work, client sessions, server sessions, and remote sessions raise session events for most session operations. Session events help you debug or coordinate the actions of multiple sessions.

This section illustrates how you customize session events, and discusses:

Session Event Listeners
Session Event Manager
Implementing Events Using Java

Session Event Listeners

One approach to customizing session events is to create session event listeners that detect and respond to session events. To register objects as listeners for session events, implement the SessionEventListener interface, and register it with the SessionEventManager using addListener().

Table 4-14 Session Event Manager Events

Event	Description
PreExecuteQuery	Raised before the execution of every query on the session
PostExecuteQuery	Raised after the execution of every query on the session
PreBeginTransaction	Raised before a database transaction starts
PostBeginTransaction	Raised after a database transaction starts
PreCommitTransaction	Raised before a database transaction commits
PostCommitTransaction	Raised after a database transaction commits
PreRollbackTransaction	Raised before a database transaction rolls back
PostRollbackTransaction	Raised after a database transaction rolls back
PreLogin	Raised before the Session initializes and acquires connections
PostLogin	Raised after the Session initializes and acquires connections

Table 4-15 Unit of Work Events

Event	Description
PostAcquireUnitOfWork	Raised after a `UnitOfWork` is acquired
PreCommitUnitOfWork	Raised before a `UnitOfWork` commits
PrepareUnitOfWork	Raised after the a `UnitOfWork` flushes its SQL, but before it commits its transaction
PostCommitUnitOfWork	Raised after a `UnitOfWork` commits
PreReleaseUnitOfWork	Raised on a `UnitOfWork` before it releases
PostReleaseUnitOfWork	Raised on a `UnitOfWork` after it releases
PostResumeUnitOfWork	Raised on a `UnitOfWork` after it resumes

Table 4-16 Server Session and Client Session Events (Three-Tier Applications)

Event	Description
PostAcquireClientSession	Raised after a `ClientSession` is acquired
PreReleaseClientSession	Raised before releasing a `ClientSession`
PostReleaseClientSession	Raised after releasing a `ClientSession`
PostConnect	Raised after connecting to the database
PostAcquireConnection	Raised after acquiring a connection
PreReleaseConnection	Raised before releasing a connection

Table 4-17 Database Access Events

Event	Description
OutputParametersDetected	Raised after a stored procedure call with output parameters executes. This event enables you to retrieve a result set and output parameters from a single stored procedure.
MoreRowsDetected	Raised when a ReadObjectQuery detects more than one row returned from the database. This event can indicate a possible error condition in your application.

Session Event Manager

The session event manager handles information about session events. Applications register listeners with the session event manager to receive session event data.

Example 4-47 Registering a Listener

public void addSessionEventListener(SessionEventListener listener)
{
    // Register specified listener to receive events from mySession
    mySession.getEventManager().addListener(listener);
}

Example 4-48 Using the Session Event Adapter to Listen for Specific Session Events

...
    SessionEventAdapter myAdapter = new SessionEventAdapter() {
        // Listen for PostCommitUnitOfWork events
        public void postCommitUnitOfWork(SessionEvent event) {
        // Call my handler routine
    unitOfWorkCommitted();     }
};
mySession.getEventManager().addListener(myAdapter);
...

Implementing Events Using Java

You can implement custom events and event handlers in Java code. The code in Example 4-49 checks for lock conflicts when the application builds an instance of Employee from information in the database.

Example 4-49 Implementing an Event in Code

/*In the employee class, declare the event method which will be invoked when the event occurs */
public void postBuild(DescriptorEvent event) {
    // Uses object row to integrate with some application level locking service.
    if ((event.getRow().get("LOCKED")).equals("T")) {
        LockManager.checkLockConflict(this);
   }
}