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 fields that reference rules or methods that return a rule. A field must be public, not
010     * static, and a subtype of {@link org.junit.rules.TestRule} (preferred) or
011     * {@link org.junit.rules.MethodRule}. A method must be public, not static,
012     * and must return a subtype of {@link org.junit.rules.TestRule} (preferred) or
013     * {@link org.junit.rules.MethodRule}.
014     * <p>
015     * The {@link org.junit.runners.model.Statement} passed
016     * to the {@link org.junit.rules.TestRule} will run any {@link Before} methods,
017     * then the {@link Test} method, and finally any {@link After} methods,
018     * throwing an exception if any of these fail.  If there are multiple
019     * annotated {@link Rule}s on a class, they will be applied in order of methods first, then fields.
020     * However, if there are multiple fields (or methods) they will be applied in an order
021     * that depends on your JVM's implementation of the reflection API, which is
022     * undefined, in general. Rules defined by fields will always be applied
023     * after Rules defined by methods, i.e. the Statements returned by the former will
024     * be executed around those returned by the latter.
025     *
026     * <h3>Usage</h3>
027     * <p>
028     * For example, here is a test class that creates a temporary folder before
029     * each test method, and deletes it after each:
030     * <pre>
031     * public static class HasTempFolder {
032     *     &#064;Rule
033     *     public TemporaryFolder folder= new TemporaryFolder();
034     *
035     *     &#064;Test
036     *     public void testUsingTempFolder() throws IOException {
037     *         File createdFile= folder.newFile(&quot;myfile.txt&quot;);
038     *         File createdFolder= folder.newFolder(&quot;subfolder&quot;);
039     *         // ...
040     *     }
041     * }
042     * </pre>
043     * <p>
044     * And the same using a method.
045     * <pre>
046     * public static class HasTempFolder {
047     *     private TemporaryFolder folder= new TemporaryFolder();
048     *
049     *     &#064;Rule
050     *     public TemporaryFolder getFolder() {
051     *         return folder;
052     *     }
053     *
054     *     &#064;Test
055     *     public void testUsingTempFolder() throws IOException {
056     *         File createdFile= folder.newFile(&quot;myfile.txt&quot;);
057     *         File createdFolder= folder.newFolder(&quot;subfolder&quot;);
058     *         // ...
059     *     }
060     * }
061     * </pre>
062     * <p>
063     * For more information and more examples, see
064     * {@link org.junit.rules.TestRule}.
065     *
066     * <h3>Ordering</h3>
067     * <p>
068     * You can use {@link #order()} if you want to have control over the order in
069     * which the Rules are applied.
070     *
071     * <pre>
072     * public class ThreeRules {
073     *     &#064;Rule(order = 0)
074     *     public LoggingRule outer = new LoggingRule("outer rule");
075     *
076     *     &#064;Rule(order = 1)
077     *     public LoggingRule middle = new LoggingRule("middle rule");
078     *
079     *     &#064;Rule(order = 2)
080     *     public LoggingRule inner = new LoggingRule("inner rule");
081     *
082     *     // ...
083     * }
084     * </pre>
085     *
086     * @since 4.7
087     */
088    @Retention(RetentionPolicy.RUNTIME)
089    @Target({ElementType.FIELD, ElementType.METHOD})
090    public @interface Rule {
091    
092        int DEFAULT_ORDER = -1;
093    
094        /**
095         * Specifies the order in which rules are applied. The rules with a higher value are inner.
096         *
097         * @since 4.13
098         */
099        int order() default DEFAULT_ORDER;
100    
101    }