Event listeners

Available:

Crowd 2.1 and later

If you are familiar with writing a listener for Confluence, writing a listener plugin for Crowd should be almost identical.

In Crowd, events are thrown for almost all operations that occur to a user. (If you need more or find a spot we haven't thought of, please let us know!.)

The following example is contained in crowd-event-listener-example plugin project.

The Listener Plugin Module

Below is an example atlassian-plugin.xml that will configure your event listeners:

1
2
<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
    <plugin-info>
        <description>${project.description}</description>
        <version>${project.version}</version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
    </plugin-info>

    <listener name="User Created Listener" key="usercreatedlistener" class="com.atlassian.crowd.event.listener.example.UserCreatedListener">
        <description>Will listen for user creation events.</description>
    </listener>
</atlassian-plugin>

The Event Listener Class

Any Java class can be made an event listener by using the com.atlassian.event.api.EventListener annotation. This can be achieved by implementing a public method with one parameter, which is the event to be handled, and annotating the method with com.atlassian.event.api.EventListener annotation. A class can contain multiple event listener methods.

The following example event listener listens for user creation events and prints out the display name of each newly created user:

1
2
package com.atlassian.crowd.event.listener.example;

import com.atlassian.crowd.event.user.UserCreatedEvent;

public class UserCreatedListener
{
    @com.atlassian.event.api.EventListener
    public void printUserCreatedEvent(UserCreatedEvent event)
    {
        System.out.println("User " + event.getUser().getDisplayName() + " has been created.");
    }
}

Refactoring Old (Before Crowd 2.1) Event Listeners to Annotation-Based Event Listeners

Old event listeners can be refactored to use annotations by following these steps:

  1. Remove implements EventListener from the class signature.
  2. Remove getHandledEventClasses() method from the class.
  3. Change the type of event parameter in handleEvent method from com.atlassian.event.Event to com.atlassian.crowd.event.Event.
  4. In case the listener is interested in all events, annotate handleEvent method with com.atlassian.event.api.EventListener annotation.
  5. In other cases, create new public method for each of the handled events taking a parameter which has the same type as the handled event. Then add com.atlassian.event.api.EventListener annotation to each new method and make them delegate to handleEvent method.

Events and Event Types

Most event types in Crowd currently extend com.atlassian.crowd.event.DirectoryEvent. If you want to see the current list of available events, please take a look at Crowd's JavaDoc.

Generally Crowd uses the following naming scheme for events: <Object><Operation>Event

For example: UserUpdatedEvent This event would indicate that a User (<Object>) has been updated (<Operation>).

Limitations of Events

Please take note of the following limitations:

  • 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 GroupUpdatedEvent that itself causes a GroupUpdatedEvent to be generated, you are responsible for preventing the ensuing infinite loop.

Developing Plugins for Crowd

Rate this page: