Community articleProgramming an event handler
Added by IBM contributorIBM on March 25, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Event handlers are Java™ code that executes within the context of the IBM® 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 IBM® 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.

Procedure

  1. Locate a copy of the lc.events.spi.jar file from within the root installation directory of any of the IBM Connections applications: Activities, Blogs, Communities, Bookmarks, Files, Forums, Home Page, News, Profiles or Wikis.
  2. Import the JAR file into your Java development environment.
  3. 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:
  4. Table 1.
    Type of event handler
    Interface to implement
    Abstract implementation to extend (optional)
    Pre-event handler
    com.ibm.connections.spi.events.PreEventHandler
    com.ibm.connections.spi.events.AbstractPreEventHandler
    Post-event handler
    com.ibm.connections.spi.events.EventHandler
    com.ibm.connections.spi.events.AbstractEventHandler


    The abstract implementations provide default implementations of the init() and destroy() methods. Your implementation class must provide a default constructor.
  5. Implement event handler logic.
  6. 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 IBM 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.
  7. Export your event handler as a JAR file from your development environment.

Results

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:

Table 2.
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