Provide meta-annotation support in the TCF

Spring 3.0 already allows component stereotypes to be used in a
meta-annotation fashion, for example by creating a custom
@TransactionalService stereotype annotation which combines
@transactional and @service in a single, reusable, application-specific
annotation. However, the Spring TestContext Framework (TCF) currently
does not provide any support for test-related annotations to be used as
meta-annotations.

This commit overhauls the TCF with regard to how annotations are
retrieved and adds explicit support for the following annotations to be
used as meta-annotations in conjunction with the TCF.

- @ContextConfiguration
- @ContextHierarchy
- @activeprofiles
- @DirtiesContext
- @IfProfileValue
- @ProfileValueSourceConfiguration
- @BeforeTransaction
- @AfterTransaction
- @TransactionConfiguration
- @Rollback
- @TestExecutionListeners
- @repeat
- @timed
- @WebAppConfiguration

Note that meta-annotation support for @transactional was already
available prior to this commit.

The following is a summary of the major changes included in this commit.

- Now using AnnotationUtils.getAnnotation() instead of
  Class.getAnnotation() where appropriate in the TestContext Framework.
- Now using AnnotationUtils.findAnnotation() instead of
  Class.isAnnotationPresent() where appropriate in the TestContext
  Framework.
- Introduced findAnnotationPrefersInteracesOverLocalMetaAnnotations() in
  AnnotationUtilsTests in order to verify the status quo.
- AnnotationUtils.findAnnotationDeclaringClass() and
  AnnotationUtils.findAnnotationDeclaringClassForTypes() now support
  meta annotations.
- Introduced MetaAnnotationUtils and AnnotationDescriptor in the
  spring-test module.
- Introduced UntypedAnnotationDescriptor in MetaAnnotationUtils.
- Introduced findAnnotationDescriptorForTypes() in MetaAnnotationUtils.
- ContextLoaderUtils now uses MetaAnnotationUtils for looking up
  @activeprofiles as a potential meta-annotation.
- TestContextManager now uses MetaAnnotationUtils for looking up
  @TestExecutionListeners as a potential meta-annotation.
- DirtiesContextTestExecutionListener now uses AnnotationUtils for
  looking up @DirtiesContext as a potential meta-annotation.
- Introduced DirtiesContextTestExecutionListenerTests.
- ProfileValueUtils now uses AnnotationUtils for looking up
  @IfProfileValue and @ProfileValueSourceConfiguration as potential
  meta-annotations.
- @BeforeTransaction and @AfterTransaction now support ANNOTATION_TYPE
  as a target, allowing them to be used as meta-annotations.
- TransactionalTestExecutionListener now uses AnnotationUtils for
  looking up @BeforeTransaction, @AfterTransaction, @Rollback, and
  @TransactionConfiguration as potential meta-annotations.
- Introduced TransactionalTestExecutionListenerTests.
- @repeat and @timed now support ANNOTATION_TYPE as a target, allowing
  them to be used as meta-annotations.
- SpringJUnit4ClassRunner now uses AnnotationUtils for looking up
  @repeat and @timed as potential meta-annotations.
- Moved all remaining logic for building the MergedContextConfiguration
  from the DefaultTestContext constructor to
  ContextLoaderUtils.buildMergedContextConfiguration().
- Verified meta-annotation support for @WebAppConfiguration and
  @ContextConfiguration.

Issue: SPR-7827

Author: sbrannen

spring-core/src/main/java/org/springframework/core/annotation/AnnotationUtils.java

@@ -285,9 +285,8 @@ public static <A extends Annotation> A findAnnotation(Class<?> clazz, Class<A> a
 	 * <p>The standard {@link Class} API does not provide a mechanism for determining which class
 	 * in an inheritance hierarchy actually declares an {@link Annotation}, so we need to handle
 	 * this explicitly.
-	 * @param annotationType the Class object corresponding to the annotation type
-	 * @param clazz the Class object corresponding to the class on which to check for the annotation,
-	 * or {@code null}
+	 * @param annotationType the annotation class to look for, both locally and as a meta-annotation
+	 * @param clazz the class on which to check for the annotation, or {@code null}
 	 * @return the first {@link Class} in the inheritance hierarchy of the specified {@code clazz}
 	 * which declares an annotation for the specified {@code annotationType}, or {@code null}
 	 * if not found
@@ -301,8 +300,24 @@ public static Class<?> findAnnotationDeclaringClass(Class<? extends Annotation>
 		if (clazz == null || clazz.equals(Object.class)) {
 			return null;
 		}
-		return (isAnnotationDeclaredLocally(annotationType, clazz)) ? clazz : findAnnotationDeclaringClass(
-			annotationType, clazz.getSuperclass());
+
+		// Declared locally?
+		if (isAnnotationDeclaredLocally(annotationType, clazz)) {
+			return clazz;
+		}
+
+		// Declared on a stereotype annotation (i.e., as a meta-annotation)?
+		if (!Annotation.class.isAssignableFrom(clazz)) {
+			for (Annotation stereotype : clazz.getAnnotations()) {
+				Class<?> declaringClass = findAnnotationDeclaringClass(annotationType, stereotype.annotationType());
+				if (declaringClass != null) {
+					return declaringClass;
+				}
+			}
+		}
+
+		// Declared on a superclass?
+		return findAnnotationDeclaringClass(annotationType, clazz.getSuperclass());
 	}
 
 	/**

spring-core/src/test/java/org/springframework/core/annotation/AnnotationUtilsTests.java

@@ -96,6 +96,18 @@ public void testFindMethodAnnotationOnBridgeMethod() throws Exception {
 	// assertNotNull(o);
 	// }
 
+	@Test
+	public void findAnnotationPrefersInteracesOverLocalMetaAnnotations() {
+		Component component = AnnotationUtils.findAnnotation(
+			ClassWithLocalMetaAnnotationAndMetaAnnotatedInterface.class, Component.class);
+
+		// By inspecting ClassWithLocalMetaAnnotationAndMetaAnnotatedInterface, one
+		// might expect that "meta2" should be found; however, with the current
+		// implementation "meta1" will be found.
+		assertNotNull(component);
+		assertEquals("meta1", component.value());
+	}
+
 	@Test
 	public void testFindAnnotationDeclaringClass() throws Exception {
 		// no class-level annotation
@@ -133,7 +145,7 @@ public void findAnnotationDeclaringClassForTypesWithSingleCandidateType() {
 		assertEquals(InheritedAnnotationInterface.class,
 			findAnnotationDeclaringClassForTypes(transactionalCandidateList, InheritedAnnotationInterface.class));
 		assertNull(findAnnotationDeclaringClassForTypes(transactionalCandidateList,
-			SubInheritedAnnotationInterface.class));
+				SubInheritedAnnotationInterface.class));
 		assertEquals(InheritedAnnotationClass.class,
 			findAnnotationDeclaringClassForTypes(transactionalCandidateList, InheritedAnnotationClass.class));
 		assertEquals(InheritedAnnotationClass.class,
@@ -288,19 +300,23 @@ public void testGetRepeatableFromMethod() throws Exception {
 
 
 	@Component(value = "meta1")
+	@Order
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface Meta1 {
 	}
 
 	@Component(value = "meta2")
+	@Transactional
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface Meta2 {
 	}
 
 	@Meta1
-	@Component(value = "local")
+	static interface InterfaceWithMetaAnnotation {
+	}
+
 	@Meta2
-	static class HasLocalAndMetaComponentAnnotation {
+	static class ClassWithLocalMetaAnnotationAndMetaAnnotatedInterface implements InterfaceWithMetaAnnotation {
 	}
 
 	public static interface AnnotatedInterface {

spring-test/src/main/java/org/springframework/test/annotation/ProfileValueUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 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.
@@ -25,6 +25,8 @@
 import org.springframework.util.ObjectUtils;
 import org.springframework.util.StringUtils;
 
+import static org.springframework.core.annotation.AnnotationUtils.*;
+
 /**
  * General utility methods for working with <em>profile values</em>.
  *
@@ -63,7 +65,7 @@ public static ProfileValueSource retrieveProfileValueSource(Class<?> testClass)
 		Assert.notNull(testClass, "testClass must not be null");
 
 		Class<ProfileValueSourceConfiguration> annotationType = ProfileValueSourceConfiguration.class;
-		ProfileValueSourceConfiguration config = testClass.getAnnotation(annotationType);
+		ProfileValueSourceConfiguration config = findAnnotation(testClass, annotationType);
 		if (logger.isDebugEnabled()) {
 			logger.debug("Retrieved @ProfileValueSourceConfiguration [" + config + "] for test class ["
 					+ testClass.getName() + "]");
@@ -114,7 +116,7 @@ public static ProfileValueSource retrieveProfileValueSource(Class<?> testClass)
 	 * environment
 	 */
 	public static boolean isTestEnabledInThisEnvironment(Class<?> testClass) {
-		IfProfileValue ifProfileValue = testClass.getAnnotation(IfProfileValue.class);
+		IfProfileValue ifProfileValue = findAnnotation(testClass, IfProfileValue.class);
 		return isTestEnabledInThisEnvironment(retrieveProfileValueSource(testClass), ifProfileValue);
 	}
 
@@ -157,11 +159,11 @@ public static boolean isTestEnabledInThisEnvironment(Method testMethod, Class<?>
 	public static boolean isTestEnabledInThisEnvironment(ProfileValueSource profileValueSource, Method testMethod,
 			Class<?> testClass) {
 
-		IfProfileValue ifProfileValue = testClass.getAnnotation(IfProfileValue.class);
+		IfProfileValue ifProfileValue = findAnnotation(testClass, IfProfileValue.class);
 		boolean classLevelEnabled = isTestEnabledInThisEnvironment(profileValueSource, ifProfileValue);
 
 		if (classLevelEnabled) {
-			ifProfileValue = testMethod.getAnnotation(IfProfileValue.class);
+			ifProfileValue = findAnnotation(testMethod, IfProfileValue.class);
 			return isTestEnabledInThisEnvironment(profileValueSource, ifProfileValue);
 		}
 

spring-test/src/main/java/org/springframework/test/annotation/Repeat.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 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.
@@ -17,25 +17,27 @@
 package org.springframework.test.annotation;
 
 import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
 /**
  * Test annotation to indicate that a test method should be invoked repeatedly.
- * <p />
- * Note that the scope of execution to be repeated includes execution of the
+ *
+ * <p>Note that the scope of execution to be repeated includes execution of the
  * test method itself as well as any <em>set up</em> or <em>tear down</em> of
  * the test fixture.
  *
  * @author Rod Johnson
  * @author Sam Brannen
  * @since 2.0
+ * @see Timed
  */
 @Documented
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.METHOD)
+@Retention(RUNTIME)
+@Target({ METHOD, ANNOTATION_TYPE })
 public @interface Repeat {
 
 	int value() default 1;

spring-test/src/main/java/org/springframework/test/annotation/Timed.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 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.
@@ -17,34 +17,31 @@
 package org.springframework.test.annotation;
 
 import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
 /**
- * <p>
  * Test-specific annotation to indicate that a test method has to finish
  * execution in a {@link #millis() specified time period}.
- * </p>
- * <p>
- * If the text execution takes longer than the specified time period, then the
- * test is to be considered failed.
- * </p>
- * <p>
- * Note that the time period includes execution of the test method itself, any
- * {@link Repeat repetitions} of the test, and any <em>set up</em> or
+ *
+ * <p>If the text execution takes longer than the specified time period, then
+ * the test is to be considered failed.
+ *
+ * <p>Note that the time period includes execution of the test method itself,
+ * any {@link Repeat repetitions} of the test, and any <em>set up</em> or
  * <em>tear down</em> of the test fixture.
- * </p>
  *
  * @author Rod Johnson
  * @author Sam Brannen
  * @since 2.0
  * @see Repeat
  */
 @Documented
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.METHOD)
+@Retention(RUNTIME)
+@Target({ METHOD, ANNOTATION_TYPE })
 public @interface Timed {
 
 	/**