    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     * after Rules defined by methods, i.e. the Statements returned by the former will
    032     * be executed around those returned by the latter.
    033     *
    034     * <h3>Usage</h3>
    035     * <p>
    036     * For example, here is a test suite that connects to a server once before
    037     * all the test classes run, and disconnects after they are finished:
    038     * <pre>
    039     * &#064;RunWith(Suite.class)
    040     * &#064;SuiteClasses({A.class, B.class, C.class})
    041     * public class UsesExternalResource {
    042     *     public static Server myServer= new Server();
    043     *
    044     *     &#064;ClassRule
    045     *     public static ExternalResource resource= new ExternalResource() {
    046     *       &#064;Override
    047     *       protected void before() throws Throwable {
    048     *          myServer.connect();
    049     *      }
    050     *
    051     *      &#064;Override
    052     *      protected void after() {
    053     *              myServer.disconnect();
    054     *      }
    055     *   };
    056     * }
    057     * </pre>
    058     * <p>
    059     * and the same using a method
    060     * <pre>
    061     * &#064;RunWith(Suite.class)
    062     * &#064;SuiteClasses({A.class, B.class, C.class})
    063     * public class UsesExternalResource {
    064     *     public static Server myServer= new Server();
    065     *
    066     *     &#064;ClassRule
    067     *     public static ExternalResource getResource() {
    068     *         return new ExternalResource() {
    069     *             &#064;Override
    070     *             protected void before() throws Throwable {
    071     *                 myServer.connect();
    072     *             }
    073     *
    074     *             &#064;Override
    075     *             protected void after() {
    076     *                 myServer.disconnect();
    077     *             }
    078     *         };
    079     *     }
    080     * }
    081     * </pre>
    082     * <p>
    083     * For more information and more examples, see {@link org.junit.rules.TestRule}.
    084     *
    085     * <h3>Ordering</h3>
    086     * <p>
    087     * You can use {@link #order()} if you want to have control over the order in
    088     * which the Rules are applied.
    089     *
    090     * <pre>
    091     * public class ThreeClassRules {
    092     *     &#064;ClassRule(order = 0)
    093     *     public static LoggingRule outer = new LoggingRule("outer rule");
    094     *
    095     *     &#064;ClassRule(order = 1)
    096     *     public static LoggingRule middle = new LoggingRule("middle rule");
    097     *
    098     *     &#064;ClassRule(order = 2)
    099     *     public static LoggingRule inner = new LoggingRule("inner rule");
    100     *
    101     *     // ...
    102     * }
    103     * </pre>
    104     *
    105     * @since 4.9
    106     */
    107    @Retention(RetentionPolicy.RUNTIME)
    108    @Target({ElementType.FIELD, ElementType.METHOD})
    109    public @interface ClassRule {
    110
    111        /**
    112         * Specifies the order in which rules are applied. The rules with a higher value are inner.
    113         *
    114         * @since 4.13
    115         */
    116        int order() default Rule.DEFAULT_ORDER;
    117
    118    }