Confluence 2.8 : Event Listener Plugins
This page last changed on Apr 24, 2007 by david@randombits.org.
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 pluginListeners are a kind of Confluence plugin module.
The Listener Plugin ModuleEach 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: <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.example.listener.AuditListener' key='auditListener'> <description>Provides an audit log for each event within Confluence.</description> </listener> </atlassian-plugin> 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 ClassThe 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: package com.atlassian.confluence.event; import com.atlassian.confluence.event.events.ConfluenceEvent; /** * Defines a listener for Confluence events. */ public interface EventListener { /** * Perform some action as a response to a Confluence event. The EventManager will * ensure that this is only called if the class of the event matches one of the * classes returned by getHandledEventClasses * * @param event some event triggered within Confluence */ void handleEvent(ConfluenceEvent event); /** * Determine which event classes this listener is interested in. * * The EventManager performs rudimentary filtering of events by their class. If * you want to receive only a subset of events passing through the system, return * an array of the Classes you wish to listen for from this method. * * For the sake of efficiency, only exact class matches are performed. Sub/superclassing * is not taken into account. * * Returning an empty array will allow you to receive every event. * * @return An array of the event classes that this event listener is interested in, * or an empty array if the listener should receive all events. <b>Must not</b> * return null. */ Class[] getHandledEventClasses(); } Events and Event TypesAll 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: 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
Example CodeA more detailed example, with sample code, can be found in Writing an Event Listener Plugin Module. |
![]() |
Document generated by Confluence on Jun 24, 2008 18:04 |