1.1.1

Chapter 33
Handling DML Events Synchronously
SQLFire provides synchronous cache plug-in mechanisms to handle cache events.
Writer and Listener Cache Plug-ins
You can implement two types of synchronous cache plug-ins: writers and listeners.
Writer and listener cache plug-ins operate in the following ways:
• Listener—A listener enables you to receive after-event notifications of changes to a table (insert, update and
delete). Any number of listeners can be defined for the same table. Listener callbacks are called synchronously,
so they will cause the DML operation to block if the callback blocks.
• Writer—A cache writer is an event handler that synchronously handles changes to a table before those changes
take place. The main use of a cache writer is to keep external data sources synchronized with a table in SQLFire,
or to perform other checking or work before a DML operation takes place in SQLFire.
A cache writer provides write-through caching with your external data source. Unlike listeners, only one writer
can be attached to a table. When the table is about to to be modified because of an insert, update, or a delete,
SQLFire informs the writer of the pending operation using the callback. The writer can choose to disallow the
operation by throwing a SQLException. The writer callback is called synchronously and will block the operation
if the callback blocks.
Note: SQLFire does not check primary or unique key constraints before invoking a writer callback.
You attach writers and listeners to tables by using the SYS.ATTACH_WRITER and SYS.ADD_LISTENER
built-in system procedures.
Both listeners and writers must be implementations of the EventCallback interface. The main method of the
interface is the onEvent method, which is invoked in both writer and listener implementations.
The Event object which is passed with the callback gives the following information:
• The type of the event. TYPE.BEFORE_INSERT, TYPE.BEFORE_UPDATE and TYPE.BEFORE_DELETE
are provided to writers to indicate whether an insert, update, or delete is about to take place. Similarly listeners
receive TYPE.AFTER_INSERT, TYPE.AFTER_UPDATE and TYPE.AFTER_DELETE.
• The old row as a List<Object> (for an update or delete operation).
• The new row as a List<Object> (for an insert or update operation).
• The ResultSetMetaData (metadata of the table).
• Information about whether the event's source was local.
• GetModifiedColumns() - the int[] of 1-based column positions for the columns that were updated.
• The primary key of the row being modified as an object[] .
195