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     * Contains static factory methods for creating {@code Equivalence} instances.
024     *
025     * <p>All methods return serializable instances.
026     *
027     * @author Bob Lee
028     * @author Kurt Alfred Kluever
029     * @since 4
030     */
031    @Beta
032    @GwtCompatible
033    public final class Equivalences {
034      private Equivalences() {}
035    
036      /**
037       * Returns an equivalence that delegates to {@link Object#equals} and {@link Object#hashCode}.
038       * {@link Equivalence#equivalent} returns {@code true} if both values are null, or if neither
039       * value is null and {@link Object#equals} returns {@code true}. {@link Equivalence#hash} returns
040       * {@code 0} if passed a null value.
041       *
042       * @since 8 (present null-friendly behavior)
043       * @since 4 (otherwise)
044       */
045      public static Equivalence<Object> equals() {
046        return Impl.EQUALS;
047      }
048    
049      /**
050       * Returns an equivalence that delegates to {@link Object#equals} and {@link Object#hashCode}.
051       * {@link Equivalence#equivalent} returns {@code true} if both values are null, or if neither
052       * value is null and {@link Object#equals} returns {@code true}. {@link Equivalence#hash} returns
053       * {@code 0} if passed a null value.
054       *
055       * @deprecated use {@link Equivalences#equals}, which now has the null-aware behavior
056       */
057      @Deprecated
058      public static Equivalence<Object> nullAwareEquals() {
059        return Impl.EQUALS;
060      }
061    
062      /**
063       * Returns an equivalence that uses {@code ==} to compare values and {@link
064       * System#identityHashCode(Object)} to compute the hash code.  {@link Equivalence#equivalent}
065       * returns {@code true} if {@code a == b}, including in the case that a and b are both null.
066       */
067      public static Equivalence<Object> identity() {
068        return Impl.IDENTITY;
069      }
070    
071      private enum Impl implements Equivalence<Object> {
072        EQUALS {
073          public boolean equivalent(@Nullable Object a, @Nullable Object b) {
074            // TODO(kevinb): use Objects.equal() after testing issue is worked out.
075            return (a == null) ? (b == null) : a.equals(b);
076          }
077    
078          public int hash(@Nullable Object o) {
079            return (o == null) ? 0 : o.hashCode();
080          }
081        },
082        IDENTITY {
083          public boolean equivalent(@Nullable Object a, @Nullable Object b) {
084            return a == b;
085          }
086    
087          public int hash(@Nullable Object o) {
088            return System.identityHashCode(o);
089          }
090        },
091      }
092    }