001/* 002 * Copyright 2002-2016 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.context.event; 018 019import java.lang.annotation.Documented; 020import java.lang.annotation.ElementType; 021import java.lang.annotation.Retention; 022import java.lang.annotation.RetentionPolicy; 023import java.lang.annotation.Target; 024 025import org.springframework.context.ApplicationEvent; 026import org.springframework.core.annotation.AliasFor; 027 028/** 029 * Annotation that marks a method as a listener for application events. 030 * 031 * <p>If an annotated method supports a single event type, the method may 032 * declare a single parameter that reflects the event type to listen to. 033 * If an annotated method supports multiple event types, this annotation 034 * may refer to one or more supported event types using the {@code classes} 035 * attribute. See the {@link #classes} javadoc for further details. 036 * 037 * <p>Events can be {@link ApplicationEvent} instances as well as arbitrary 038 * objects. 039 * 040 * <p>Processing of {@code @EventListener} annotations is performed via 041 * the internal {@link EventListenerMethodProcessor} bean which gets 042 * registered automatically when using Java config or manually via the 043 * {@code <context:annotation-config/>} or {@code <context:component-scan/>} 044 * element when using XML config. 045 * 046 * <p>Annotated methods may have a non-{@code void} return type. When they 047 * do, the result of the method invocation is sent as a new event. If the 048 * return type is either an array or a collection, each element is sent 049 * as a new individual event. 050 * 051 * <p>It is also possible to define the order in which listeners for a 052 * certain event are to be invoked. To do so, add Spring's common 053 * {@link org.springframework.core.annotation.Order @Order} annotation 054 * alongside this event listener annotation. 055 * 056 * <p>While it is possible for an event listener to declare that it 057 * throws arbitrary exception types, any checked exceptions thrown 058 * from an event listener will be wrapped in an 059 * {@link java.lang.reflect.UndeclaredThrowableException} 060 * since the event publisher can only handle runtime exceptions. 061 * 062 * @author Stephane Nicoll 063 * @since 4.2 064 * @see EventListenerMethodProcessor 065 */ 066@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE}) 067@Retention(RetentionPolicy.RUNTIME) 068@Documented 069public @interface EventListener { 070 071 /** 072 * Alias for {@link #classes}. 073 */ 074 @AliasFor("classes") 075 Class<?>[] value() default {}; 076 077 /** 078 * The event classes that this listener handles. 079 * <p>If this attribute is specified with a single value, the 080 * annotated method may optionally accept a single parameter. 081 * However, if this attribute is specified with multiple values, 082 * the annotated method must <em>not</em> declare any parameters. 083 */ 084 @AliasFor("value") 085 Class<?>[] classes() default {}; 086 087 /** 088 * Spring Expression Language (SpEL) attribute used for making the 089 * event handling conditional. 090 * <p>Default is {@code ""}, meaning the event is always handled. 091 * <p>The SpEL expression evaluates against a dedicated context that 092 * provides the following meta-data: 093 * <ul> 094 * <li>{@code #root.event}, {@code #root.args} for 095 * references to the {@link ApplicationEvent} and method arguments 096 * respectively.</li> 097 * <li>Method arguments can be accessed by index. For instance the 098 * first argument can be accessed via {@code #root.args[0]}, {@code #p0} 099 * or {@code #a0}. Arguments can also be accessed by name if that 100 * information is available.</li> 101 * </ul> 102 */ 103 String condition() default ""; 104 105}