Package org.docx4j.com.google.common.base

Class Equivalence<T>

java.lang.Object
org.docx4j.com.google.common.base.Equivalence<T>
All Implemented Interfaces:
java.util.function.BiPredicate<T,​T>
@GwtCompatible
public abstract class Equivalence<T>
extends java.lang.Object
implements java.util.function.BiPredicate<T,​T>
A strategy for determining whether two instances are considered equivalent, and for computing hash codes in a manner consistent with that equivalence. Two examples of equivalences are the identity equivalence and the "equals" equivalence.
Since:
10.0 (mostly source-compatible since 4.0)
Author:
Bob Lee, Ben Yu, Gregory Kick

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  Equivalence.Wrapper<T>
    Wraps an object so that Equivalence.Wrapper.equals(Object) and Equivalence.Wrapper.hashCode() delegate to an Equivalence.

  • Constructor Summary

    Constructors 
    Modifier Constructor Description
    protected Equivalence()
    Constructor for use by subclasses.

  • Method Summary

    Modifier and Type Method Description
    protected abstract boolean doEquivalent​(T a, T b)
    Implemented by the user to determine whether a and b are considered equivalent, subject to the requirements specified in equivalent(T, T).
    protected abstract int doHash​(T t)
    Implemented by the user to return a hash code for t, subject to the requirements specified in hash(T).
    static Equivalence<java.lang.Object> equals()
    Returns an equivalence that delegates to Object.equals(java.lang.Object) and Object.hashCode().
    boolean equivalent​(@Nullable T a, @Nullable T b)
    Returns true if the given objects are considered equivalent.
    Predicate<T> equivalentTo​(@Nullable T target)
    Returns a predicate that evaluates to true if and only if the input is equivalent to target according to this equivalence relation.
    int hash​(@Nullable T t)
    Returns a hash code for t.
    static Equivalence<java.lang.Object> identity()
    Returns an equivalence that uses == to compare values and System.identityHashCode(Object) to compute the hash code.
    boolean test​(@Nullable T t, @Nullable T u)
    Deprecated.
    Provided only to satisfy the BiPredicate interface; use equivalent(T, T) instead.
    <S extends T>
    Equivalence.Wrapper<S>    		 wrap​(@Nullable S reference)
    Returns a wrapper of reference that implements Object.equals() such that wrap(a).equals(wrap(b)) if and only if equivalent(a, b).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface java.util.function.BiPredicate

    and, negate, or

  • Constructor Details

    • Equivalence

      protected Equivalence()
      Constructor for use by subclasses.

  • Method Details

    • equivalent

      public final boolean equivalent​(@Nullable T a, @Nullable T b)
      Returns true if the given objects are considered equivalent.

      This method describes an equivalence relation on object references, meaning that for all references x, y, and z (any of which may be null):

      • equivalent(x, x) is true (reflexive property)
      • equivalent(x, y) and equivalent(y, x) each return the same result (symmetric property)
      • If equivalent(x, y) and equivalent(y, z) are both true, then equivalent(x, z) is also true (transitive property)

      Note that all calls to equivalent(x, y) are expected to return the same result as long as neither x nor y is modified.

    • test

      @Deprecated public final boolean test​(@Nullable T t, @Nullable T u)
      Deprecated.
      Provided only to satisfy the BiPredicate interface; use equivalent(T, T) instead.
      Specified by:
      test in interface java.util.function.BiPredicate<T,​T>
      Since:
      21.0

    • doEquivalent

      @ForOverride protected abstract boolean doEquivalent​(T a, T b)
      Implemented by the user to determine whether a and b are considered equivalent, subject to the requirements specified in equivalent(T, T).

      This method should not be called except by equivalent(T, T). When equivalent(T, T) calls this method, a and b are guaranteed to be distinct, non-null instances.

      Since:
      10.0 (previously, subclasses would override equivalent())

    • hash

      public final int hash​(@Nullable T t)
      Returns a hash code for t.

      The hash has the following properties:

      • It is consistent: for any reference x, multiple invocations of hash(x} consistently return the same value provided x remains unchanged according to the definition of the equivalence. The hash need not remain consistent from one execution of an application to another execution of the same application.
      • It is distributable across equivalence: for any references x and y, if equivalent(x, y), then hash(x) == hash(y). It is not necessary that the hash be distributable across inequivalence. If equivalence(x, y) is false, hash(x) == hash(y) may still be true.
      • hash(null) is 0.

    • doHash

      @ForOverride protected abstract int doHash​(T t)
      Implemented by the user to return a hash code for t, subject to the requirements specified in hash(T).

      This method should not be called except by hash(T). When hash(T) calls this method, t is guaranteed to be non-null.

      Since:
      10.0 (previously, subclasses would override hash())

    • wrap

      public final <S extends T> Equivalence.Wrapper<S> wrap​(@Nullable S reference)
      Returns a wrapper of reference that implements Object.equals() such that wrap(a).equals(wrap(b)) if and only if equivalent(a, b).
      Since:
      10.0

    • equivalentTo

      public final Predicate<T> equivalentTo​(@Nullable T target)
      Returns a predicate that evaluates to true if and only if the input is equivalent to target according to this equivalence relation.
      Since:
      10.0

    • equals

      public static Equivalence<java.lang.Object> equals()
      Returns an equivalence that delegates to Object.equals(java.lang.Object) and Object.hashCode(). equivalent(T, T) returns true if both values are null, or if neither value is null and Object.equals(java.lang.Object) returns true. hash(T) returns 0 if passed a null value.
      Since:
      13.0, 8.0 (in Equivalences with null-friendly behavior), 4.0 (in Equivalences)

    • identity

      public static Equivalence<java.lang.Object> identity()
      Returns an equivalence that uses == to compare values and System.identityHashCode(Object) to compute the hash code. equivalent(T, T) returns true if a == b, including in the case that a and b are both null.
      Since:
      13.0, 4.0 (in Equivalences)