Writing an Event Listener plugin module

Overview

For an introduction to event listener plugin modules, read Event Listener module.

Step 1. Identify the events you wish to listen for

The easiest thing here is to consult the Javadoc, in the com.atlassian.confluence.event.events package. When you implement an EventListener you will provide an array of Class objects which represent the events you wish to handle.

The naming of most events are self explanatory (for example, GlobalSettingsChangedEvent or ReindexStartedEvent). However, there are some that need further clarification.

Step 2. Create the EventListener

The EventListener interface defines two methods that must be implemented: getHandledEventClasses() and handleEvent().

1. Implement getHandledEventClasses()

   The getHandledEventClasses() method holds an array of class objects representing the events you wish to listen for.

   • Your listener will only receive events of the types specified in getHandledEventClasses().
   • You must specify all the event types you need — specifying a superclass will not include its subclasses.
   • Returning an empty array will cause your listener to receive every event Confluence produces.

   So, if you want your listener to receive only SpaceCreatedEvent and SpaceRemovedEvent, do the following:

   1
   2
   private static final Class[] HANDLED_EVENTS = new Class[] {
       SpaceCreateEvent.class, SpaceRemovedEvent.class
   };
   
   public Class[] getHandledEventClasses()
   {
       return HANDLED_EVENTS;
   }
   

   Alternatively, to receive all possible events, use the following code:

   1
   2
   /**
    * Returns an empty array, thereby handling every ConfluenceEvent
    * @return
    */
   public Class[] getHandledEventClasses()
   {
       return new Class[0];
   }
   

2. Implement handleEvent()

   The following implementation simply relies upon the toString() implementation of the event and logs it to a log4j appender.

   1
   2
   public void handleEvent(Event event)
   {
       if (!initialized)
          initializeLogger();
   
       log.info(event);
   }
   

   Most often, a handleEvent(..) method will type check each event sent through it and execute some conditional logic.

   1
   2
   public void handleEvent(Event event)
   {
       if (event instanceof LoginEvent)
       {
           LoginEvent loginEvent = (LoginEvent) event;
           // ... logic associated with the LoginEvent
       }
       else if (event instanceof LogoutEvent)
       {
           LogoutEvent logoutEvent = (LogoutEvent) event;
           // ... logic associated with the LogoutEvent
       }
   }
   

You can find a full example of an EventListener class that listens for login and logout events in EventListener example.

Step 3. Add the EventListener as a module to your plugin

1. To add the EventListener as a module, create an atlassian-plugin.xml file.

The atlassian-plugin.xml file has been described here in detail. This is an example of a listener plugin module included in an atlassian-plugin.xml file.

1
2
<atlassian-plugin name='Optional Listeners' key='confluence.extra.auditor'>
    <plugin-info>
        <description>Audit Logging</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <version>1.0</version>
    </plugin-info>

    <listener name='Audit Log Listener' class='com.atlassian.confluence.extra.auditer.AuditListener' key='auditListener'>
        <description>Provides an audit log for each event within Confluence.</description>
    </listener>
</atlassian-plugin>