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    import com.google.common.annotations.GwtCompatible;
019    
020    import javax.annotation.Nullable;
021    
022    /**
023     * A strategy for determining whether two instances are considered equivalent. Examples of
024     * equivalences are the {@link Equivalences#identity() identity equivalence} and {@link
025     * Equivalences#equals equals equivalence}.
026     *
027     * @author Bob Lee
028     * @since 4
029     */
030    @Beta
031    @GwtCompatible
032    public interface Equivalence<T> {
033      /**
034       * Returns {@code true} if the given objects are considered equivalent.
035       *
036       * <p>The {@code equivalent} method implements an equivalence relation on object references:
037       *
038       * <ul>
039       * <li>It is <i>reflexive</i>: for any reference {@code x}, including null, {@code
040       *     equivalent(x, x)} should return {@code true}.
041       * <li>It is <i>symmetric</i>: for any references {@code x} and {@code y}, {@code
042       *     equivalent(x, y) == equivalent(y, x)}.
043       * <li>It is <i>transitive</i>: for any references {@code x}, {@code y}, and {@code z}, if
044       *     {@code equivalent(x, y)} returns {@code true} and {@code equivalent(y, z)} returns {@code
045       *     true}, then {@code equivalent(x, z)} should return {@code true}.
046       * <li>It is <i>consistent</i>: for any references {@code x} and {@code y}, multiple invocations
047       *     of {@code equivalent(x, y)} consistently return {@code true} or consistently return {@code
048       *     false} (provided that neither {@code x} nor {@code y} is modified).
049       * </ul>
050       */
051      boolean equivalent(@Nullable T a, @Nullable T b);
052    
053      /**
054       * Returns a hash code for {@code object}. This function <b>must</b> return the same value for
055       * any two references which are {@link #equivalent}, and should as often as possible return a
056       * distinct value for references which are not equivalent. It should support null references.
057       *
058       * @see Object#hashCode the same contractual obligations apply here
059       */
060      int hash(@Nullable T t);
061    }