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}