com.nytimes.android.external.cache

Class Equivalence<T>

java.lang.Object

com.nytimes.android.external.cache.Equivalence<T>

public abstract class Equivalence<T>
extends java.lang.Object

A strategy for determining whether two instances are considered equivalent. Examples of equivalences are the identity equivalence and equals equivalence.

Since:

10.0 (mostly source-compatible since 4.0)

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
protected abstract boolean	doEquivalent(T a, T b) Returns true if a and b are considered equivalent.
protected abstract int	doHash(T t) Returns a hash code for non-null object t.
static Equivalence<java.lang.Object>	equals() Returns an equivalence that delegates to Object.equals(java.lang.Object) and Object.hashCode().
boolean	equivalent(T a, T b) Returns true if the given objects are considered equivalent.
int	hash(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.

Methods inherited from class java.lang.Object

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

Constructor Detail

Equivalence

protected Equivalence()

Constructor for use by subclasses.

Method Detail

equivalent

public final boolean equivalent(T a,
                                T b)

Returns true if the given objects are considered equivalent.

The equivalent method implements an equivalence relation on object references:

• It is reflexive: for any reference x, including null, equivalent(x, x) returns true.
• It is symmetric: for any references x and y, equivalent(x, y) == equivalent(y, x).
• It is transitive: for any references x, y, and z, if equivalent(x, y) returns true and equivalent(y, z) returns true, then equivalent(x, z) returns true.
• It is consistent: for any references x and y, multiple invocations of equivalent(x, y) consistently return true or consistently return false (provided that neither x nor y is modified).

doEquivalent

protected abstract boolean doEquivalent(T a,
                                        T b)

Returns true if a and b are considered equivalent.

Called by equivalent(T, T). a and b are not the same object and are not nulls.

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

protected abstract int doHash(T t)

Returns a hash code for non-null object t.

Called by hash(T).

Since:

10.0 (previously, subclasses would override hash())

equals

@Nonnull
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

@Nonnull
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)