001    package org.junit.runner.manipulation;
002    
003    import java.util.ArrayList;
004    import java.util.Collection;
005    import java.util.Collections;
006    import java.util.Comparator;
007    import java.util.List;
008    
009    import 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     */
018    public 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    }