Event Notification and Listeners - blojsom - Confluence

API Availability

This API is available as of blojsom 2.18.

Event Notification and Listener API

The blojsom event notification and listener API allows developers to write blojsom components (dispatchers, fetchers, listeners, and plugins) that respond to events from other blojsom components in a well-defined way. For example, based on an event indicating that a blog entry was added or updated, a listener or plugin could be written to respond to that event and "ping" a weblog update notification service like weblogs.com or blo.gs. Another example might be a listener or plugin which e-mails a list of individuals when a blog entry has been added to a blog.

The blojsom event notification and listener API was designed to be very straightforward.

Event Notification API

The event notification API consists of the BlojsomEvent class and the BlojsomEventBroadcaster and BlojsomFilter interfaces. The BlojsomEventBroadcaster interface defines the following 4 methods:

public void addListener(BlojsomListener listener);
public void addListener(BlojsomListener listener, BlojsomFilter filter);
public void removeListener(BlojsomListener listener);
public void broadcastEvent(BlojsomEvent event);

The implementation of this interface that ships with blojsom is the SimpleBlojsomEventBroadcaster. Events are broadcast to each event in a separate thread so that the broadcaster is not a bottleneck. No defined order is set for how each event will receive an event, so you should not assume any order in listeners being called. No steps are taken to ensure an event does not receive an event if it is removed at the same time an event is being broadcast. Also, listeners registered using the addListener(BlojsomListener listener) method in this implementation use a BlojsomFilter that returns true for all events for its processEvent(BlojsomEvent event) method.

The BlojsomFilter interface defines 1 method that must be implemented:

public boolean processEvent(BlojsomEvent event);

Configuring the registered event broadcaster

In your /WEB-INF/blojsom.properties file, the blojsom-broadcaster property is used to set the class implementing the BlojsomEventBroadcaster interface that will be used to register listeners and dispatch events.

blojsom-broadcaster=org.blojsom.event.SimpleBlojsomEventBroadcaster

If this property is not present, blojsom will default to using the org.blojsom.event.SimpleEventBroadcaster class.

Broadcasting events to other components

Retrieve the BlojsomEventBroadcaster instance from the BlojsomConfiguration object. Use the broadcastEvent(BlojsomEvent event) method to dispatch events to the registered listeners.

For example:

public BlogEntry[] process(HttpServletRequest httpServletRequest, 
        HttpServletResponse httpServletResponse, 
        BlogUser user, Map context, 
        BlogEntry[] entries) throws BlojsomPluginException {
        
        // Something is being done in a plugin
     
        UpdatedStateEvent updateEvent =
            new UpdatedStateEvent(this, new Date(), State.PENDING);
        eventBroadcaster.broadcastEvent(updateEvent);
    }

Listener API

A developer that wants to write an event listener will implement the BlojsomListener interface. This interface defines 2 methods that must be implemented:

public void handleEvent(BlojsomEvent event);
public void processEvent(BlojsomEvent event);

The handleEvent method is to be used for asynchronous events while the processEvent method is to be used for synchronous events.

A component that registers itself as an event listener can implement a specific filter to only receive events of interest based on event type, time, or any other criteria.

Registering as a listener

If you are writing a BlojsomDispatcher, BlojsomFetcher, or BlojsomPlugin that wishes to register as an event listener, you may use the getEventBroadcaster() method to retrieve the configured event registrar and broadcaster from the BlojsomConfiguration object passed to you in your init(...) method. You will then use either the addListener(BlojsomListener listener) or addListener(BlojsomListener listener, BlojsomFilter filter) to register as an event listener.

For example:

public class EventBroadcastingPlugin implements BlojsomListener, BlojsomPlugin {

    // Some private variables

    public void init(ServletConfig servletConfig, 
        BlojsomConfiguration blojsomConfiguration) 
             throws BlojsomPluginException {
        blojsomConfiguration.getEventBroadcaster().addListener(this);
    }

    // Other plugin methods
}

You may also register listeners with the configured event registrar and broadcaster using a listeners configuration file. The use of the configuration file is optional. The configuration file is specified using the listener-configuration servlet initialization parameter in your /WEB-INF/web.xml file.

<init-param>
    <param-name>listener-configuration</param-name>
    <param-value>/WEB-INF/listener.properties</param-value>
</init-param>

The format of this file is as follows:

name=fully-qualified name of class implementing the BlojsomListener interface

name can be anything as long as it is unique within the file.

This way of registering listeners is useful for standalone components that do not need any blojsom configuration information. If you do need blojsom configuration information, you probably want to write a blojsom plugin that implements the BlojsomListener interface.