Programming an event handlerAdded by IBM on February 2, 2011 | Version 1 (Original)
|Event handlers are Java™ code that executes within the context of the Lotus® Connections server. To write an event handler, you must implement the Event handler SPI interfaces. The Event handler SPI interfaces are contained in the lc.events.spi.jar file. More detailed information about the specific Event SPI interfaces referenced in this topic are contained in the Event SPI Javadoc.
Event handlers are Java™ code that executes within the context of the Lotus® Connections server. To write an event handler, you must implement the Event handler SPI interfaces. The Event handler SPI interfaces are contained in the lc.events.spi.jar file. More detailed information about the specific Event SPI interfaces referenced in this topic are contained in the Event SPI Javadoc.
- Locate a copy of the lc.events.spi.jar file from within the root installation directory of any of the Lotus Connections applications: Activities, Blogs, Communities, Bookmarks, Files, Forums, Home Page, News, Profiles or Wikis.
- Import the JAR file into your Java development environment.
- Create a new Java class that implements the correct interface for the type of event handler you are creating. The supported types are as follows:
|Type of event handler||Interface to implement||Abstract implementation to extend (optional)|
The abstract implementations provide default implementations of the init() and destroy() methods. Your implementation class must provide a default constructor.
- Implement event handler logic.
Things to consider when programming an event handler:
- Handlers must be thread-safe objects. Do not store state in your handlers.
- There is no guarantee that only one instance of your handler will be created, or that the same instance will always be called. The system may create multiple instances of the same handler class.
- Handlers must be valid JavaBeans™.
- If implementing a pre-event handler or an event handler which will be configured to be invoked synchronously, ensure that your handler logic does not perform expensive operations, nor is reliant on external resources which may incur wait time or slow execution. If this is the case, look to register the handler asynchronously instead.
- Pre-event handlers and post-event handlers deployed synchronously will only be used for specific functions in Lotus Connections. Only asynchronously-registered post-event handlers will be able to subscribe to any generated event from the system.
Your handler can define properties it relies on, the values of which are injected at runtime from the configuration you specify when deploying the handler. Properties can be simple JavaBean properties for primitive types or String only. Complex object and indexed properties are not supported. To implement a property, you must provide public getXXX and setXXX methods (or isXXX and setXXX for Boolean properties) . In order to validate that the injected properties are correctly specified at runtime, you can provide an implementation of the init() method which checks property values.
- Export your event handler as a JAR file from your development environment.
The handleEvent method will be called each time an event for which your handler is subscribed gets generated by the system. The parameter passed to the handleEvent method will be one of the following:
|Handler type||Event interface consumed||Description|
|Pre-event handler||com.ibm.connections.spi.events.object.mutable.MutableEvent||Provides read only access to all event data and the ability to update a limited set of event data.|
|Post-event handler||com.ibm.connections.spi.events.object.Event||Provides read-only access to all event data.|
Both handlers provide access to the same event data. Event data is broken down into discrete sets of data such as the details of the user who instigated the event action, and the details of the object the action was taken against. Full documentation of what data is exposed is detailed in the Event SPI Javadoc. Note that not all event data is present for all events in the system.
Parent topic: Event SPI