Jaybird Events API

Events Introduction

Events are a little-known but very powerful feature of the Firebird database system. The Events API allows for events to be posted from within database triggers and stored procedures, with external applications registering for delivery of these notifications.

Although the Events API can be (clumsily) replicated with polling in the database, the Firebird implementation allows for a much more resource-efficient alerting system.

Events are posted with the POST_EVENT, as follows:

POST_EVENT 'EVENT_NAME';

The name of an event can also be supplied by a value fetched from the database.

A much more thorough explanation of the events mechanism can be found in The Power of Firebird Events and Borland InterBase Events whitepaper (internet archive).

Events in Jaybird

Starting from Jaybird 2.1, there is a java implementation for event notification. The org.firebirdsql.event.FBEventManager allows for both synchronous and asynchronous consumption of events. The basic setup of a FBEventManager is very similar to that of Jaybird's Services API Manager implementation, with getters and setters for the basic connection information to the target database.

Synchronous Event Handling

The synchronous event handling is done with the waitForEvent method. This method is overloaded, with both variations taking the event name that should be waited on, and the second variation taking a timeout value. The waitForEvent method works in a very similar manner to the java.lang.Object.wait() method; it simply blocks until event notification is received from the database, or the timeout is reached. The number of events that were received is returned by this method; -1 is returned if the timeout was reached.

Asynchronous Event Handling

Asynchronous event handling is performed with event listeners, in a manner similar to AWT and Swing event listeners. An object that is to be registered to handle database events must implement the org.firebirdsql.event.EventListener interface. This interface contains a single method: eventOccurred(org.firebirdsql.event.DatabaseEvent event). The DatabaseEvent object contains information about the name of the event and the number of times it occurred.

Base Implementation

All event mechanisms in Jaybird make use of the base event methods in the org.firebirdsql.gds.GDS interface; the isc_event_xxx methods of the core Firebird API are replicated in the GDS interface.

Examples

The two example applications below rely on a database that has triggers for posting events. A simple example of such a setup can be produced with create_event_db.sql. Once the table and triggers have been created with the SQL script, events can be generated by inserting, updating, or deleting rows in the CUSTOMER table. To perform the operations that will generate events in the database, you must be connected to the database through a TCP/IP connection (and not an embedded/IPC connection). For example, if you are using isql, make sure to include localhost: at the start of your connection string. Another important point is that events are only generated once the database operation has been committed.

Synchronous Event Handling

SynchronousEventNotifier.java is a simple program that illustrates the use of synchronous event handling with the org.firebirdsql.event.FBEventManager. It is invoked with the database path, username and password as commandline parameters, as well as the name of the event that should be waited for. For example, if the schema from create_event_db.sql is used, the program could be started as follows:

java SynchronousEventNotifier /tmp/test.gdb sysdba masterkey CUSTOMER_INSERT

The program could then be tested by running the following commands in another window:

$ isql -user sysdba -password masterkey localhost:/tmp/test.gdb
Database:  localhost:/tmp/test.gdb, User: sysdba
SQL> INSERT INTO CUSTOMER VALUES (1, 'Gabriel Reid');
SQL> COMMIT;

This should result in the following output in the window running SynchronousEventNotifier:

Received 1 instance(s) of event 'CUSTOMER_INSERT', total is 1

Note the the program will time out after 10 seconds of waiting for an event.

Asychronous Event Handling

AsynchronousEventNotifier.java demonstrates asynchronous event handling with Jaybird, in the form of a GUI application. It is invoked in the same manner as SynchronousEventNotifier, but multiple event names can be supplied. To try it out, just start the application with several event names as follows:

java AsynchronousEventNotifier /tmp/test.gdb sysdba masterkey 
  CUSTOMER_INSERT CUSTOMER_DELETE CUSTOMER_UPDATE

and then login to the database and start making changes. After each commit, the notifications of the changes will be displayed in the application's window.