001package org.junit;
002
003import java.lang.annotation.ElementType;
004import java.lang.annotation.Retention;
005import java.lang.annotation.RetentionPolicy;
006import 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}.<p>
014 *
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 fields first, then methods.
020 * However, if there are mutliple 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 * before Rules defined by methods.<p>
024 *
025 * For example, here is a test class that creates a temporary folder before
026 * each test method, and deletes it after each:
027 *
028 * <pre>
029 * public static class HasTempFolder {
030 *     &#064;Rule
031 *     public TemporaryFolder folder= new TemporaryFolder();
032 *
033 *     &#064;Test
034 *     public void testUsingTempFolder() throws IOException {
035 *         File createdFile= folder.newFile(&quot;myfile.txt&quot;);
036 *         File createdFolder= folder.newFolder(&quot;subfolder&quot;);
037 *         // ...
038 *     }
039 * }
040 * </pre>
041 *
042 * And the same using a method.
043 *
044 * <pre>
045 * public static class HasTempFolder {
046 *     private TemporaryFolder folder= new TemporaryFolder();
047 *
048 *     &#064;Rule
049 *     public TemporaryFolder getFolder() {
050 *         return folder;
051 *     }
052 *
053 *     &#064;Test
054 *     public void testUsingTempFolder() throws IOException {
055 *         File createdFile= folder.newFile(&quot;myfile.txt&quot;);
056 *         File createdFolder= folder.newFolder(&quot;subfolder&quot;);
057 *         // ...
058 *     }
059 * }
060 * </pre>
061 *
062 * For more information and more examples, see
063 * {@link org.junit.rules.TestRule}.
064 *
065 * @since 4.7
066 */
067@Retention(RetentionPolicy.RUNTIME)
068@Target({ElementType.FIELD, ElementType.METHOD})
069public @interface Rule {
070
071}