root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Document meta-annotation support in the TCF 

- Completed Javadoc for MetaAnnotationUtils.
- Added Javadoc notes to multiple annotations in the TCF, pointing out
  which annotations can be used as meta-annotations.

Issue: SPR-11109
This commit is contained in:
Sam Brannen 2013-12-11 14:43:10 +01:00
parent 9fbb57c3ec
commit a223e247c2
17 changed files with 148 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java
View File

@ -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 <em>dirty</em> and should be closed:
*
* <ul>
* <li>after the current test, when declared at the method level</li>
* <li>after each test method in the current test class, when declared at the
* class level with class mode set to {@link ClassMode#AFTER_EACH_TEST_METHOD
* AFTER_EACH_TEST_METHOD}</li>
* <li>after the current test class, when declared at the class level with class
* mode set to {@link ClassMode#AFTER_CLASS AFTER_CLASS}</li>
* <li>after the current test, when declared at the method level</li>
* <li>after each test method in the current test class, when declared at the
* class level with class mode set to {@link ClassMode#AFTER_EACH_TEST_METHOD
* AFTER_EACH_TEST_METHOD}</li>
* <li>after the current test class, when declared at the class level with class
* mode set to {@link ClassMode#AFTER_CLASS AFTER_CLASS}</li>
* </ul>
* <p>
* Use this annotation if a test has modified the context &mdash; for example, by
* replacing a bean definition or changing the state of a singleton bean.
*
* <p>Use this annotation if a test has modified the context &mdash; for example,
* by replacing a bean definition or changing the state of a singleton bean.
* Subsequent tests will be supplied a new context.
* </p>
* <p>
* {@code @DirtiesContext} may be used as a class-level and method-level
*
* <p>{@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 <em>dirty</em> 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.
* </p>
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @author Rod Johnson

3
spring-test/src/main/java/org/springframework/test/annotation/IfProfileValue.java
View File

@ -63,6 +63,9 @@ import java.lang.annotation.Target;
* }
* </pre>
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Rod Johnson
* @author Sam Brannen
* @since 2.0

13
spring-test/src/main/java/org/springframework/test/annotation/ProfileValueSourceConfiguration.java
View File

@ -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;
/**
* <p>
* ProfileValueSourceConfiguration is a class-level annotation which is used to
* specify what type of {@link ProfileValueSource} to use when retrieving
* <em>profile values</em> configured via the {@link IfProfileValue
* <p>{@code ProfileValueSourceConfiguration} is a class-level annotation which
* is used to specify what type of {@link ProfileValueSource} to use when
* retrieving <em>profile values</em> configured via the {@link IfProfileValue
* &#064;IfProfileValue} annotation.
* </p>
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 2.5

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

@ -30,6 +30,9 @@ import static java.lang.annotation.RetentionPolicy.*;
* test method itself as well as any <em>set up</em> or <em>tear down</em> of
* the test fixture.
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Rod Johnson
* @author Sam Brannen
* @since 2.0

3
spring-test/src/main/java/org/springframework/test/annotation/Rollback.java
View File

@ -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.
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 2.5
*/

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

@ -34,6 +34,9 @@ import static java.lang.annotation.RetentionPolicy.*;
* any {@link Repeat repetitions} of the test, and any <em>set up</em> or
* <em>tear down</em> of the test fixture.
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Rod Johnson
* @author Sam Brannen
* @since 2.0

3
spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java
View File

@ -29,6 +29,9 @@ import java.lang.annotation.Target;
* an {@link org.springframework.context.ApplicationContext ApplicationContext}
* for test classes.
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 3.1
* @see SmartContextLoader

3
spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java
View File

@ -64,6 +64,9 @@ import org.springframework.context.ConfigurableApplicationContext;
* for further information regarding the configuration and semantics of
* <em>annotated classes</em>.
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 2.5
* @see ContextHierarchy

3
spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java
View File

@ -131,6 +131,9 @@ import java.lang.annotation.Target;
* )
* public class ExtendedTests extends BaseTests {}</pre>
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 3.2.2
* @see ContextConfiguration

85
spring-test/src/main/java/org/springframework/test/context/MetaAnnotationUtils.java
View File

@ -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}.
*
* <p>Whereas {@code AnnotationUtils} only provides utilities for <em>getting</em>
* or <em>finding</em> an annotation, {@code MetaAnnotationUtils} provides
* additional support for determining the <em>root class</em> on which an
* annotation is declared, either directly or via a <em>composed annotation</em>.
* This additional information is encapsulated in an {@link AnnotationDescriptor}.
*
* <p>The additional information provided by an {@code AnnotationDescriptor} is
* required in the <em>Spring TestContext Framework</em> in order to be able to
* support class hierarchy traversals for <em>inherited</em> 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.
*
* <p>This method explicitly handles class-level annotations which are not
* declared as {@linkplain java.lang.annotation.Inherited inherited} <em>as
* well as meta-annotations</em>.
*
* <p>The algorithm operates as follows:
* <ol>
* <li>Search for a local declaration of the annotation on the given class
* and return a corresponding {@code AnnotationDescriptor} if found.
* <li>Search through all annotations that the given class declares,
* returning an {@code AnnotationDescriptor} for the first matching
* candidate, if any.
* <li>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.
* </ol>
*
* <p>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 <T extends Annotation> AnnotationDescriptor<T> findAnnotationDescriptor(Class<?> clazz,
Class<T> 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.
*
* <p>This method traverses the annotations and superclasses of the specified
* {@code clazz} if no annotation can be found on the given class itself.
*
* <p>This method explicitly handles class-level annotations which are not
* declared as {@linkplain java.lang.annotation.Inherited inherited} <em>as
* well as meta-annotations</em>.
*
* <p>The algorithm operates as follows:
* <ol>
* <li>Search for a local declaration of one of the annotation types on
* the given class and return a corresponding {@code UntypedAnnotationDescriptor}
* if found.
* <li>Search through all annotations that the given class declares,
* returning an {@code UntypedAnnotationDescriptor} for the first matching
* candidate, if any.
* <li>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.
* </ol>
*
* <p>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 {
}
}
/**
* <em>Untyped</em> 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<Annotation> {
public UntypedAnnotationDescriptor(Class<?> declaringClass, Annotation annotation) {

3
spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java
View File

@ -31,6 +31,9 @@ import java.lang.annotation.Target;
* <p>Typically, {@code @TestExecutionListeners} will be used in conjunction with
* {@link ContextConfiguration @ContextConfiguration}.
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 2.5
* @see TestExecutionListener

9
spring-test/src/main/java/org/springframework/test/context/transaction/AfterTransaction.java
View File

@ -24,16 +24,17 @@ import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
/**
* <p>
* Test annotation to indicate that the annotated {@code public void}
* <p>Test annotation to indicate that the annotated {@code public void}
* method should be executed <em>after</em> a transaction is ended for test
* methods configured to run within a transaction via the
* {@code &#064;Transactional} annotation.
* </p>
*
* <p>
* The {@code &#064;AfterTransaction} methods of superclasses will be
* executed after those of the current class.
* </p>
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 2.5

11
spring-test/src/main/java/org/springframework/test/context/transaction/BeforeTransaction.java
View File

@ -24,17 +24,18 @@ import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
/**
* <p>
* Test annotation to indicate that the annotated {@code public void}
* <p>Test annotation to indicate that the annotated {@code public void}
* method should be executed <em>before</em> a transaction is started for test
* methods configured to run within a transaction via the
* {@code &#064;Transactional} annotation.
* </p>
* <p>
* The {@code &#064;BeforeTransaction} methods of superclasses will be
*
* <p>The {@code &#064;BeforeTransaction} methods of superclasses will be
* executed before those of the current class.
* </p>
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 2.5
* @see org.springframework.transaction.annotation.Transactional

5
spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java
View File

@ -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.
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 2.5
* @see TransactionalTestExecutionListener

3
spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java
View File

@ -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.
*
* <p>As of Spring Framework 4.0, this annotation may be used as a
* <em>meta-annotation</em> to create custom <em>composed annotations</em>.
*
* @author Sam Brannen
* @since 3.2
* @see org.springframework.web.context.WebApplicationContext

1
spring-test/src/test/java/org/springframework/test/context/MetaAnnotationUtilsTests.java
View File

@ -36,6 +36,7 @@ import static org.springframework.test.context.MetaAnnotationUtils.*;
*
* @author Sam Brannen
* @since 4.0
* @see OverriddenMetaAnnotationAttributesTests
*/
public class MetaAnnotationUtilsTests {

1
spring-test/src/test/java/org/springframework/test/context/OverriddenMetaAnnotationAttributesTests.java
View File

@ -34,6 +34,7 @@ import static org.springframework.test.context.MetaAnnotationUtils.*;
*
* @author Sam Brannen
* @since 4.0
* @see MetaAnnotationUtilsTests
*/
public class OverriddenMetaAnnotationAttributesTests {