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