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
18package 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 */
31public 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     */
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     */
72    public boolean equals(Object object);
73}
74