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 GemFire XD, or to perform other checking or work before a DML operation takes place in GemFire XD.

    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, GemFire XD 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: GemFire XD does not check primary or unique key constraints before invoking a writer callback.
    Note: GemFire XD invokes a listener only for single DML events; bulk DML or batch SQL statements do not invoke listeners.

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[] .

GemFire XD API provides additional information and examples for using callbacks.