KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > comparators > BooleanComparator


1 /*
2  * Copyright 2003-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.comparators;
17
18 import java.io.Serializable JavaDoc;
19 import java.util.Comparator JavaDoc;
20
21 /**
22  * A {@link Comparator} for {@link Boolean} objects that can sort either
23  * true or false first.
24  * <p>
25  * @see #getTrueFirstComparator()
26  * @see #getFalseFirstComparator()
27  * @see #getBooleanComparator(boolean)
28  *
29  * @since Commons Collections 3.0
30  * @version $Revision: 1.14 $ $Date: 2004/05/16 11:56:47 $
31  *
32  * @author Rodney Waldhoff
33  */
34 public final class BooleanComparator implements Comparator JavaDoc, Serializable JavaDoc {
35
36     /** Serialization version. */
37     private static final long serialVersionUID = 1830042991606340609L;
38
39     /** Constant "true first" reference. */
40     private static final BooleanComparator TRUE_FIRST = new BooleanComparator(true);
41
42     /** Constant "false first" reference. */
43     private static final BooleanComparator FALSE_FIRST = new BooleanComparator(false);
44
45     /** <code>true</code> iff <code>true</code> values sort before <code>false</code> values. */
46     private boolean trueFirst = false;
47
48     //-----------------------------------------------------------------------
49 /**
50      * Returns a BooleanComparator instance that sorts
51      * <code>true</code> values before <code>false</code> values.
52      * <p />
53      * Clients are encouraged to use the value returned from
54      * this method instead of constructing a new instance
55      * to reduce allocation and garbage collection overhead when
56      * multiple BooleanComparators may be used in the same
57      * virtual machine.
58      *
59      * @return the true first singleton BooleanComparator
60      */
61     public static BooleanComparator getTrueFirstComparator() {
62         return TRUE_FIRST;
63     }
64     
65     /**
66      * Returns a BooleanComparator instance that sorts
67      * <code>false</code> values before <code>true</code> values.
68      * <p />
69      * Clients are encouraged to use the value returned from
70      * this method instead of constructing a new instance
71      * to reduce allocation and garbage collection overhead when
72      * multiple BooleanComparators may be used in the same
73      * virtual machine.
74      *
75      * @return the false first singleton BooleanComparator
76      */
77     public static BooleanComparator getFalseFirstComparator() {
78         return FALSE_FIRST;
79     }
80         
81     /**
82      * Returns a BooleanComparator instance that sorts
83      * <code><i>trueFirst</i></code> values before
84      * <code>&#x21;<i>trueFirst</i></code> values.
85      * <p />
86      * Clients are encouraged to use the value returned from
87      * this method instead of constructing a new instance
88      * to reduce allocation and garbage collection overhead when
89      * multiple BooleanComparators may be used in the same
90      * virtual machine.
91      *
92      * @param trueFirst when <code>true</code>, sort
93      * <code>true</code> <code>Boolean</code>s before <code>false</code>
94      * @return a singleton BooleanComparator instance
95      */
96     public static BooleanComparator getBooleanComparator(boolean trueFirst) {
97         return trueFirst ? TRUE_FIRST : FALSE_FIRST;
98     }
99
100     //-----------------------------------------------------------------------
101 /**
102      * Creates a <code>BooleanComparator</code> that sorts
103      * <code>false</code> values before <code>true</code> values.
104      * <p>
105      * Equivalent to {@link #BooleanComparator(boolean) BooleanComparator(false)}.
106      * <p>
107      * Please use the static factory instead whenever possible.
108      */
109     public BooleanComparator() {
110         this(false);
111     }
112
113     /**
114      * Creates a <code>BooleanComparator</code> that sorts
115      * <code><i>trueFirst</i></code> values before
116      * <code>&#x21;<i>trueFirst</i></code> values.
117      * <p>
118      * Please use the static factories instead whenever possible.
119      *
120      * @param trueFirst when <code>true</code>, sort
121      * <code>true</code> boolean values before <code>false</code>
122      */
123     public BooleanComparator(boolean trueFirst) {
124         this.trueFirst = trueFirst;
125     }
126
127     //-----------------------------------------------------------------------
128 /**
129      * Compares two arbitrary Objects.
130      * When both arguments are <code>Boolean</code>, this method is equivalent to
131      * {@link #compare(Boolean,Boolean) compare((Boolean)<i>obj1</i>,(Boolean)<i>obj2</i>)}.
132      * When either argument is not a <code>Boolean</code>, this methods throws
133      * a {@link ClassCastException}.
134      *
135      * @param obj1 the first object to compare
136      * @param obj2 the second object to compare
137      * @return negative if obj1 is less, positive if greater, zero if equal
138      * @throws ClassCastException when either argument is not <code>Boolean</code>
139      */
140     public int compare(Object JavaDoc obj1, Object JavaDoc obj2) {
141         return compare((Boolean JavaDoc)obj1, (Boolean JavaDoc)obj2);
142     }
143     
144     /**
145      * Compares two non-<code>null</code> <code>Boolean</code> objects
146      * according to the value of {@link #trueFirst}.
147      *
148      * @param b1 the first boolean to compare
149      * @param b2 the second boolean to compare
150      * @return negative if obj1 is less, positive if greater, zero if equal
151      * @throws NullPointerException when either argument <code>null</code>
152      */
153     public int compare(Boolean JavaDoc b1, Boolean JavaDoc b2) {
154         boolean v1 = b1.booleanValue();
155         boolean v2 = b2.booleanValue();
156
157         return (v1 ^ v2) ? ( (v1 ^ trueFirst) ? 1 : -1 ) : 0;
158     }
159
160     //-----------------------------------------------------------------------
161 /**
162      * Implement a hash code for this comparator that is consistent with
163      * {@link #equals(Object) equals}.
164      *
165      * @return a hash code for this comparator.
166      */
167     public int hashCode() {
168         int hash = "BooleanComparator".hashCode();
169         return trueFirst ? -1 * hash : hash;
170     }
171
172     /**
173      * Returns <code>true</code> iff <i>that</i> Object is
174      * is a {@link Comparator} whose ordering is known to be
175      * equivalent to mine.
176      * <p>
177      * This implementation returns <code>true</code>
178      * iff <code><i>that</i></code> is a {@link BooleanComparator}
179      * whose {@link #trueFirst} value is equal to mine.
180      *
181      * @param object the object to compare to
182      * @return true if equal
183      */
184     public boolean equals(Object JavaDoc object) {
185         return (this == object) ||
186                ((object instanceof BooleanComparator) &&
187                 (this.trueFirst == ((BooleanComparator)object).trueFirst));
188     }
189
190     //-----------------------------------------------------------------------
191 /**
192      * Returns <code>true</code> iff
193      * I sort <code>true</code> values before
194      * <code>false</code> values. In other words,
195      * returns <code>true</code> iff
196      * {@link #compare(Boolean,Boolean) compare(Boolean.FALSE,Boolean.TRUE)}
197      * returns a positive value.
198      *
199      * @return the trueFirst flag
200      */
201     public boolean sortsTrueFirst() {
202         return trueFirst;
203     }
204
205 }
206
Popular Tags