Event Listener module

Every time something important happens within Confluence (a page is added or modified, the configuration is changed, etc.), an 'event' is triggered. Listeners allow you to extend Confluence by installing code that responds to those events.

Limitations of events

• Events are notifications that something has occurred. The event system is not designed to allow a listener to veto the action that caused the event.
• There is no loop detection. If you write a listener for the SpaceModifiedEvent that itself causes a SpaceModifiedEvent to be generated, you are responsible for preventing the start of an infinite loop.
• You can listen for plugin install/uninstall/enable/disable events. However, this will be unreliable when trying to listen for events about your own plugin. To trigger actions for these events, your modules should implement Spring lifecycle interfaces: InitializingBean and DisposableBean. The afterPropertiesSet() and destroy() methods on these interfaces will be called when the module is enabled or disabled,
• Confluence events are currently processed synchronously. That is, Confluence waits for your event to finish processing before returning from the method that is the source of the event. This makes it very important that any event listener you write completes as quickly as possible.

Adding a Listener plugin

Listeners are a kind of Confluence plugin modules.

• For more information about plugins in general, read Confluence plugin guide.
• For an introduction to writing your own plugins, read Writing Confluence plugins

Annotation-Based Event Listeners with Atlassian Spring Scanner

Annotation-based event listeners let you annotate methods to be called for specific event types. The annotated methods must take a single parameter specifying the type of event that should trigger the method.

To use the annotation-based event listeners, you must register your listener as a component and start listening to EventPublisher.

1
2
@Named
public class EventListener implements DisposableBean {

    @ConfluenceImport
    private EventPublisher eventPublisher;

    @Inject
    public EventListener(EventPublisher eventPublisher) {
        eventPublisher.register(this);  //just for example
    }

    // Unregister the listener if the plugin is uninstalled or disabled.
    public void destroy() throws Exception {
        eventPublisher.unregister(this);
    }
}

You can check Writing advanced Confluence blueprint for an example of a simple listener.

Events and Event types

All events within Confluence extend from com.atlassian.com.event.events.ConfluenceEvent. In general, we use the following convention for naming each type of ConfluenceEvent:

<Object><Operation>Event

For example, we have the following event types relating to space events: SpaceCreateEvent, SpaceUpdateEvent, and SpaceRemoveEvent. In the previous description, space would correspond to <Object> and create, update, or remove would correspond to <Operation>.

Occasionally, an operation is so singular that its meaning will be obvious without use of this naming convention; for example, a LoginEvent or ConfigurationEvent.

Legacy

There are a few legacy ways to register event listener:

• Descriptor based Event Listener
• Annotation based Event Listener - legacy