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.
The event and listener API can be found in the org.blojsom.event package.
You may also be interested in the event and listener API examples.
Event Notification API
The event notification API consists of the Event class and the EventBroadcaster and Filter interfaces.
Event Broadcaster Interface
The EventBroadcaster interface defines the following 5 methods:
- public void addListener(Listener listener);
- public void addListener(Listener listener, Filter filter);
- public void removeListener(Listener listener);
- public void broadcastEvent(Event event);
- public void processEvent(Event event);
The implementation of this interface that ships with blojsom is the SimpleEventBroadcaster. 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(Listener listener) method in this implementation use a Filter that returns true for all events for its processEvent(Event event) method.
Filter Interface
The Filter interface defines 1 method that must be implemented:
- public boolean processEvent(Event event);
This method returns true or false depending on whether the event should be processed based on the criteria defined by the component.
Configuring an Event Broadcaster
The event broadcaster bean is configured in /WEB-INF/classes/blojsom.xml.
<bean id="eventBroadcaster" class="org.blojsom.event.SimpleEventBroadcaster"/>
If you write a new implementation of the EventBroadcaster interface, you would need to make the class available to the blojsom web application and change the class attribute here for the eventBroadcaster bean.
Publishing Events to Other Components
A component wishing to publish events to other components should do the following.
- Declare an instance of the event broadcaster
private EventBroadcaster _eventBroadcaster;
- Declare a set method to set the instance of the event broadcaster for that component.
public void setEventBroadcaster(EventBroadcaster eventBroadcaster) {
_eventBroadcaster = eventBroadcaster;
}
- Make sure that the event broadcaster is passed to the component in the appropriate configuration file.
<bean id="hello-world" class="org.blojsom.plugin.example.HelloWorldPlugin" init-method="init" destroy-method="destroy">
<property name="eventBroadcaster">
<ref bean="eventBroadcaster"/>
</property>
</bean>
At this point, you're ready to publish events in either broadcast or process mode.
Publishing an Event in Broadcast Mode
If you publish an event in broadcast mode, you're telling other components registered for that event, "Here is an event. Handle it as appropriate."
EntryUpdatedEvent entryUpdatedEvent = new EntryUpdatedEvent(this, new Date(), entry, blog);
_eventBroadcaster.broadcastEvent(entryUpdatedEvent);
The simple event broadcaster is written so that after the broadcastEvent method is called, it should return almost instantly and allow the other code after the call to execute.
Publishing an Event in Process Mode
If you publish an event in process mode, you're telling other components registered for that event, "Here is an event. Handle it as appropriate, but I'll be waiting for you to finish processing the event."
EntryUpdatedEvent entryUpdatedEvent = new EntryUpdatedEvent(this, new Date(), entry, blog);
_eventBroadcaster.processEvent(entryUpdatedEvent);
The simple event broadcaster is written so that after the processEvent method is called, it executes the appropriate components registered for that event and then returns control back to the component that initiated the processEvent call.
When Do I Use Broadcast and When Do I Use Process?
If you simply need to notify other components an event has occurred, use broadcastEvent.
If your components needs other components to process content or items contained in the event and you need to handle the processed content or items in the event, use processEvent.
Listener API
A developer that wants to write an event listener will implement the Listener interface. This interface defines 2 methods that must be implemented:
- public void handleEvent(Event event);
- public void processEvent(Event 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.
Listening for Events from Other Components
A component wishing to listen for events from other components should do the following.
- Implement the Listener interface
public class HelloWorldListenerPlugin implements Plugin, Listener {
- Declare an instance of the event broadcaster
private EventBroadcaster _eventBroadcaster;
- Declare a set method to set the instance of the event broadcaster for that component.
public void setEventBroadcaster(EventBroadcaster eventBroadcaster) {
_eventBroadcaster = eventBroadcaster;
}
- Make sure that the event broadcaster is passed to the component in the appropriate configuration file.
<bean id="hello-world" class="org.blojsom.plugin.example.HelloWorldPlugin" init-method="init" destroy-method="destroy">
<property name="eventBroadcaster">
<ref bean="eventBroadcaster"/>
</property>
</bean>
- Register as an event listener in the appropriate initialization method.
_eventBroadcaster.addListener(this);
At this point, you're ready to listen for events that are published in either broadcast or process mode.
Listening for Specific Events
Listeners may also register with a filter for events being published from other components. You can add a filter when a component registers as a listener.
public void init() throws PluginException {
_eventBroadcaster.addListener(this, new Filter() {
/**
* Determines whether or not a particular event should be processed
*
* @param event {@link Event} to be processed
* @return <code>true</code> if the event should be processed, <code>false</code> otherwise
*/
public boolean processEvent(Event event) {
if (event instanceof EntryEvent) {
return false;
}
return true;
}
});
}
In the above example, the component will only be listening for events not related to entries.
Listening for a Broadcast Event
Implement your code in the handleEvent method.
/**
* Handle an event broadcast from another component
*
* @param event {@link Event} to be handled
*/
public void handleEvent(Event event) {
if (event instanceof EntryDeletedEvent) {
_deletedEntries += 1;
EntryDeletedEvent entryDeletedEvent = (EntryDeletedEvent) event;
if (_logger.isDebugEnabled()) {
_logger.debug("It's such a shame that an entry, " + entryDeletedEvent.getEntry().getTitle() + " was deleted for " +
"its time was too short on this blog, " + entryDeletedEvent.getBlog().getBlogName());
}
}
}
Listening for a Process Event
Implement your code in the processEvent method.
/**
* Process an event from another component
*
* @param event {@link Event} to be handled
*/
public void processEvent(Event event) {
}
