View Javadoc

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 net.sf.collections15.comparators;
17  
18  import java.io.Serializable;
19  import java.util.Comparator;
20  
21  /***
22   * A {@link Comparator} that compares {@link Comparable} objects.
23   * <p/>
24   * This Comparator is useful, for example, for enforcing the natural order in
25   * custom implementations of <code>SortedSet</code> and <code>SortedMap</code>.
26   *
27   * @author Henri Yandell
28   * @author Chris Lambrou (port to Java 5.0)
29   * @see java.util.Collections#reverseOrder()
30   * @since Collections15 1.0
31   */
32  public class ComparableComparator <E extends Comparable>
33          implements Comparator<E>, Serializable
34  {
35  
36      static final long serialVersionUID = 4818349402198823211L;
37  
38      /***
39       * Gets a ComparableComparator instance.
40       * <p/>
41       * Developers are encouraged to reuse the comparator returned from this
42       * method instead of constructing a new instance to reduce allocation and GC
43       * overhead when multiple comparable comparators may be used in the same
44       * VM.
45       *
46       * @return A <code>ComparableComparator</code> apropriate to the generic
47       *         type.
48       */
49      public static <T extends Comparable> ComparableComparator<T> getInstance()
50      {
51          return new ComparableComparator<T>();
52      }
53  
54      /***
55       * Constructs a new instance. The protected access modifier forces use of
56       * the {@link #getInstance()} method.
57       */
58      protected ComparableComparator()
59      {
60      }
61  
62      /***
63       * Compare the two {@link Comparable} arguments. This method is equivalent
64       * to: <code>((Comparable)obj1).compareTo(obj2)</code>
65       *
66       * @param obj1 The first object to compare.
67       * @param obj2 The second object to compare.
68       *
69       * @return A negative value if <code>obj1</code> is less than
70       *         </code>obj2</code>, a positive value if <code>obj1</code> is
71       *         greater than <code>obj2</code> or zero if <code>obj1</code> and
72       *         <code>obj2</code> are equal.
73       *
74       * @throws NullPointerException Thrown if <code>obj1</code> is
75       *                              <code>null</code>, or when <code>((Comparable)obj1).compareTo(obj2)</code>
76       *                              throws a <code>NullPointerException</code>.
77       */
78      public int compare(E obj1, E obj2)
79      {
80          return obj1.compareTo(obj2);
81      }
82  
83      /***
84       * Implement a hash code for this comparator that is consistent with {@link
85       * #equals(Object) equals}.
86       *
87       * @return A hash code for this comparator.
88       *
89       * @since Collections15 1.0
90       */
91      public int hashCode()
92      {
93          return "ComparableComparator".hashCode(); //@todo: This is stupid!
94      }
95  
96      /***
97       * Determines whether or not a specified object is equal to this
98       * <code>ComparableComparator</code> instance.
99       * <p/>
100      * This implementation returns <code>true</code> only if
101      * <code><i>object</i>.{@link Object#getClass() getClass()}</code> equals
102      * <code>this.getClass()</code>. Subclasses may want to override this
103      * behavior to remain consistent with the {@link java.util.Comparator#equals(Object)}
104      * contract.
105      *
106      * @param object The object to compare to.
107      *
108      * @return true If the specified object is equal to this instance.
109      *
110      * @since Collections15 1.0
111      */
112     public boolean equals(Object object)
113     {
114         return (this == object) ||
115                 ((null != object) && (object.getClass().equals(this.getClass())));
116     }
117 
118 }