1.1.1

• All AsyncEventListener implementations should check for the possibility that an existing database connection
may have been closed due to an earlier exception. For example, check for Connection.isClosed() in
a catch block and re-create the connection as needed before performing further operations. The DBSynchronizer
implementation in SQLFire automatically performs this type of check before reusing a connection.
• An AsyncEventListener implementation must be installed on one or more members of the SQLFire system.
You can install AsyncEventListeners only on data stores (peers configured with the property host-data set
to " true").
• You can install a listener on more than one member to provide high availability and guarantee delivery for
events, in the event that a SQLFire member with an active AsyncEventListener shuts down. At any given time
only one member has an active thread for dispatching events. The threads on other members remain on standby
for redundancy.
• Install no more than one standby listener (redundancy of at most one) for performance and memory reasons.
• To preserve pending events through member shutdowns, configure SQLFire to persist the internal queue of an
AsyncEventListener to an available Using Disk Stores to Persist Data. By default, any pending events that
reside in the internal queue of an AsyncEventListener are lost if the active listener's SQLFire member shuts
down.
• To ensure high availability and reliable delivery of events, configure the event queue to be both persistent and
redundant.
• If your listener implementation must deliver user credentials to an outside data source, consider encrypting the
credentials using sqlf encrypt-password with the external option. You can then supply the encrypted
password (rather than a clear-text password) to your listener via initialization parameters. The listener can then
use the AsyncEventHelper.decryptPassword method to decrypt the password before in order to
connect to the outside data source.
Implementing an AsyncEventListener
You implement an AsyncEventListener by defining a class that implements the AsynchEventListener interface,
installing the AsynchEventListener configuration, and associating a table with it.
Note: SQLFire also includes sample code for the built-in DBSynchronizer listener, which uses the latest
AsyncEventListener API. This sample listener is installed in the
examples/com/vmware/sqlfire/callbacks subdirectory of your SQLFire installation directory.
The main steps are detailed in the sections that follow. Before you begin, read Implementation Requirements
on page 197.
1. Implement the AsyncEventListener Interface on page 199.
2. Install the AsyncEventListener Configuration on page 200.
3. Start the AsyncEventListener Configuration on page 201.
4. Associate a Table with an AsyncEventListener Configuration on page 201.
5. Stop or Remove an AsyncEventListener Configuration on page 202
The example procedures show how to configure an AsyncEventListener with redundancy 1 in a SQLFire system
having one peer-client member and three data store members. Two data stores "DataStore1" and "DataStore2"
are available in server group "SG1." The AsyncEventListener will be installed on only those members that belong
to server group 'SG1'. A single table, "TESTTABLE" is associated with the AsyncEventListener.
When testing your own AsyncEventListener implementation you will also need to stop the listener configuration.
Stop or Remove an AsyncEventListener Configuration on page 202 describes this process.
vFabric SQLFire User's Guide198
Caching Data with vFabric SQLFire