Writing an Event Listener Plugin Module


Confluence 1.4 and later


In Confluence 3.3 and later, Confluence events are annotation-based. This means that you have two options when writing event listeners. Option 1 is the Event Listener plugin module, using the com.atlassian.event.EventListener class. Option 2 is to declare your listener as a component and use annotation-based event listeners, annotating your methods to be called for specific event types. The component will need to register itself at the time it gets access to the EventPublisher, typically in the constructor. More information and examples are in Event Listener Module.


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

Writing an Event Listener as a plugin module within Confluence

Writing an event listener is a four-step process:

  1. Identify the events you wish to listen for
  2. Create the EventListener Java class
    1. Implement getHandledEventClasses()
    2. Implement handleEvent()
  3. Add the listener module to your atlassian-plugin.xml file

Identify the events you wish to listen for

The easiest thing here is to consult the Javadoc, in the package com.atlassian.confluence.event.events . 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 explanitory (GlobalSettingsChangedEvent or ReindexStartedEvent for example), however there are some which need further clarification:

Event Class



On the creation of the first label to the target Content Entity Object.


On the removal of the last label from the target Content Entity Object.


On the addition of any label to the target Content Entity Object.


On the deletion of any label from the target Content Entity Object.

Create the EventListener

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

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

    private static final Class[] HANDLED_EVENTS = new Class[] { 
        SpaceCreateEvent.class, SpaceRemovedEvent.class 

    public Class[] getHandledEventClasses()
        return HANDLED_EVENTS;

Alternatively, to receive all possible events:

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

Implement handleEvent()

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

    public void handleEvent(Event event)
        if (!initialized)


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

    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

A full example of an EventListener class that listens for login and logout events can be found in EventListener Example.

Add the EventListener as a module to your plugin by creating an atlassian-plugin.xml

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

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

    <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>
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport