001package org.junit.runner.manipulation; 002 003import java.util.ArrayList; 004import java.util.Collection; 005import java.util.Collections; 006import java.util.Comparator; 007import java.util.List; 008 009import org.junit.runner.Description; 010 011/** 012 * A <code>Sorter</code> orders tests. In general you will not need 013 * to use a <code>Sorter</code> directly. Instead, use 014 * {@link org.junit.runner.Request#sortWith(Comparator)}. 015 * 016 * @since 4.0 017 */ 018public class Sorter extends Ordering implements Comparator<Description> { 019 /** 020 * NULL is a <code>Sorter</code> that leaves elements in an undefined order 021 */ 022 public static final Sorter NULL = new Sorter(new Comparator<Description>() { 023 public int compare(Description o1, Description o2) { 024 return 0; 025 } 026 }); 027 028 private final Comparator<Description> comparator; 029 030 /** 031 * Creates a <code>Sorter</code> that uses <code>comparator</code> 032 * to sort tests 033 * 034 * @param comparator the {@link Comparator} to use when sorting tests 035 * @since 4.0 036 */ 037 public Sorter(Comparator<Description> comparator) { 038 this.comparator = comparator; 039 } 040 041 /** 042 * Sorts the tests in <code>target</code> using <code>comparator</code>. 043 * 044 * @since 4.0 045 */ 046 @Override 047 public void apply(Object target) { 048 /* 049 * Note that all runners that are Orderable are also Sortable (because 050 * Orderable extends Sortable). Sorting is more efficient than ordering, 051 * so we override the parent behavior so we sort instead. 052 */ 053 if (target instanceof Sortable) { 054 Sortable sortable = (Sortable) target; 055 sortable.sort(this); 056 } 057 } 058 059 public int compare(Description o1, Description o2) { 060 return comparator.compare(o1, o2); 061 } 062 063 /** 064 * {@inheritDoc} 065 * 066 * @since 4.13 067 */ 068 @Override 069 protected final List<Description> orderItems(Collection<Description> descriptions) { 070 /* 071 * In practice, we will never get here--Sorters do their work in the 072 * compare() method--but the Liskov substitution principle demands that 073 * we obey the general contract of Orderable. Luckily, it's trivial to 074 * implement. 075 */ 076 List<Description> sorted = new ArrayList<Description>(descriptions); 077 Collections.sort(sorted, this); // Note: it would be incorrect to pass in "comparator" 078 return sorted; 079 } 080 081 /** 082 * {@inheritDoc} 083 * 084 * @since 4.13 085 */ 086 @Override 087 boolean validateOrderingIsCorrect() { 088 return false; 089 } 090}