package org.junit.rules;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import org.junit.runner.Description;
import org.junit.runners.model.Statement;

/**
 * The RuleChain rule allows ordering of TestRules. You create a
 * {@code RuleChain} with {@link #outerRule(TestRule)} and subsequent calls of
 * {@link #around(TestRule)}:
 *
 * <pre>
 * public static class UseRuleChain {
 * 	&#064;Rule
 * 	public RuleChain chain= RuleChain
 * 	                       .outerRule(new LoggingRule("outer rule")
 * 	                       .around(new LoggingRule("middle rule")
 * 	                       .around(new LoggingRule("inner rule");
 *
 * 	&#064;Test
 * 	public void example() {
 * 		assertTrue(true);
 *     }
 * }
 * </pre>
 *
 * writes the log
 *
 * <pre>
 * starting outer rule
 * starting middle rule
 * starting inner rule
 * finished inner rule
 * finished middle rule
 * finished outer rule
 * </pre>
 *
 * @since 4.10
 */
public class RuleChain implements TestRule {
    private static final RuleChain EMPTY_CHAIN = new RuleChain(
            Collections.<TestRule>emptyList());

    private List<TestRule> rulesStartingWithInnerMost;

    /**
     * Returns a {@code RuleChain} without a {@link TestRule}. This method may
     * be the starting point of a {@code RuleChain}.
     *
     * @return a {@code RuleChain} without a {@link TestRule}.
     */
    public static RuleChain emptyRuleChain() {
        return EMPTY_CHAIN;
    }

    /**
     * Returns a {@code RuleChain} with a single {@link TestRule}. This method
     * is the usual starting point of a {@code RuleChain}.
     *
     * @param outerRule the outer rule of the {@code RuleChain}.
     * @return a {@code RuleChain} with a single {@link TestRule}.
     */
    public static RuleChain outerRule(TestRule outerRule) {
        return emptyRuleChain().around(outerRule);
    }

    private RuleChain(List<TestRule> rules) {
        this.rulesStartingWithInnerMost = rules;
    }

    /**
     * Create a new {@code RuleChain}, which encloses the given {@link TestRule} with
     * the rules of the current {@code RuleChain}.
     *
     * @param enclosedRule the rule to enclose.
     * @return a new {@code RuleChain}.
     */
    public RuleChain around(TestRule enclosedRule) {
        List<TestRule> rulesOfNewChain = new ArrayList<TestRule>();
        rulesOfNewChain.add(enclosedRule);
        rulesOfNewChain.addAll(rulesStartingWithInnerMost);
        return new RuleChain(rulesOfNewChain);
    }

    /**
     * {@inheritDoc}
     */
    public Statement apply(Statement base, Description description) {
        return new RunRules(base, rulesStartingWithInnerMost, description);
    }
}
@@ -381,23 +381,16 @@
  public 
-static 
 class Us
@@ -402,16 +402,16 @@
 Chain %7B%0A
+
  * %09&#06
@@ -518,24 +518,25 @@
 outer rule%22)
+)
 %0A * %09       
@@ -589,16 +589,17 @@
 e rule%22)
+)
 %0A * %09   
@@ -655,16 +655,17 @@
 r rule%22)
+)
 ;%0A *%0A * 
@@ -897,24 +897,24 @@
 middle rule%0A
-
  * finished 
@@ -930,24 +930,577 @@
 e%0A * %3C/pre%3E%0A
+ * %0A * %7B@code RuleChain%7D cannot be used to define the order of existing rules.%0A * For example in the below snippet the LoggingRule %7B@code middle%7D would be%0A * executed outside as well as inside the %7B@code RuleChain%7D:%0A *%0A * %3Cpre%3E%0A * &#064;Rule%0A * public LoggingRule middle = new LoggingRule(%22middle rule%22);%0A * %0A * &#064;Rule%0A * public RuleChain chain = RuleChain%0A *                          .outerRule(new LoggingRule(%22outer rule%22))%0A *                          .around(middle)%0A *                          .around(new LoggingRule(%22inner rule%22));%0A * %3C/pre%3E%0A
  *%0A * @since

Improve Javadoc of RuleChain (#1319)