Annotation-based event listeners

Add support for annotation-based event listeners. Enabled automatically
when using Java configuration or can be enabled explicitly via the
regular <context:annotation-driven/> XML element. Detect methods of
managed beans annotated with @eventlistener, either directly or through
a meta-annotation.

Annotated methods must define the event type they listen to as a single
parameter argument. Events are automatically filtered out according to
the method signature. When additional runtime filtering is required, one
can specify the `condition` attribute of the annotation that defines a
SpEL expression that should match to actually invoke the method for a
particular event. The root context exposes the actual `event`
(`#root.event`) and method arguments (`#root.args`). Individual method
arguments are also exposed via either the `a` or `p` alias (`#a0` refers
to the first method argument). Finally, methods arguments are exposed via
their names if that information can be discovered.

Events can be either an ApplicationEvent or any arbitrary payload. Such
payload is wrapped automatically in a PayloadApplicationEvent and managed
explicitly internally. As a result, users can now publish and listen
for arbitrary objects.

If an annotated method has a return value, an non null result is actually
published as a new event, something like:

@eventlistener
public FooEvent handle(BarEvent event) { ... }

Events can be handled in an aynchronous manner by adding `@Async` to the
event method declaration and enabling such infrastructure. Events can
also be ordered by adding an `@Order` annotation to the event method.

Issue: SPR-11622

Author: snicoll

spring-context/src/main/java/org/springframework/cache/interceptor/CacheEvaluationContext.java

@@ -19,13 +19,9 @@
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.Map;
 
-import org.springframework.aop.support.AopUtils;
-import org.springframework.context.expression.AnnotatedElementKey;
+import org.springframework.context.expression.MethodBasedEvaluationContext;
 import org.springframework.core.ParameterNameDiscoverer;
-import org.springframework.expression.spel.support.StandardEvaluationContext;
-import org.springframework.util.ObjectUtils;
 
 /**
  * Cache specific evaluation context that adds a method parameters as SpEL
@@ -44,32 +40,14 @@
  * @author Stephane Nicoll
  * @since 3.1
  */
-class CacheEvaluationContext extends StandardEvaluationContext {
-
-	private final ParameterNameDiscoverer paramDiscoverer;
-
-	private final Method method;
-
-	private final Object[] args;
-
-	private final Class<?> targetClass;
-
-	private final Map<AnnotatedElementKey, Method> methodCache;
+class CacheEvaluationContext extends MethodBasedEvaluationContext {
 
 	private final List<String> unavailableVariables;
 
-	private boolean paramLoaded = false;
+	CacheEvaluationContext(Object rootObject, Method method, Object[] args,
+			ParameterNameDiscoverer paramDiscoverer) {
 
-
-	CacheEvaluationContext(Object rootObject, ParameterNameDiscoverer paramDiscoverer, Method method,
-			Object[] args, Class<?> targetClass, Map<AnnotatedElementKey, Method> methodCache) {
-		super(rootObject);
-
-		this.paramDiscoverer = paramDiscoverer;
-		this.method = method;
-		this.args = args;
-		this.targetClass = targetClass;
-		this.methodCache = methodCache;
+		super(rootObject, method, args, paramDiscoverer);
 		this.unavailableVariables = new ArrayList<String>();
 	}
 
@@ -93,47 +71,7 @@ public Object lookupVariable(String name) {
 		if (this.unavailableVariables.contains(name)) {
 			throw new VariableNotAvailableException(name);
 		}
-		Object variable = super.lookupVariable(name);
-		if (variable != null) {
-			return variable;
-		}
-		if (!this.paramLoaded) {
-			loadArgsAsVariables();
-			this.paramLoaded = true;
-			variable = super.lookupVariable(name);
-		}
-		return variable;
-	}
-
-	private void loadArgsAsVariables() {
-		// shortcut if no args need to be loaded
-		if (ObjectUtils.isEmpty(this.args)) {
-			return;
-		}
-
-		AnnotatedElementKey methodKey = new AnnotatedElementKey(this.method, this.targetClass);
-		Method targetMethod = this.methodCache.get(methodKey);
-		if (targetMethod == null) {
-			targetMethod = AopUtils.getMostSpecificMethod(this.method, this.targetClass);
-			if (targetMethod == null) {
-				targetMethod = this.method;
-			}
-			this.methodCache.put(methodKey, targetMethod);
-		}
-
-		// save arguments as indexed variables
-		for (int i = 0; i < this.args.length; i++) {
-			setVariable("a" + i, this.args[i]);
-			setVariable("p" + i, this.args[i]);
-		}
-
-		String[] parameterNames = this.paramDiscoverer.getParameterNames(targetMethod);
-		// save parameter names (if discovered)
-		if (parameterNames != null) {
-			for (int i = 0; i < parameterNames.length; i++) {
-				setVariable(parameterNames[i], this.args[i]);
-			}
-		}
+		return super.lookupVariable(name);
 	}
 
 }

spring-context/src/main/java/org/springframework/cache/interceptor/ExpressionEvaluator.java

@@ -21,6 +21,7 @@
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+import org.springframework.aop.support.AopUtils;
 import org.springframework.cache.Cache;
 import org.springframework.context.expression.AnnotatedElementKey;
 import org.springframework.context.expression.CachedExpressionEvaluator;
@@ -98,8 +99,9 @@ public EvaluationContext createEvaluationContext(Collection<? extends Cache> cac
 
 		CacheExpressionRootObject rootObject = new CacheExpressionRootObject(caches,
 				method, args, target, targetClass);
+		Method targetMethod = getTargetMethod(targetClass, method);
 		CacheEvaluationContext evaluationContext = new CacheEvaluationContext(rootObject,
-				this.paramNameDiscoverer, method, args, targetClass, this.targetMethodCache);
+				targetMethod, args, this.paramNameDiscoverer);
 		if (result == RESULT_UNAVAILABLE) {
 			evaluationContext.addUnavailableVariable(RESULT_VARIABLE);
 		}
@@ -121,5 +123,18 @@ public boolean unless(String unlessExpression, AnnotatedElementKey methodKey, Ev
 		return getExpression(this.unlessCache, methodKey, unlessExpression).getValue(evalContext, boolean.class);
 	}
 
+	private Method getTargetMethod(Class<?> targetClass, Method method) {
+		AnnotatedElementKey methodKey = new AnnotatedElementKey(method, targetClass);
+		Method targetMethod = this.targetMethodCache.get(methodKey);
+		if (targetMethod == null) {
+			targetMethod = AopUtils.getMostSpecificMethod(method, targetClass);
+			if (targetMethod == null) {
+				targetMethod = method;
+			}
+			this.targetMethodCache.put(methodKey, targetMethod);
+		}
+		return targetMethod;
+	}
+
 
 }

spring-context/src/main/java/org/springframework/context/ApplicationEventPublisher.java

@@ -21,6 +21,7 @@
  * Serves as super-interface for ApplicationContext.
  *
  * @author Juergen Hoeller
+ * @author Stephane Nicoll
  * @since 1.1.1
  * @see ApplicationContext
  * @see ApplicationEventPublisherAware
@@ -38,4 +39,14 @@ public interface ApplicationEventPublisher {
 	 */
 	void publishEvent(ApplicationEvent event);
 
+	/**
+	 * Notify all <strong>matching</strong> listeners registered with this
+	 * application of an event.
+	 * <p>If the specified {@code event} is not an {@link ApplicationEvent}, it
+	 * is wrapped in a {@code GenericApplicationEvent}.
+	 * @param event the event to publish
+	 * @see PayloadApplicationEvent
+	 */
+	void publishEvent(Object event);
+
 }

spring-context/src/main/java/org/springframework/context/PayloadApplicationEvent.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2002-2015 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.context;
+
+import org.springframework.util.Assert;
+
+/**
+ * An {@link ApplicationEvent} that carries an arbitrary payload.
+ * <p>
+ * Mainly intended for internal use within the framework.
+ *
+ * @param <T> the payload type of the event
+ * @author Stephane Nicoll
+ * @since 4.2
+ */
+@SuppressWarnings("serial")
+public class PayloadApplicationEvent<T>
+		extends ApplicationEvent {
+
+	private final T payload;
+
+	public PayloadApplicationEvent(Object source, T payload) {
+		super(source);
+		Assert.notNull(payload, "Payload must not be null");
+		this.payload = payload;
+	}
+
+	/**
+	 * Return the payload of the event.
+	 */
+	public T getPayload() {
+		return payload;
+	}
+
+}
+

spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,6 +30,7 @@
 import org.springframework.beans.factory.support.BeanDefinitionRegistry;
 import org.springframework.beans.factory.support.DefaultListableBeanFactory;
 import org.springframework.beans.factory.support.RootBeanDefinition;
+import org.springframework.context.event.EventListenerMethodProcessor;
 import org.springframework.context.support.GenericApplicationContext;
 import org.springframework.core.annotation.AnnotationAttributes;
 import org.springframework.core.annotation.AnnotationAwareOrderComparator;
@@ -48,6 +49,7 @@
  * @author Juergen Hoeller
  * @author Chris Beams
  * @author Phillip Webb
+ * @author Stephane Nicoll
  * @since 2.5
  * @see ContextAnnotationAutowireCandidateResolver
  * @see CommonAnnotationBeanPostProcessor
@@ -103,6 +105,11 @@ public class AnnotationConfigUtils {
 	private static final String PERSISTENCE_ANNOTATION_PROCESSOR_CLASS_NAME =
 			"org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor";
 
+	/**
+	 * The bean name of the internally managed @EventListener annotation processor.
+	 */
+	public static final String EVENT_LISTENER_PROCESSOR_BEAN_NAME =
+			"org.springframework.context.event.internalEventListenerProcessor";
 
 	private static final boolean jsr250Present =
 			ClassUtils.isPresent("javax.annotation.Resource", AnnotationConfigUtils.class.getClassLoader());
@@ -183,6 +190,12 @@ public static Set<BeanDefinitionHolder> registerAnnotationConfigProcessors(
 			beanDefs.add(registerPostProcessor(registry, def, PERSISTENCE_ANNOTATION_PROCESSOR_BEAN_NAME));
 		}
 
+		if (!registry.containsBeanDefinition(EVENT_LISTENER_PROCESSOR_BEAN_NAME)) {
+			RootBeanDefinition def = new RootBeanDefinition(EventListenerMethodProcessor.class);
+			def.setSource(source);
+			beanDefs.add(registerPostProcessor(registry, def, EVENT_LISTENER_PROCESSOR_BEAN_NAME));
+		}
+
 		return beanDefs;
 	}