Set up event-driven messaging with Atlassian Event

Introduction

Atlassian Events is a library that allows other plugins to send and consume internal messages within Atlassian applications. It provides a framework for creating, publishing, and listening to custom events. This is useful for developers who want to extend the functionality of Atlassian products by reacting to specific events or changes within the system. This page helps developers setup the Event Listener and Event Publisher.
Event Listener is a component that listens for specific events occurring within Atlassian applications and performs actions in response to those events.
Event Publisher is a component responsible for publishing events within the Atlassian ecosystem. It acts as a central mechanism to broadcast events to any registered listeners that are interested in those events.

1. Add Atlassian Event library to your pom.xml

1
2
<dependency>
    <groupId>com.atlassian.event</groupId>
    <artifactId>atlassian-event</artifactId>
    <scope>provided</scope>
</dependency>

2. Create a Custom Event Object

An event can be a simple POJO with fields that must define their access methods, for example:

1
2
public class UsernameChangedEvent {
    private final String oldUsername;
    private User newUser;
    
    public UsernameChangedEvent(String oldUsername, User newUser) {
        this.oldUserName = oldUsername;
        this.newUser = newUser;
    }
    
    public String getOldUsername() {
        return oldUsername;
    }
    
    public User getNewUser() {
        return newUser;
    }
}

This class should be public API. Plugins that listen to this event will have to import the event's java class.

3. Write an Event Publisher

To publish an event, you need to inject the EventPublisher into your class and use it to publish your custom event. It can be an already existing class or you can create a custom class dedicated to publishing events:

1
2
public class UsernameChangedEventPublisher {
    private final EventPublisher eventPublisher;

    public UserManager(EventPublisher eventPublisher) {
        this.eventPublisher = eventPublisher;
    }
    
    public void publishUsernameChangedEvent(User newUser, String oldUsername) {
        // Publish the event
        eventPublisher.publish(new UsernameChangedEvent(oldUsername, newUser));
    }
}

4. Write an Event Listener

To create an event listener, follow these steps:

• Inject the EventPublisher into your listener class.
• Register the listener to receive events.
• Use the @EventListener annotation on methods that should handle events.

  1
  2
  public class UsernameChangedEventListener implements InitializingBean, DisposableBean {
      private final EventPublisher eventPublisher;
      
      public DefaultCalendarNotificationManager(EventPublisher eventPublisher) {
          this.eventPublisher = eventPublisher;
      }
      
      @Override
      public void afterPropertiesSet() throws Exception {
          // Register with the EventPublisher
          eventPublisher.register(this);
      }
      
      @Override
      public void destroy() throws Exception {
          // Unregister from the EventPublisher
          eventPublisher.unregister(this);
      }
      
      @EventListener
      public void onUsernameChanged(UsernameChangedEvent event) {
          // Handle the event
      }
  }
  

5. Plugin Configuration

For the configuration you have to do 3 things:

• Define your listener in atlassian-plugin.xml
  • <listener key="eventListener" class="com.example.tutorial.plugins.IssueCreatedResolvedListener"/>
• Import the EventPublisher bean, read spring Java Config page to learn how to import beans using spring-java-config.

6. Additional notes

• f you're publishing multiple events and want to execute them asynchronously, you can use @AsynchronousPreferred. This annotation leverages java.util.concurrent.Executor to run each event in its own thread, handling them through thread queues for efficient management. You can add this annotation to your event POJO like so:

  1
  2
    @AsynchronousPreferred
    public class UsernameChangedEvent {
    ...
  }