* * The ordering imposed by a Comparator c on a set of elements * S is said to be consistent with equals if and only if * (compare((Object)e1, (Object)e2)==0) has the same boolean value as * e1.equals((Object)e2) for every e1 and e2 in * S.
* * Caution should be exercised when using a comparator capable of imposing an * ordering inconsistent with equals to order a sorted set (or sorted map). * Suppose a sorted set (or sorted map) with an explicit Comparator c * is used with elements (or keys) drawn from a set S. If the * ordering imposed by c on S is inconsistent with equals, * the sorted set (or sorted map) will behave "strangely." In particular the * sorted set (or sorted map) will violate the general contract for set (or * map), which is defined in terms of equals.
* * For example, if one adds two keys a and b such that * (a.equals((Object)b) && c.compare((Object)a, (Object)b) != 0) to a * sorted set with comparator c, the second add operation * will return false (and the size of the sorted set will not increase) * because a and b are equivalent from the sorted set's * perspective.
* * Note: It is generally a good idea for comparators to implement * java.io.Serializable, as they may be used as ordering methods in * serializable data structures (like TreeSet, TreeMap). In * order for the data structure to serialize successfully, the comparator (if * provided) must implement Serializable.
* * For the mathematically inclined, the relation that defines * the total order that a given comparator c imposes on a * given set of objects S is:
* {(x, y) such that c.compare((Object)x, (Object)y) <= 0}.
* The quotient for this total order is:
* {(x, y) such that c.compare((Object)x, (Object)y) == 0}.
*
*
* It follows immediately from the contract for compare that the
* quotient is an equivalence relation on S, and that the
* natural ordering is a total order on S. When we say that
* the ordering imposed by c on S is consistent with
* equals, we mean that the quotient for the natural ordering is the
* equivalence relation defined by the objects' equals(Object)
* method(s):
* {(x, y) such that x.equals((Object)y)}.
*
*
* This interface is a member of the
*
* Java Collections Framework.
*
* @author Josh Bloch
* @author Neal Gafter
* @version 1.22, 12/19/03
* @see Comparable
* @see Arrays#sort(Object[], Comparator)
* @see TreeMap
* @see TreeSet
* @see SortedMap
* @see SortedSet
* @see java.io.Serializable
* @since 1.2
*/
public interface Comparator
*
* The implementor must ensure that sgn(compare(x, y)) ==
* -sgn(compare(y, x)) for all x and y. (This
* implies that compare(x, y) must throw an exception if and only
* if compare(y, x) throws an exception.)
*
* The implementor must also ensure that the relation is transitive:
* ((compare(x, y)>0) && (compare(y, z)>0)) implies
* compare(x, z)>0.
*
* Finally, the implementer must ensure that compare(x, y)==0
* implies that sgn(compare(x, z))==sgn(compare(y, z)) for all
* z.
*
* It is generally the case, but not strictly required that
* (compare(x, y)==0) == (x.equals(y)). Generally speaking,
* any comparator that violates this condition should clearly indicate
* this fact. The recommended language is "Note: this comparator
* imposes orderings that are inconsistent with equals."
*
* @param o1 the first object to be compared.
* @param o2 the second object to be compared.
* @return a negative integer, zero, or a positive integer as the
* first argument is less than, equal to, or greater than the
* second.
* @throws ClassCastException if the arguments' types prevent them from
* being compared by this Comparator.
*/
int compare(T o1, T o2);
/**
*
* Indicates whether some other object is "equal to" this
* Comparator. This method must obey the general contract of
* Object.equals(Object). Additionally, this method can return
* true only if the specified Object is also a comparator
* and it imposes the same ordering as this comparator. Thus,
*
*
* Note that it is always safe not to override
* Object.equals(Object). However, overriding this method may,
* in some cases, improve performance by allowing programs to determine
* that two distinct Comparators impose the same order.
*
* @param obj the reference object with which to compare.
* @return comp1.equals(comp2) implies that sgn(comp1.compare(o1,
* o2))==sgn(comp2.compare(o1, o2)) for every object reference
* o1 and o2.true only if the specified object is also
* a comparator and it imposes the same ordering as this
* comparator.
* @see java.lang.Object#equals(java.lang.Object)
* @see java.lang.Object#hashCode()
*/
boolean equals(Object obj);
}