 | Availability Listener plugins are available in Confluence 1.4 and later. |
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.
 | Plugin Events It is possible to listen for plugin install/uninstall/enable/disable events, however this will be unreliable when trying to listen for events about your own plugin. You will not receive a PluginDisableEvent or PluginUninstallEvent for the plugin itself. To trigger actions for these events, one (or more) of your modules (macro, event listener, etc.) should implement the StateAware interface instead. |
| Synchronous Events Confluence events are currently processed synchronously - that is, Confluence will wait for your event to finish processing before returning from the method that was the source of the event. This makes it very important that any event listener you write completes as quickly as possible. Asynchronous events will be forthcoming in a future Developer Release. |
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 and Configuring Plugins manually.
- For an introduction to writing your own plugins, read Writing Confluence Plugins
The Listener Plugin Module
Each listener is a plugin module of type "listener", packaged with whatever Java classes and other resources that 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:
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, 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.
A full catalogue of the events available within Confluence will be forthcoming before the 1.4 final release.
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.
Example Code
A more detailed example, with sample code, can be found in Writing an Event Listener Plugin Module.
