KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > ComparatorUtils


1 /*
2  * Copyright 2002-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections;
17
18 import java.util.Collection JavaDoc;
19 import java.util.Comparator JavaDoc;
20
21 import org.apache.commons.collections.comparators.BooleanComparator;
22 import org.apache.commons.collections.comparators.ComparableComparator;
23 import org.apache.commons.collections.comparators.ComparatorChain;
24 import org.apache.commons.collections.comparators.NullComparator;
25 import org.apache.commons.collections.comparators.ReverseComparator;
26 import org.apache.commons.collections.comparators.TransformingComparator;
27
28 /**
29  * Provides convenient static utility methods for <Code>Comparator</Code>
30  * objects.
31  * <p>
32  * Most of the functionality in this class can also be found in the
33  * <code>comparators</code> package. This class merely provides a
34  * convenient central place if you have use for more than one class
35  * in the <code>comparators</code> subpackage.
36  *
37  * @since Commons Collections 2.1
38  * @version $Revision: $ $Date: $
39  *
40  * @author Paul Jack
41  * @author Stephen Colebourne
42  */
43 public class ComparatorUtils {
44
45     /**
46      * ComparatorUtils should not normally be instantiated.
47      */
48     public ComparatorUtils() {
49     }
50
51     /**
52      * Comparator for natural sort order.
53      *
54      * @see ComparableComparator#getInstance
55      */
56     public static final Comparator JavaDoc NATURAL_COMPARATOR = ComparableComparator.getInstance();
57
58     /**
59      * Gets a comparator that uses the natural order of the objects.
60      *
61      * @return a comparator which uses natural order
62      */
63     public static Comparator JavaDoc naturalComparator() {
64         return NATURAL_COMPARATOR;
65     }
66
67     /**
68      * Gets a comparator that compares using two {@link Comparator}s.
69      * <p>
70      * The second comparator is used if the first comparator returns equal.
71      *
72      * @param comparator1 the first comparator to use, not null
73      * @param comparator2 the first comparator to use, not null
74      * @return a {@link ComparatorChain} formed from the two comparators
75      * @throws NullPointerException if either comparator is null
76      * @see ComparatorChain
77      */
78     public static Comparator JavaDoc chainedComparator(Comparator JavaDoc comparator1, Comparator JavaDoc comparator2) {
79         return chainedComparator(new Comparator JavaDoc[] {comparator1, comparator2});
80     }
81
82     /**
83      * Gets a comparator that compares using an array of {@link Comparator}s, applied
84      * in sequence until one returns not equal or the array is exhausted.
85      *
86      * @param comparators the comparators to use, not null or empty or containing nulls
87      * @return a {@link ComparatorChain} formed from the input comparators
88      * @throws NullPointerException if comparators array is null or contains a null
89      * @see ComparatorChain
90      */
91     public static Comparator JavaDoc chainedComparator(Comparator JavaDoc[] comparators) {
92         ComparatorChain chain = new ComparatorChain();
93         for (int i = 0; i < comparators.length; i++) {
94             if (comparators[i] == null) {
95                 throw new NullPointerException JavaDoc("Comparator cannot be null");
96             }
97             chain.addComparator(comparators[i]);
98         }
99         return chain;
100     }
101
102     /**
103      * Gets a comparator that compares using a collection of {@link Comparator}s,
104      * applied in (default iterator) sequence until one returns not equal or the
105      * collection is exhausted.
106      *
107      * @param comparators the comparators to use, not null or empty or containing nulls
108      * @return a {@link ComparatorChain} formed from the input comparators
109      * @throws NullPointerException if comparators collection is null or contains a null
110      * @throws ClassCastException if the comparators collection contains the wrong object type
111      * @see ComparatorChain
112      */
113     public static Comparator JavaDoc chainedComparator(Collection JavaDoc comparators) {
114         return chainedComparator(
115             (Comparator JavaDoc[]) comparators.toArray(new Comparator JavaDoc[comparators.size()])
116         );
117     }
118
119     /**
120      * Gets a comparator that reverses the order of the given comparator.
121      *
122      * @param comparator the comparator to reverse
123      * @return a comparator that reverses the order of the input comparator
124      * @see ReverseComparator
125      */
126     public static Comparator JavaDoc reversedComparator(Comparator JavaDoc comparator) {
127         if (comparator == null) {
128             comparator = NATURAL_COMPARATOR;
129         }
130         return new ReverseComparator(comparator);
131     }
132
133     /**
134      * Gets a Comparator that can sort Boolean objects.
135      * <p>
136      * The parameter specifies whether true or false is sorted first.
137      * <p>
138      * The comparator throws NullPointerException if a null value is compared.
139      *
140      * @param trueFirst when <code>true</code>, sort
141      * <code>true</code> {@link Boolean}s before
142      * <code>false</code> {@link Boolean}s.
143      * @return a comparator that sorts booleans
144      */
145     public static Comparator JavaDoc booleanComparator(boolean trueFirst) {
146         return BooleanComparator.getBooleanComparator(trueFirst);
147     }
148     
149     /**
150      * Gets a Comparator that controls the comparison of <code>null</code> values.
151      * <p>
152      * The returned comparator will consider a null value to be less than
153      * any nonnull value, and equal to any other null value. Two nonnull
154      * values will be evaluated with the given comparator.
155      *
156      * @param comparator the comparator that wants to allow nulls
157      * @return a version of that comparator that allows nulls
158      * @see NullComparator
159      */
160     public static Comparator JavaDoc nullLowComparator(Comparator JavaDoc comparator) {
161         if (comparator == null) {
162             comparator = NATURAL_COMPARATOR;
163         }
164         return new NullComparator(comparator, false);
165     }
166
167     /**
168      * Gets a Comparator that controls the comparison of <code>null</code> values.
169      * <p>
170      * The returned comparator will consider a null value to be greater than
171      * any nonnull value, and equal to any other null value. Two nonnull
172      * values will be evaluated with the given comparator.
173      *
174      * @param comparator the comparator that wants to allow nulls
175      * @return a version of that comparator that allows nulls
176      * @see NullComparator
177      */
178     public static Comparator JavaDoc nullHighComparator(Comparator JavaDoc comparator) {
179         if (comparator == null) {
180             comparator = NATURAL_COMPARATOR;
181         }
182         return new NullComparator(comparator, true);
183     }
184
185     /**
186      * Gets a Comparator that passes transformed objects to the given comparator.
187      * <p>
188      * Objects passed to the returned comparator will first be transformed
189      * by the given transformer before they are compared by the given
190      * comparator.
191      *
192      * @param comparator the sort order to use
193      * @param transformer the transformer to use
194      * @return a comparator that transforms its input objects before comparing them
195      * @see TransformingComparator
196      */
197     public static Comparator JavaDoc transformedComparator(Comparator JavaDoc comparator, Transformer transformer) {
198         if (comparator == null) {
199             comparator = NATURAL_COMPARATOR;
200         }
201         return new TransformingComparator(transformer, comparator);
202     }
203
204     /**
205      * Returns the smaller of the given objects according to the given
206      * comparator, returning the second object if the comparator
207      * returns equal.
208      *
209      * @param o1 the first object to compare
210      * @param o2 the second object to compare
211      * @param comparator the sort order to use
212      * @return the smaller of the two objects
213      */
214     public static Object JavaDoc min(Object JavaDoc o1, Object JavaDoc o2, Comparator JavaDoc comparator) {
215         if (comparator == null) {
216             comparator = NATURAL_COMPARATOR;
217         }
218         int c = comparator.compare(o1, o2);
219         return (c < 0) ? o1 : o2;
220     }
221
222     /**
223      * Returns the larger of the given objects according to the given
224      * comparator, returning the second object if the comparator
225      * returns equal.
226      *
227      * @param o1 the first object to compare
228      * @param o2 the second object to compare
229      * @param comparator the sort order to use
230      * @return the larger of the two objects
231      */
232     public static Object JavaDoc max(Object JavaDoc o1, Object JavaDoc o2, Comparator JavaDoc comparator) {
233         if (comparator == null) {
234             comparator = NATURAL_COMPARATOR;
235         }
236         int c = comparator.compare(o1, o2);
237         return (c > 0) ? o1 : o2;
238     }
239     
240 }
241
Popular Tags