Spring Events – Spring活动

最后修改: 2014年 11月 10日


1. Overview


In this tutorial, we’ll be discussing how to use events in Spring.


Events are one of the more overlooked functionalities in the framework but also one of the more useful. And like many other things in Spring, event publishing is one of the capabilities provided by ApplicationContext.


There are a few simple guidelines to follow:


  • The event class should extend ApplicationEvent if we’re using versions before Spring Framework 4.2. As of the 4.2 version, the event classes no longer need to extend the ApplicationEvent class.
  • The publisher should inject an ApplicationEventPublisher object.
  • The listener should implement the ApplicationListener interface.

2. A Custom Event


Spring allows us to create and publish custom events that by default are synchronous. This has a few advantages, such as the listener being able to participate in the publisher’s transaction context.


2.1. A Simple Application Event


Let’s create a simple event class — just a placeholder to store the event data.


In this case, the event class holds a String message:


public class CustomSpringEvent extends ApplicationEvent {
    private String message;

    public CustomSpringEvent(Object source, String message) {
        this.message = message;
    public String getMessage() {
        return message;

2.2. A Publisher


Now let’s create a publisher of that event. The publisher constructs the event object and publishes it to anyone who’s listening.


To publish the event, the publisher can simply inject the ApplicationEventPublisher and use the publishEvent() API:

要发布事件,发布者可以简单地注入ApplicationEventPublisher并使用publishEvent() API。

public class CustomSpringEventPublisher {
    private ApplicationEventPublisher applicationEventPublisher;

    public void publishCustomEvent(final String message) {
        System.out.println("Publishing custom event. ");
        CustomSpringEvent customSpringEvent = new CustomSpringEvent(this, message);

Alternatively, the publisher class can implement the ApplicationEventPublisherAware interface, and this will also inject the event publisher on the application startup. Usually, it’s simpler to just inject the publisher with @Autowire.


As of Spring Framework 4.2, the ApplicationEventPublisher interface provides a new overload for the publishEvent(Object event) method that accepts any object as the event. Therefore, Spring events no longer need to extend the ApplicationEvent class.

从Spring Framework 4.2开始,ApplicationEventPublisher接口为publishEvent(Object event)方法提供了一个新的重载,该方法接受任何对象作为事件。因此,Spring事件不再需要扩展ApplicationEvent类。

2.3. A Listener


Finally, let’s create the listener.


The only requirement for the listener is to be a bean and implement ApplicationListener interface:


public class CustomSpringEventListener implements ApplicationListener<CustomSpringEvent> {
    public void onApplicationEvent(CustomSpringEvent event) {
        System.out.println("Received spring custom event - " + event.getMessage());

Notice how our custom listener is parametrized with the generic type of custom event, which makes the onApplicationEvent() method type-safe. This also avoids having to check if the object is an instance of a specific event class and casting it.


And, as already discussed (by default Spring events are synchronous), the doStuffAndPublishAnEvent() method blocks until all listeners finish processing the event.


3. Creating Asynchronous Events


In some cases, publishing events synchronously isn’t really what we’re looking for — we may need async handling of our events.


We can turn that on in the configuration by creating an ApplicationEventMulticaster bean with an executor.


For our purposes here, SimpleAsyncTaskExecutor works well:


public class AsynchronousSpringEventsConfig {
    @Bean(name = "applicationEventMulticaster")
    public ApplicationEventMulticaster simpleApplicationEventMulticaster() {
        SimpleApplicationEventMulticaster eventMulticaster =
          new SimpleApplicationEventMulticaster();
        eventMulticaster.setTaskExecutor(new SimpleAsyncTaskExecutor());
        return eventMulticaster;

The event, the publisher and the listener implementations remain the same as before, but now the listener will asynchronously deal with the event in a separate thread.


4. Existing Framework Events


Spring itself publishes a variety of events out of the box. For example, the ApplicationContext will fire various framework events: ContextRefreshedEvent, ContextStartedEvent, RequestHandledEvent etc.


These events provide application developers an option to hook into the life cycle of the application and the context and add in their own custom logic where needed.


Here’s a quick example of a listener listening for context refreshes:


public class ContextRefreshedListener 
  implements ApplicationListener<ContextRefreshedEvent> {
    public void onApplicationEvent(ContextRefreshedEvent cse) {
        System.out.println("Handling context re-freshed event. ");

To learn more about existing framework events, have a look at our next tutorial here.


5. Annotation-Driven Event Listener


Starting with Spring 4.2, an event listener is not required to be a bean implementing the ApplicationListener interface — it can be registered on any public method of a managed bean via the @EventListener annotation:

从Spring 4.2开始,事件监听器不需要是实现ApplicationListener接口的Bean,它可以通过@EventListener注解在管理Bean的任何public方法上注册。

public class AnnotationDrivenEventListener {
    public void handleContextStart(ContextStartedEvent cse) {
        System.out.println("Handling context started event.");

As before, the method signature declares the event type it consumes.


By default, the listener is invoked synchronously. However, we can easily make it asynchronous by adding an @Async annotation. We just need to remember to enable Async support in the application.


6. Generics Support


It is also possible to dispatch events with generics information in the event type.


6.1. A Generic Application Event


Let’s create a generic event type.


In our example, the event class holds any content and a success status indicator:


public class GenericSpringEvent<T> {
    private T what;
    protected boolean success;

    public GenericSpringEvent(T what, boolean success) {
        this.what = what;
        this.success = success;
    // ... standard getters

Notice the difference between GenericSpringEvent and CustomSpringEvent. We now have the flexibility to publish any arbitrary event and it’s not required to extend from ApplicationEvent anymore.


6.2. A Listener


Now let’s create a listener of that event.


We could define the listener by implementing the ApplicationListener interface like before:

我们可以像以前一样通过实现 ApplicationListener接口来定义监听器。

public class GenericSpringEventListener 
  implements ApplicationListener<GenericSpringEvent<String>> {
    public void onApplicationEvent(@NonNull GenericSpringEvent<String> event) {
        System.out.println("Received spring generic event - " + event.getWhat());

But this definition unfortunately requires us to inherit GenericSpringEvent from the ApplicationEvent class. So for this tutorial, let’s make use of an annotation-driven event listener discussed previously.


It is also possible to make the event listener conditional by defining a boolean SpEL expression on the @EventListener annotation.


In this case, the event handler will only be invoked for a successful GenericSpringEvent of String:


public class AnnotationDrivenEventListener {
    @EventListener(condition = "#event.success")
    public void handleSuccessful(GenericSpringEvent<String> event) {
        System.out.println("Handling generic event (conditional).");

The Spring Expression Language (SpEL) is a powerful expression language that’s covered in detail in another tutorial.


6.3. A Publisher


The event publisher is similar to the one described above. But due to type erasure, we need to publish an event that resolves the generics parameter we would filter on, for example, class GenericStringSpringEvent extends GenericSpringEvent<String>.

事件发布者与上面描述的类似。但是由于类型擦除,我们需要发布一个事件,解决我们要过滤的泛型参数,例如,class GenericStringSpringEvent extends GenericSpringEvent<String>

Also, there’s an alternative way of publishing events. If we return a non-null value from a method annotated with @EventListener as the result, Spring Framework will send that result as a new event for us. Moreover, we can publish multiple new events by returning them in a collection as the result of event processing.

此外,还有一种发布事件的替代方式。如果我们从注有@EventListener的方法中返回一个非空值作为结果,Spring Framework将把该结果作为一个新的事件为我们发送。此外,我们可以通过在一个集合中返回多个新事件作为事件处理的结果来发布这些事件。

7. Transaction-Bound Events


This section is about using the @TransactionalEventListener annotation. To learn more about transaction management, check out Transactions With Spring and JPA.

本节是关于使用@TransactionalEventListener注解。要了解有关事务管理的更多信息,请查看Transactions With Spring and JPA

Since Spring 4.2, the framework provides a new @TransactionalEventListener annotation, which is an extension of @EventListener, that allows binding the listener of an event to a phase of the transaction.

从Spring 4.2开始,框架提供了一个新的@TransactionalEventListener注解,它是@EventListener的扩展,可以将事件的监听器绑定到事务的某个阶段。

Binding is possible to the following transaction phases:


  • AFTER_COMMIT (default) is used to fire the event if the transaction has completed successfully.
  • AFTER_ROLLBACK – if the transaction has rolled back
  • AFTER_COMPLETION – if the transaction has completed (an alias for AFTER_COMMIT and AFTER_ROLLBACK)
  • BEFORE_COMMIT is used to fire the event right before transaction commit.

Here’s a quick example of a transactional event listener:


@TransactionalEventListener(phase = TransactionPhase.BEFORE_COMMIT)
public void handleCustom(CustomSpringEvent event) {
    System.out.println("Handling event inside a transaction BEFORE COMMIT.");

This listener will be invoked only if there’s a transaction in which the event producer is running and it’s about to be committed.


And if no transaction is running, the event isn’t sent at all unless we override this by setting fallbackExecution attribute to true.


8. Conclusion


In this quick article, we went over the basics of dealing with events in Spring, including creating a simple custom event, publishing it and then handling it in a listener.


We also had a brief look at how to enable the asynchronous processing of events in the configuration.


Then we learned about improvements introduced in Spring 4.2, such as annotation-driven listeners, better generics support and events binding to transaction phases.

然后我们了解了Spring 4.2中引入的改进,如注解驱动的监听器、更好的泛型支持和事件绑定到事务阶段。

As always, the code presented in this article is available over on GitHub. This is a Maven-based project, so it should be easy to import and run as it is.