1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.collections4.comparators; 18 19 import java.io.Serializable; 20 import java.util.Comparator; 21 22 /** 23 * A {@link Comparator Comparator} that compares {@link Comparable Comparable} 24 * objects. 25 * <p> 26 * This Comparator is useful, for example, for enforcing the natural order in 27 * custom implementations of {@link java.util.SortedSet SortedSet} and 28 * {@link java.util.SortedMap SortedMap}. 29 * </p> 30 * <p> 31 * Note: In the 2.0 and 2.1 releases of Commons Collections, this class would 32 * throw a {@link ClassCastException} if either of the arguments to 33 * {@link #compare(Comparable, Comparable)} compare} were {@code null}, not 34 * {@link Comparable Comparable}, or for which 35 * {@link Comparable#compareTo(Object) compareTo} gave inconsistent results. 36 * This is no longer the case. See {@link #compare(Comparable, Comparable)} compare} for 37 * details. 38 * </p> 39 * 40 * @param <E> the type of objects compared by this comparator 41 * 42 * @since 2.0 43 * @see java.util.Collections#reverseOrder() 44 */ 45 public class ComparableComparator<E extends Comparable<? super E>> implements Comparator<E>, Serializable { 46 47 /** Serialization version. */ 48 private static final long serialVersionUID = -291439688585137865L; 49 50 /** The singleton instance. */ 51 @SuppressWarnings("rawtypes") 52 public static final ComparableComparator INSTANCE = new ComparableComparator(); 53 54 /** 55 * Gets the singleton instance of a ComparableComparator. 56 * <p> 57 * Developers are encouraged to use the comparator returned from this method 58 * instead of constructing a new instance to reduce allocation and GC overhead 59 * when multiple comparable comparators may be used in the same VM. 60 * 61 * @param <E> the element type 62 * @return the singleton ComparableComparator 63 * @since 4.0 64 */ 65 public static <E extends Comparable<? super E>> ComparableComparator<E> comparableComparator() { 66 return INSTANCE; 67 } 68 69 /** 70 * Constructor whose use should be avoided. 71 * <p> 72 * Please use the {@link #comparableComparator()} method whenever possible. 73 */ 74 public ComparableComparator() { 75 } 76 77 /** 78 * Compare the two {@link Comparable Comparable} arguments. 79 * This method is equivalent to: 80 * <pre>((Comparable)obj1).compareTo(obj2)</pre> 81 * 82 * @param obj1 the first object to compare 83 * @param obj2 the second object to compare 84 * @return negative if obj1 is less, positive if greater, zero if equal 85 * @throws NullPointerException if <i>obj1</i> is {@code null}, 86 * or when {@code ((Comparable)obj1).compareTo(obj2)} does 87 * @throws ClassCastException if <i>obj1</i> is not a {@code Comparable}, 88 * or when {@code ((Comparable)obj1).compareTo(obj2)} does 89 */ 90 @Override 91 public int compare(final E obj1, final E obj2) { 92 return obj1.compareTo(obj2); 93 } 94 95 /** 96 * Returns {@code true} iff <i>that</i> Object is a {@link Comparator Comparator} 97 * whose ordering is known to be equivalent to mine. 98 * <p> 99 * This implementation returns {@code true} iff 100 * {@code <i>object</i>.{@link Object#getClass() getClass()}} equals 101 * {@code this.getClass()}. Subclasses may want to override this behavior to remain 102 * consistent with the {@link Comparator#equals(Object)} contract. 103 * 104 * @param object the object to compare with 105 * @return {@code true} if equal 106 * @since 3.0 107 */ 108 @Override 109 public boolean equals(final Object object) { 110 return this == object || 111 null != object && object.getClass().equals(this.getClass()); 112 } 113 114 /** 115 * Implement a hash code for this comparator that is consistent with 116 * {@link #equals(Object) equals}. 117 * 118 * @return a hash code for this comparator. 119 * @since 3.0 120 */ 121 @Override 122 public int hashCode() { 123 return "ComparableComparator".hashCode(); 124 } 125 126 }