001    /*
002     * Copyright (C) 2010 Google Inc.
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     */
014    
015    package com.google.common.base;
016    
017    import com.google.common.annotations.Beta;
018    
019    /**
020     * A strategy for determining whether two instances are considered equivalent. Examples of
021     * equivalences are the {@link Equivalences#identity() identity equivalence} and {@link
022     * Equivalences#equals equals equivalence}.
023     *
024     * @author Bob Lee
025     * @since 4
026     */
027    @Beta
028    public interface Equivalence<T> {
029      /**
030       * Returns {@code true} if the given objects are considered equivalent.
031       *
032       * <p>The <code>equivalent</code> method implements an equivalence relation on non-null object
033       * references:
034       *
035       * <ul>
036       * <li>It is <i>reflexive</i>: for any non-null reference value {@code x}, {@code x.equals(x)}
037       *     should return {@code true}.
038       * <li>It is <i>symmetric</i>: for any non-null reference values {@code x} and {@code y}, {@code
039       *     x.equals(y)} should return {@code true} if and only if {@code y.equals(x)} returns {@code
040       *     true}.
041       * <li>It is <i>transitive</i>: for any non-null reference values {@code x}, {@code y}, and {@code
042       *     z}, if {@code x.equals(y)} returns {@code true} and {@code y.equals(z)} returns {@code
043       *     true}, then {@code x.equals(z)} should return {@code true}.
044       * <li>It is <i>consistent</i>: for any non-null reference values {@code x} and {@code y},
045       *     multiple invocations of {@code x.equals(y)} consistently return {@code true} or
046       *     consistently return {@code false}, provided no information used in {@code equals}
047       *     comparisons on the objects is modified.
048       * <li>For any non-null reference value {@code x}, {@code x.equals(null)} should return {@code
049       *     false}.
050       * </ul>
051       */
052      boolean equivalent(T a, T b);
053    
054      /**
055       * Returns a hash code for {@code object}. This function <b>must</b> return the same value for
056       * any two instances which are {@link #equivalent}, and should as often as possible return a
057       * distinct value for instances which are not equivalent.
058       *
059       * @see Object#hashCode the same contractual obligations apply here
060       * @throws NullPointerException if t is null
061       */
062      int hash(T t);
063    }