KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * Copyright 2001-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 Comparator that will compare nulls to be either lower or higher than
23  * other objects.
24  *
25  * @since Commons Collections 2.0
26  * @version $Revision: 1.13 $ $Date: 2004/05/15 13:24:11 $
27  *
28  * @author Michael A. Smith
29  */
30 public class NullComparator implements Comparator JavaDoc, Serializable JavaDoc {
31
32     /** Serialization version. */
33     private static final long serialVersionUID = -5820772575483504339L;
34
35     /**
36      * The comparator to use when comparing two non-<code>null</code> objects.
37      **/
38     private Comparator JavaDoc nonNullComparator;
39
40     /**
41      * Specifies whether a <code>null</code> are compared as higher than
42      * non-<code>null</code> objects.
43      **/
44     private boolean nullsAreHigh;
45
46     //-----------------------------------------------------------------------
47 /**
48      * Construct an instance that sorts <code>null</code> higher than any
49      * non-<code>null</code> object it is compared with. When comparing two
50      * non-<code>null</code> objects, the {@link ComparableComparator} is
51      * used.
52      **/
53     public NullComparator() {
54         this(ComparableComparator.getInstance(), true);
55     }
56
57     /**
58      * Construct an instance that sorts <code>null</code> higher than any
59      * non-<code>null</code> object it is compared with. When comparing two
60      * non-<code>null</code> objects, the specified {@link Comparator} is
61      * used.
62      *
63      * @param nonNullComparator the comparator to use when comparing two
64      * non-<code>null</code> objects. This argument cannot be
65      * <code>null</code>
66      *
67      * @exception NullPointerException if <code>nonNullComparator</code> is
68      * <code>null</code>
69      **/
70     public NullComparator(Comparator JavaDoc nonNullComparator) {
71         this(nonNullComparator, true);
72     }
73
74     /**
75      * Construct an instance that sorts <code>null</code> higher or lower than
76      * any non-<code>null</code> object it is compared with. When comparing
77      * two non-<code>null</code> objects, the {@link ComparableComparator} is
78      * used.
79      *
80      * @param nullsAreHigh a <code>true</code> value indicates that
81      * <code>null</code> should be compared as higher than a
82      * non-<code>null</code> object. A <code>false</code> value indicates
83      * that <code>null</code> should be compared as lower than a
84      * non-<code>null</code> object.
85      **/
86     public NullComparator(boolean nullsAreHigh) {
87         this(ComparableComparator.getInstance(), nullsAreHigh);
88     }
89     
90     /**
91      * Construct an instance that sorts <code>null</code> higher or lower than
92      * any non-<code>null</code> object it is compared with. When comparing
93      * two non-<code>null</code> objects, the specified {@link Comparator} is
94      * used.
95      *
96      * @param nonNullComparator the comparator to use when comparing two
97      * non-<code>null</code> objects. This argument cannot be
98      * <code>null</code>
99      *
100      * @param nullsAreHigh a <code>true</code> value indicates that
101      * <code>null</code> should be compared as higher than a
102      * non-<code>null</code> object. A <code>false</code> value indicates
103      * that <code>null</code> should be compared as lower than a
104      * non-<code>null</code> object.
105      *
106      * @exception NullPointerException if <code>nonNullComparator</code> is
107      * <code>null</code>
108      **/
109     public NullComparator(Comparator JavaDoc nonNullComparator, boolean nullsAreHigh) {
110         this.nonNullComparator = nonNullComparator;
111         this.nullsAreHigh = nullsAreHigh;
112         
113         if(nonNullComparator == null) {
114             throw new NullPointerException JavaDoc("null nonNullComparator");
115         }
116     }
117
118     //-----------------------------------------------------------------------
119 /**
120      * Perform a comparison between two objects. If both objects are
121      * <code>null</code>, a <code>0</code> value is returned. If one object
122      * is <code>null</code> and the other is not, the result is determined on
123      * whether the Comparator was constructed to have nulls as higher or lower
124      * than other objects. If neither object is <code>null</code>, an
125      * underlying comparator specified in the constructor (or the default) is
126      * used to compare the non-<code>null</code> objects.
127      *
128      * @param o1 the first object to compare
129      * @param o2 the object to compare it to.
130      * @return <code>-1</code> if <code>o1</code> is "lower" than (less than,
131      * before, etc.) <code>o2</code>; <code>1</code> if <code>o1</code> is
132      * "higher" than (greater than, after, etc.) <code>o2</code>; or
133      * <code>0</code> if <code>o1</code> and <code>o2</code> are equal.
134      **/
135     public int compare(Object JavaDoc o1, Object JavaDoc o2) {
136         if(o1 == o2) { return 0; }
137         if(o1 == null) { return (this.nullsAreHigh ? 1 : -1); }
138         if(o2 == null) { return (this.nullsAreHigh ? -1 : 1); }
139         return this.nonNullComparator.compare(o1, o2);
140     }
141
142     //-----------------------------------------------------------------------
143 /**
144      * Implement a hash code for this comparator that is consistent with
145      * {@link #equals(Object)}.
146      *
147      * @return a hash code for this comparator.
148      **/
149     public int hashCode() {
150         return (nullsAreHigh ? -1 : 1) * nonNullComparator.hashCode();
151     }
152
153     /**
154      * Determines whether the specified object represents a comparator that is
155      * equal to this comparator.
156      *
157      * @param obj the object to compare this comparator with.
158      *
159      * @return <code>true</code> if the specified object is a NullComparator
160      * with equivalent <code>null</code> comparison behavior
161      * (i.e. <code>null</code> high or low) and with equivalent underlying
162      * non-<code>null</code> object comparators.
163      **/
164     public boolean equals(Object JavaDoc obj) {
165         if(obj == null) { return false; }
166         if(obj == this) { return true; }
167         if(!obj.getClass().equals(this.getClass())) { return false; }
168
169         NullComparator other = (NullComparator)obj;
170     
171         return ((this.nullsAreHigh == other.nullsAreHigh) &&
172                 (this.nonNullComparator.equals(other.nonNullComparator)));
173     }
174
175 }
176
Popular Tags