Event Listener 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
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.
Adding a Listener Plugin
Listeners are a kind of Confluence plugin module.
- For more information about plugins in general, read Confluence Plugin Guide.
- To learn how to install and configure plugins (including macros), read Installing a Plugin.
- For an introduction to writing your own plugins, read Writing Confluence Plugins
Option 1. Annotation Based Event Listeners
Using annotation-based event listeners allows you to 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.
You must also register the class with the
EventPublisher, which can be injected to the listener.
As an annotation-based event listener is not required to implement the
com.atlassian.event.EventListener interface, you cannot use the
listener module descriptor.
In order to use the annotation-based event listeners you must register your listener as a component. For example:
See the example code for how to implement this listener: Annotation Based Event Listener Example
Option 2. The Listener Plugin Module
The Listener Plugin XML
Each listener is a plugin module of type 'listener', packaged with whatever Java classes and other resources the listener requires in order to run. Here is an example
atlassian-plugin.xml file containing a single listener:
The listener module definition has no configuration requirements beyond any other module: just give it a name, a key, and provide the name of the class that implements the listener.
The Listener Class
The class attribute of the listener module definition must refer to a Java class that implements the
com.atlassian.confluence.event.EventListener interface. This is the interface:
A more detailed example, with sample code, can be found in Writing an Event Listener Plugin Module.
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:
For example, we have the following event types relating to space events:
SpaceRemoveEvent. In the above 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.
Limitations of Events
- Events are a notification 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 ensuing infinite loop.