Upgrade to JUnit 4.12

The license has changed from Common Public License v1.0 to
Eclipse Public License v1.0.

This will not compile as it is because it is intended to be
built against Hamcrest 1.3 or later but it is being built
against Hamcrest 1.1.

A follow on patch will fix the compilation errors so that it
builds against Hamcrest 1.1. That allows Hamcrest to be upgraded
separately. The patch can be reverted once Hamcrest has been
upgraded.

There are also some Android specific issues that will also be
fixed in follow on patches.

Bug: 33613916
Test: make checkbuild
Change-Id: Ic2c983a030399e3ace1a14927cb143fbd8307b4f

1 files changed, 58 insertions, 31 deletions

diff --git a/src/main/java/org/junit/ClassRule.java b/src/main/java/org/junit/ClassRule.java
index 97a111f..02c40a7 100644
--- a/src/main/java/org/junit/ClassRule.java
+++ b/src/main/java/org/junit/ClassRule.java
@@ -6,55 +6,82 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotates static fields that contain rules. Such a field must be public,
- * static, and a subtype of {@link org.junit.rules.TestRule}.  
- * The {@link org.junit.runners.model.Statement} passed 
- * to the {@link org.junit.rules.TestRule} will run any {@link BeforeClass} methods, 
+ * Annotates static fields that reference rules or methods that return them. A field must be public,
+ * static, and a subtype of {@link org.junit.rules.TestRule}.  A method must be public static, and return
+ * a subtype of {@link org.junit.rules.TestRule}.
+ * <p>
+ * The {@link org.junit.runners.model.Statement} passed
+ * to the {@link org.junit.rules.TestRule} will run any {@link BeforeClass} methods,
  * then the entire body of the test class (all contained methods, if it is
- * a standard JUnit test class, or all contained classes, if it is a 
+ * a standard JUnit test class, or all contained classes, if it is a
  * {@link org.junit.runners.Suite}), and finally any {@link AfterClass} methods.
- * 
+ * <p>
  * The statement passed to the {@link org.junit.rules.TestRule} will never throw an exception,
  * and throwing an exception from the {@link org.junit.rules.TestRule} will result in undefined
- * behavior.  This means that some {@link org.junit.rules.TestRule}s, such as 
- * {@link org.junit.rules.ErrorCollector}, 
- * {@link org.junit.rules.ExpectedException}, 
+ * behavior.  This means that some {@link org.junit.rules.TestRule}s, such as
+ * {@link org.junit.rules.ErrorCollector},
+ * {@link org.junit.rules.ExpectedException},
  * and {@link org.junit.rules.Timeout},
  * have undefined behavior when used as {@link ClassRule}s.
- * 
+ * <p>
  * If there are multiple
  * annotated {@link ClassRule}s on a class, they will be applied in an order
  * that depends on your JVM's implementation of the reflection API, which is
- * undefined, in general.
- *
+ * undefined, in general. However, Rules defined by fields will always be applied
+ * before Rules defined by methods.
+ * <p>
  * For example, here is a test suite that connects to a server once before
  * all the test classes run, and disconnects after they are finished:
- * 
  * <pre>
- * 
  * &#064;RunWith(Suite.class)
  * &#064;SuiteClasses({A.class, B.class, C.class})
  * public class UsesExternalResource {
- * 	public static Server myServer= new Server();
- * 
- * 	&#064;ClassRule
- * 	public static ExternalResource resource= new ExternalResource() {
- * 		&#064;Override
- * 		protected void before() throws Throwable {
- * 			myServer.connect();
- * 		};
- * 
- * 		&#064;Override
- * 		protected void after() {
- * 			myServer.disconnect();
- * 		};
- * 	};
+ *     public static Server myServer= new Server();
+ *
+ *     &#064;ClassRule
+ *     public static ExternalResource resource= new ExternalResource() {
+ *       &#064;Override
+ *       protected void before() throws Throwable {
+ *          myServer.connect();
+ *      }
+ *
+ *      &#064;Override
+ *      protected void after() {
+ * 	        myServer.disconnect();
+ *      }
+ *   };
+ * }
+ * </pre>
+ * <p>
+ * and the same using a method
+ * <pre>
+ * &#064;RunWith(Suite.class)
+ * &#064;SuiteClasses({A.class, B.class, C.class})
+ * public class UsesExternalResource {
+ *     public static Server myServer= new Server();
+ *
+ *     &#064;ClassRule
+ *     public static ExternalResource getResource() {
+ *         return new ExternalResource() {
+ *             &#064;Override
+ *             protected void before() throws Throwable {
+ *                 myServer.connect();
+ *             }
+ *
+ *             &#064;Override
+ *             protected void after() {
+ *                 myServer.disconnect();
+ *             }
+ *         };
+ *     }
  * }
  * </pre>
- * 
- * For more information and more examples, see {@link org.junit.rules.TestRule}. 
+ * <p>
+ * For more information and more examples, see {@link org.junit.rules.TestRule}.
+ *
+ * @since 4.9
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.FIELD})
+@Target({ElementType.FIELD, ElementType.METHOD})
 public @interface ClassRule {
 }