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 
18 package java.util;
19 
20 /**
21  * A {@code Comparator} is used to compare two objects to determine their ordering with
22  * respect to each other. On a given {@code Collection}, a {@code Comparator} can be used to
23  * obtain a sorted {@code Collection} which is <i>totally ordered</i>. For a {@code Comparator}
24  * to be <i>consistent with equals</i>, its {code #compare(Object, Object)}
25  * method has to return zero for each pair of elements (a,b) where a.equals(b)
26  * holds true. It is recommended that a {@code Comparator} implements
27  * {@link java.io.Serializable}.
28  *
29  * @since 1.2
30  */
31 public interface Comparator<T> {
32     /**
33      * Compares the two specified objects to determine their relative ordering. The ordering
34      * implied by the return value of this method for all possible pairs of
35      * {@code (lhs, rhs)} should form an <i>equivalence relation</i>.
36      * This means that
37      * <ul>
38      * <li>{@code compare(a,a)} returns zero for all {@code a}</li>
39      * <li>the sign of {@code compare(a,b)} must be the opposite of the sign of {@code
40      * compare(b,a)} for all pairs of (a,b)</li>
41      * <li>From {@code compare(a,b) > 0} and {@code compare(b,c) > 0} it must
42      * follow {@code compare(a,c) > 0} for all possible combinations of {@code
43      * (a,b,c)}</li>
44      * </ul>
45      *
46      * @param lhs
47      *            an {@code Object}.
48      * @param rhs
49      *            a second {@code Object} to compare with {@code lhs}.
50      * @return an integer < 0 if {@code lhs} is less than {@code rhs}, 0 if they are
51      *         equal, and > 0 if {@code lhs} is greater than {@code rhs}.
52      * @throws ClassCastException
53      *                if objects are not of the correct type.
54      */
compare(T lhs, T rhs)55     public int compare(T lhs, T rhs);
56 
57     /**
58      * Compares this {@code Comparator} with the specified {@code Object} and indicates whether they
59      * are equal. In order to be equal, {@code object} must represent the same object
60      * as this instance using a class-specific comparison.
61      * <p>
62      * A {@code Comparator} never needs to override this method, but may choose so for
63      * performance reasons.
64      *
65      * @param object
66      *            the {@code Object} to compare with this comparator.
67      * @return boolean {@code true} if specified {@code Object} is the same as this
68      *         {@code Object}, and {@code false} otherwise.
69      * @see Object#hashCode
70      * @see Object#equals
71      */
equals(Object object)72     public boolean equals(Object object);
73 }
74