How does the Sakai event system work?

The following diagram illustrates Sakai event handling in general, and search-specific handling in particular. It is not an exhaustive representation of event handling in Sakai, but illustrates the high-level roles of the APIs involved.

Event handling is triggered when some Sakai object generates an event object and post()s that object to the EventTrackingService API. ClusterEventTracking is the default implementation of that API. The "Cluster" prefix refers to the fact that the implementation writes events to the database after local Observers have been notified. This allows for cluster-wide cache invalidation, for example.

Event dispatching logic is somewhat more fine-grained than is shown in this diagram. The point made here is simply that Sakai distinguishes between local event handlers, which ignore events received from other application server nodes, and clustered event handlers which process both local and external events. Both types of event handlers are implemented behind JDK-standard Observer and Observed APIs. Note that the object which generates the event does not fulfill the Observed role. The latter is used exclusively for its built-in dispatching logic.

All Sakai event handling within a JVM occurs synchronously unless an Observer chooses to spawn a thread for asynchronous Observer-specific behavior.

At startup the Sakai NotificationService registers itself with the EventTrackingService as a local Observer. The NotificationService is a factory for Notifications which encapsulate conditional event handling rules and processes. Upon receipt of an event, the NotificationService effectively offers the event to each Notification of which it is aware, which can include global, persistent Notifications or transient instances registered at runtime. When its conditions are satisifed, a Notification delegates event handling to the NotificationAction instance with which it has been configured.

Sakai's search module implements the NotificationAction API in the form of SearchNotficationAction. This object passes selected events through to SearchIndexBuilder.addResource(), which collaborates with the appropriate EntityContentProducer and a DAO object (not shown) to queue an event-specific SearchBuilderItem. Depending on configuration, the actual processing of the SearchBuilderItem might be handled by one of several index worker abstractions, and possibly on a different Sakai JVM.