[Junit-devel] CVS: junit/src/org/junit/runner/manipulation Sortable.java, NONE, 1.1 Filterable.java, NONE, 1.1 Filter.java, NONE, 1.1 NoTestsRemainException.java, NONE, 1.1 Sorter.java, NONE, 1.1 package-info.java, NONE, 1.1

[David S. <ds...@us...>]

Update of /cvsroot/junit/junit/src/org/junit/runner/manipulation
In directory sc8-pr-cvs6.sourceforge.net:/tmp/cvs-serv19867/src/org/junit/runner/manipulation

Added Files:
	Sortable.java Filterable.java Filter.java 
	NoTestsRemainException.java Sorter.java package-info.java 
Log Message:
Created a separate src folder for sources, and adjusted Eclipse classpath and build file accordingly

--- NEW FILE: Sortable.java ---
package org.junit.runner.manipulation;

/**
 * Interface for runners that allow sorting of tests. By sorting tests based on when they last failed, most recently
 * failed first, you can reduce the average time to the first test failing. Test sorting should not be used to
 * cope with order dependencies between tests. Tests that are isolated from each other are less
 * expensive to maintain and can be run individually.
 */
public interface Sortable {

	/**
	 * Sorts the tests using <code>sorter</code>
	 * @param sorter the {@link Sorter} to use for sorting the tests
	 */
	public void sort(Sorter sorter);

}

--- NEW FILE: Filterable.java ---
package org.junit.runner.manipulation;

/**
 * Runners that allow filtering should implement this interface. Implement {@link #filter(Filter)}
 * to remove tests that don't pass the filter.
 */
public interface Filterable {

	/**
	 * Remove tests that don't pass the parameter <code>filter</code>.
	 * @param filter the {@link Filter} to apply
	 * @throws NoTestsRemainException if all tests are filtered out
	 */
	void filter(Filter filter) throws NoTestsRemainException;

}

--- NEW FILE: Filter.java ---
package org.junit.runner.manipulation;

import org.junit.runner.Description;
import org.junit.runner.Request;
import org.junit.runner.Runner;

/**
 * The canonical case of filtering is when you want to run a single test method in a class. Rather
 * than introduce runner API just for that one case, JUnit provides a general filtering mechanism.
 * If you want to filter the tests to be run, extend <code>Filter</code> and apply an instance of
 * your filter to the {@link org.junit.runner.Request} before running it (see 
 * {@link org.junit.runner.JUnitCore#run(Request)}. Alternatively, apply a <code>Filter</code> to 
 * a {@link org.junit.runner.Runner} before running tests (for example, in conjunction with 
 * {@link org.junit.runner.RunWith}.
 */
public abstract class Filter {
	/**
	 * A null <code>Filter</code> that passes all tests through.
	 */
	public static Filter ALL= new Filter() {
		@Override
		public boolean shouldRun(Description description) {
			return true;
		}

		@Override
		public String describe() {
			return "all tests";
		}
	};

	/**
	 * @param description the description of the test to be run
	 * @return <code>true</code> if the test should be run
	 */
	public abstract boolean shouldRun(Description description);

	/**
	 * Invoke with a {@link org.junit.runner.Runner} to cause all tests it intends to run
	 * to first be checked with the filter. Only those that pass the filter will be run.
	 * @param runner the runner to be filtered by the receiver
	 * @throws NoTestsRemainException if the receiver removes all tests
	 */
	public void apply(Runner runner) throws NoTestsRemainException {
		if (runner instanceof Filterable) {
			Filterable filterable= (Filterable)runner;
			filterable.filter(this);
		}
	}

	/**
	 * Returns a textual description of this Filter
	 * @return a textual description of this Filter
	 */
	public abstract String describe();
}

--- NEW FILE: NoTestsRemainException.java ---
package org.junit.runner.manipulation;

/**
 * Thrown when a filter removes all tests from a runner.
 */
public class NoTestsRemainException extends Exception {
	private static final long serialVersionUID = 1L;
}

--- NEW FILE: Sorter.java ---
package org.junit.runner.manipulation;

import java.util.Comparator;

import org.junit.runner.Description;
import org.junit.runner.Runner;

//TODO add an example
/**
 * A <code>Sorter</code> orders tests. In general you will not need
 * to use a <code>Sorter</code> directly. Instead, use {@link org.junit.runner.Request#sortWith(Comparator)}.
 */
public class Sorter implements Comparator<Description> {
	private final Comparator<Description> fComparator;

	/**
	 * Creates a <code>Sorter</code> that uses <code>comparator</code>
	 * to sort tests
	 * @param comparator the {@link Comparator} to use when sorting tests
	 */
	public Sorter(Comparator<Description> comparator) {
		fComparator= comparator;
	}

	/**
	 * Sorts the test in <code>runner</code> using <code>comparator</code>
	 * @param runner
	 */
	public void apply(Runner runner) {
		if (runner instanceof Sortable) {
			Sortable sortable = (Sortable) runner;
			sortable.sort(this);
		}
	}

	/** @inheritDoc */
	public int compare(Description o1, Description o2) {
		return fComparator.compare(o1, o2);
	}
}

--- NEW FILE: package-info.java ---
/**
 * Provides classes to {@link org.junit.runner.manipulation.Filter filter} or {@link org.junit.runner.manipulation.Sorter sort} tests.
 *
 * @since 4.0
 * @see org.junit.runner.Runner
 */
package org.junit.runner.manipulation;