diff --git a/spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java b/spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java index aa6ed211370..564f582edf6 100644 --- a/spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java +++ b/spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java @@ -27,28 +27,30 @@ import java.lang.annotation.Target; * Test annotation which indicates that the * {@link org.springframework.context.ApplicationContext ApplicationContext} * associated with a test is dirty and should be closed: + * * - *

- * Use this annotation if a test has modified the context — for example, by - * replacing a bean definition or changing the state of a singleton bean. + * + *

Use this annotation if a test has modified the context — for example, + * by replacing a bean definition or changing the state of a singleton bean. * Subsequent tests will be supplied a new context. - *

- *

- * {@code @DirtiesContext} may be used as a class-level and method-level + * + *

{@code @DirtiesContext} may be used as a class-level and method-level * annotation within the same class. In such scenarios, the * {@code ApplicationContext} will be marked as dirty after any * such annotated method as well as after the entire class. If the * {@link ClassMode} is set to {@link ClassMode#AFTER_EACH_TEST_METHOD * AFTER_EACH_TEST_METHOD}, the context will be marked dirty after each test * method in the class. - *

+ * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. * * @author Sam Brannen * @author Rod Johnson diff --git a/spring-test/src/main/java/org/springframework/test/annotation/IfProfileValue.java b/spring-test/src/main/java/org/springframework/test/annotation/IfProfileValue.java index 97ca1298cd1..5009a75f85e 100644 --- a/spring-test/src/main/java/org/springframework/test/annotation/IfProfileValue.java +++ b/spring-test/src/main/java/org/springframework/test/annotation/IfProfileValue.java @@ -63,6 +63,9 @@ import java.lang.annotation.Target; * } * * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Rod Johnson * @author Sam Brannen * @since 2.0 diff --git a/spring-test/src/main/java/org/springframework/test/annotation/ProfileValueSourceConfiguration.java b/spring-test/src/main/java/org/springframework/test/annotation/ProfileValueSourceConfiguration.java index 4e240aa6ea7..cd285587981 100644 --- a/spring-test/src/main/java/org/springframework/test/annotation/ProfileValueSourceConfiguration.java +++ b/spring-test/src/main/java/org/springframework/test/annotation/ProfileValueSourceConfiguration.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. @@ -24,12 +24,13 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - *

- * ProfileValueSourceConfiguration is a class-level annotation which is used to - * specify what type of {@link ProfileValueSource} to use when retrieving - * profile values configured via the {@link IfProfileValue + *

{@code ProfileValueSourceConfiguration} is a class-level annotation which + * is used to specify what type of {@link ProfileValueSource} to use when + * retrieving profile values configured via the {@link IfProfileValue * @IfProfileValue} annotation. - *

+ * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. * * @author Sam Brannen * @since 2.5 diff --git a/spring-test/src/main/java/org/springframework/test/annotation/Repeat.java b/spring-test/src/main/java/org/springframework/test/annotation/Repeat.java index 7b7d04816ff..35b72d5667b 100644 --- a/spring-test/src/main/java/org/springframework/test/annotation/Repeat.java +++ b/spring-test/src/main/java/org/springframework/test/annotation/Repeat.java @@ -30,6 +30,9 @@ import static java.lang.annotation.RetentionPolicy.*; * test method itself as well as any set up or tear down of * the test fixture. * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Rod Johnson * @author Sam Brannen * @since 2.0 diff --git a/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java b/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java index 85333dcb618..809f03fce63 100644 --- a/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java +++ b/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java @@ -29,6 +29,9 @@ import static java.lang.annotation.RetentionPolicy.*; * has completed. If {@code true}, the transaction will be rolled back; * otherwise, the transaction will be committed. * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Sam Brannen * @since 2.5 */ diff --git a/spring-test/src/main/java/org/springframework/test/annotation/Timed.java b/spring-test/src/main/java/org/springframework/test/annotation/Timed.java index fc7c6e0bc09..9f3a324f6a4 100644 --- a/spring-test/src/main/java/org/springframework/test/annotation/Timed.java +++ b/spring-test/src/main/java/org/springframework/test/annotation/Timed.java @@ -34,6 +34,9 @@ import static java.lang.annotation.RetentionPolicy.*; * any {@link Repeat repetitions} of the test, and any set up or * tear down of the test fixture. * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Rod Johnson * @author Sam Brannen * @since 2.0 diff --git a/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java b/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java index 0b76fa42318..c54e7c2d68b 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java +++ b/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java @@ -29,6 +29,9 @@ import java.lang.annotation.Target; * an {@link org.springframework.context.ApplicationContext ApplicationContext} * for test classes. * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Sam Brannen * @since 3.1 * @see SmartContextLoader diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java index 7033765c0b3..6018f06e57d 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java +++ b/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java @@ -64,6 +64,9 @@ import org.springframework.context.ConfigurableApplicationContext; * for further information regarding the configuration and semantics of * annotated classes. * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Sam Brannen * @since 2.5 * @see ContextHierarchy diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java b/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java index 7eac62d6e5d..dd099d773cf 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java +++ b/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java @@ -131,6 +131,9 @@ import java.lang.annotation.Target; * ) * public class ExtendedTests extends BaseTests {} * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Sam Brannen * @since 3.2.2 * @see ContextConfiguration diff --git a/spring-test/src/main/java/org/springframework/test/context/MetaAnnotationUtils.java b/spring-test/src/main/java/org/springframework/test/context/MetaAnnotationUtils.java index 02efb376705..4410dd137cf 100644 --- a/spring-test/src/main/java/org/springframework/test/context/MetaAnnotationUtils.java +++ b/spring-test/src/main/java/org/springframework/test/context/MetaAnnotationUtils.java @@ -20,6 +20,7 @@ import java.lang.annotation.Annotation; import org.springframework.core.annotation.AnnotatedElementUtils; import org.springframework.core.annotation.AnnotationAttributes; +import org.springframework.core.annotation.AnnotationUtils; import org.springframework.core.style.ToStringCreator; import org.springframework.util.Assert; import org.springframework.util.ObjectUtils; @@ -27,10 +28,26 @@ import org.springframework.util.ObjectUtils; import static org.springframework.core.annotation.AnnotationUtils.*; /** - * TODO Document MetaAnnotationUtils. + * {@code MetaAnnotationUtils} is a collection of utility methods that complements + * support already available in {@link AnnotationUtils}. + * + *

Whereas {@code AnnotationUtils} only provides utilities for getting + * or finding an annotation, {@code MetaAnnotationUtils} provides + * additional support for determining the root class on which an + * annotation is declared, either directly or via a composed annotation. + * This additional information is encapsulated in an {@link AnnotationDescriptor}. + * + *

The additional information provided by an {@code AnnotationDescriptor} is + * required in the Spring TestContext Framework in order to be able to + * support class hierarchy traversals for inherited annotations such as + * {@link ContextConfiguration @ContextConfiguration}, + * {@link TestExecutionListeners @TestExecutionListeners}, and + * {@link ActiveProfiles @ActiveProfiles}. * * @author Sam Brannen * @since 4.0 + * @see AnnotationUtils + * @see AnnotationDescriptor */ abstract class MetaAnnotationUtils { @@ -39,13 +56,37 @@ abstract class MetaAnnotationUtils { } /** - * TODO Document findAnnotationDescriptor(). + * Find the {@link AnnotationDescriptor} for the supplied {@code annotationType} + * from the supplied {@link Class}, traversing its annotations and superclasses + * if no annotation can be found on the given class itself. + * + *

This method explicitly handles class-level annotations which are not + * declared as {@linkplain java.lang.annotation.Inherited inherited} as + * well as meta-annotations. + * + *

The algorithm operates as follows: + *

    + *
  1. Search for a local declaration of the annotation on the given class + * and return a corresponding {@code AnnotationDescriptor} if found. + *
  2. Search through all annotations that the given class declares, + * returning an {@code AnnotationDescriptor} for the first matching + * candidate, if any. + *
  3. Proceed with introspection of the superclass hierarchy of the given + * class by returning to step #1 with the superclass as the class to look + * for annotations on. + *
+ * + *

If the supplied {@code clazz} is an interface, only the interface + * itself will be checked; the inheritance hierarchy for interfaces will not + * be traversed. * * @param clazz the class to look for annotations on * @param annotationType the annotation class to look for, both locally and * as a meta-annotation * @return the corresponding annotation descriptor if the annotation was found; * otherwise {@code null} + * @see AnnotationUtils#findAnnotationDeclaringClass(Class, Class) + * @see #findAnnotationDescriptorForTypes(Class, Class...) */ public static AnnotationDescriptor findAnnotationDescriptor(Class clazz, Class annotationType) { @@ -76,13 +117,43 @@ abstract class MetaAnnotationUtils { } /** - * TODO Document findAnnotationDescriptorForTypes(). + * Find the {@link UntypedAnnotationDescriptor} for the first {@link Class} + * in the inheritance hierarchy of the specified {@code clazz} (including + * the specified {@code clazz} itself) which declares at least one of the + * specified {@code annotationTypes}, or {@code null} if none of the + * specified annotation types could be found. + * + *

This method traverses the annotations and superclasses of the specified + * {@code clazz} if no annotation can be found on the given class itself. + * + *

This method explicitly handles class-level annotations which are not + * declared as {@linkplain java.lang.annotation.Inherited inherited} as + * well as meta-annotations. + * + *

The algorithm operates as follows: + *

    + *
  1. Search for a local declaration of one of the annotation types on + * the given class and return a corresponding {@code UntypedAnnotationDescriptor} + * if found. + *
  2. Search through all annotations that the given class declares, + * returning an {@code UntypedAnnotationDescriptor} for the first matching + * candidate, if any. + *
  3. Proceed with introspection of the superclass hierarchy of the given + * class by returning to step #1 with the superclass as the class to look + * for annotations on. + *
+ * + *

If the supplied {@code clazz} is an interface, only the interface + * itself will be checked; the inheritance hierarchy for interfaces will not + * be traversed. * * @param clazz the class to look for annotations on * @param annotationTypes the types of annotations to look for, both locally * and as meta-annotations * @return the corresponding annotation descriptor if one of the annotations * was found; otherwise {@code null} + * @see AnnotationUtils#findAnnotationDeclaringClassForTypes(java.util.List, Class) + * @see #findAnnotationDescriptor(Class, Class) */ @SuppressWarnings("unchecked") public static UntypedAnnotationDescriptor findAnnotationDescriptorForTypes(Class clazz, @@ -241,6 +312,14 @@ abstract class MetaAnnotationUtils { } } + /** + * Untyped extension of {@code AnnotationDescriptor} that is used + * to describe the declaration of one of several candidate annotation types + * where the actual annotation type cannot be predetermined. + * + * @author Sam Brannen + * @since 4.0 + */ public static class UntypedAnnotationDescriptor extends AnnotationDescriptor { public UntypedAnnotationDescriptor(Class declaringClass, Annotation annotation) { diff --git a/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java b/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java index 388f66b5c8e..30d8f43d30f 100644 --- a/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java +++ b/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java @@ -31,6 +31,9 @@ import java.lang.annotation.Target; *

Typically, {@code @TestExecutionListeners} will be used in conjunction with * {@link ContextConfiguration @ContextConfiguration}. * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Sam Brannen * @since 2.5 * @see TestExecutionListener diff --git a/spring-test/src/main/java/org/springframework/test/context/transaction/AfterTransaction.java b/spring-test/src/main/java/org/springframework/test/context/transaction/AfterTransaction.java index c05b12c6b07..c8d46156603 100644 --- a/spring-test/src/main/java/org/springframework/test/context/transaction/AfterTransaction.java +++ b/spring-test/src/main/java/org/springframework/test/context/transaction/AfterTransaction.java @@ -24,16 +24,17 @@ import static java.lang.annotation.ElementType.*; import static java.lang.annotation.RetentionPolicy.*; /** - *

- * Test annotation to indicate that the annotated {@code public void} + *

Test annotation to indicate that the annotated {@code public void} * method should be executed after a transaction is ended for test * methods configured to run within a transaction via the * {@code @Transactional} annotation. - *

+ * *

* The {@code @AfterTransaction} methods of superclasses will be * executed after those of the current class. - *

+ * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. * * @author Sam Brannen * @since 2.5 diff --git a/spring-test/src/main/java/org/springframework/test/context/transaction/BeforeTransaction.java b/spring-test/src/main/java/org/springframework/test/context/transaction/BeforeTransaction.java index a39cb19007e..f995f7c78da 100644 --- a/spring-test/src/main/java/org/springframework/test/context/transaction/BeforeTransaction.java +++ b/spring-test/src/main/java/org/springframework/test/context/transaction/BeforeTransaction.java @@ -24,17 +24,18 @@ import static java.lang.annotation.ElementType.*; import static java.lang.annotation.RetentionPolicy.*; /** - *

- * Test annotation to indicate that the annotated {@code public void} + *

Test annotation to indicate that the annotated {@code public void} * method should be executed before a transaction is started for test * methods configured to run within a transaction via the * {@code @Transactional} annotation. - *

- *

- * The {@code @BeforeTransaction} methods of superclasses will be + * + *

The {@code @BeforeTransaction} methods of superclasses will be * executed before those of the current class. *

* + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Sam Brannen * @since 2.5 * @see org.springframework.transaction.annotation.Transactional diff --git a/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java index 7d91bcba026..3fc2759360d 100644 --- a/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java +++ b/spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.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. @@ -27,6 +27,9 @@ import java.lang.annotation.Target; * {@code TransactionConfiguration} defines class-level metadata for configuring * transactional tests. * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Sam Brannen * @since 2.5 * @see TransactionalTestExecutionListener diff --git a/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java index 7f24c2663f6..07746c1e142 100644 --- a/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java +++ b/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java @@ -38,6 +38,9 @@ import java.lang.annotation.Target; * {@link org.springframework.test.context.ContextConfiguration @ContextConfiguration}, * either within a single test class or within a test class hierarchy. * + *

As of Spring Framework 4.0, this annotation may be used as a + * meta-annotation to create custom composed annotations. + * * @author Sam Brannen * @since 3.2 * @see org.springframework.web.context.WebApplicationContext diff --git a/spring-test/src/test/java/org/springframework/test/context/MetaAnnotationUtilsTests.java b/spring-test/src/test/java/org/springframework/test/context/MetaAnnotationUtilsTests.java index 0daaf5e27da..85bfc5e741e 100644 --- a/spring-test/src/test/java/org/springframework/test/context/MetaAnnotationUtilsTests.java +++ b/spring-test/src/test/java/org/springframework/test/context/MetaAnnotationUtilsTests.java @@ -36,6 +36,7 @@ import static org.springframework.test.context.MetaAnnotationUtils.*; * * @author Sam Brannen * @since 4.0 + * @see OverriddenMetaAnnotationAttributesTests */ public class MetaAnnotationUtilsTests { diff --git a/spring-test/src/test/java/org/springframework/test/context/OverriddenMetaAnnotationAttributesTests.java b/spring-test/src/test/java/org/springframework/test/context/OverriddenMetaAnnotationAttributesTests.java index d1bc66ac06a..ce4d56fee54 100644 --- a/spring-test/src/test/java/org/springframework/test/context/OverriddenMetaAnnotationAttributesTests.java +++ b/spring-test/src/test/java/org/springframework/test/context/OverriddenMetaAnnotationAttributesTests.java @@ -34,6 +34,7 @@ import static org.springframework.test.context.MetaAnnotationUtils.*; * * @author Sam Brannen * @since 4.0 + * @see MetaAnnotationUtilsTests */ public class OverriddenMetaAnnotationAttributesTests {