001    package org.junit;
002    
003    import java.lang.annotation.ElementType;
004    import java.lang.annotation.Retention;
005    import java.lang.annotation.RetentionPolicy;
006    import java.lang.annotation.Target;
007    
008    /**
009     * Annotates static fields that reference rules or methods that return them. A field must be public,
010     * static, and a subtype of {@link org.junit.rules.TestRule}.  A method must be public static, and return
011     * a subtype of {@link org.junit.rules.TestRule}.
012     * <p>
013     * The {@link org.junit.runners.model.Statement} passed
014     * to the {@link org.junit.rules.TestRule} will run any {@link BeforeClass} methods,
015     * then the entire body of the test class (all contained methods, if it is
016     * a standard JUnit test class, or all contained classes, if it is a
017     * {@link org.junit.runners.Suite}), and finally any {@link AfterClass} methods.
018     * <p>
019     * The statement passed to the {@link org.junit.rules.TestRule} will never throw an exception,
020     * and throwing an exception from the {@link org.junit.rules.TestRule} will result in undefined
021     * behavior.  This means that some {@link org.junit.rules.TestRule}s, such as
022     * {@link org.junit.rules.ErrorCollector},
023     * {@link org.junit.rules.ExpectedException},
024     * and {@link org.junit.rules.Timeout},
025     * have undefined behavior when used as {@link ClassRule}s.
026     * <p>
027     * If there are multiple
028     * annotated {@link ClassRule}s on a class, they will be applied in an order
029     * that depends on your JVM's implementation of the reflection API, which is
030     * undefined, in general. However, Rules defined by fields will always be applied
031     * before Rules defined by methods.
032     * <p>
033     * For example, here is a test suite that connects to a server once before
034     * all the test classes run, and disconnects after they are finished:
035     * <pre>
036     * &#064;RunWith(Suite.class)
037     * &#064;SuiteClasses({A.class, B.class, C.class})
038     * public class UsesExternalResource {
039     *     public static Server myServer= new Server();
040     *
041     *     &#064;ClassRule
042     *     public static ExternalResource resource= new ExternalResource() {
043     *       &#064;Override
044     *       protected void before() throws Throwable {
045     *          myServer.connect();
046     *      }
047     *
048     *      &#064;Override
049     *      protected void after() {
050     *              myServer.disconnect();
051     *      }
052     *   };
053     * }
054     * </pre>
055     * <p>
056     * and the same using a method
057     * <pre>
058     * &#064;RunWith(Suite.class)
059     * &#064;SuiteClasses({A.class, B.class, C.class})
060     * public class UsesExternalResource {
061     *     public static Server myServer= new Server();
062     *
063     *     &#064;ClassRule
064     *     public static ExternalResource getResource() {
065     *         return new ExternalResource() {
066     *             &#064;Override
067     *             protected void before() throws Throwable {
068     *                 myServer.connect();
069     *             }
070     *
071     *             &#064;Override
072     *             protected void after() {
073     *                 myServer.disconnect();
074     *             }
075     *         };
076     *     }
077     * }
078     * </pre>
079     * <p>
080     * For more information and more examples, see {@link org.junit.rules.TestRule}.
081     *
082     * @since 4.9
083     */
084    @Retention(RetentionPolicy.RUNTIME)
085    @Target({ElementType.FIELD, ElementType.METHOD})
086    public @interface ClassRule {
087    }