net.openhft.collect
Class Equivalence<T>

java.lang.Object
  net.openhft.collect.Equivalence<T>

Type Parameters:

T - type of objects compared by this equivalence

Direct Known Subclasses:

StatelessEquivalence

public abstract class Equivalence<T>
extends Object

A strategy for determining whether two instances are considered equivalent.

This class is inspired and very similar to Guava's Equivalence, with two notable differences.

First, this Equivalence is consistently nullable, i. e. when null is passed instead of Equivalence instance anywhere in the library, default Java equality is assumed (see Object.equals(Object) and Object.hashCode()). In Guava there is a special instance for such equivalence.

Second, this Equivalence forces the actual implementation to override equals(Object) and hashCode(). Notice these are Equivalence's own equals and hashCode, not the strategy equivalent(Object, Object) and hash(Object) methods. It is needed because, for example, ObjCollection's equality depends on Equivalence equality.

In most cases, when Equivalence is stateless, you can extend StatelessEquivalence not to bother with implementing these methods. See examples in the documentation to identity and case insensitive equivalences.

Constructor Summary

protected

Equivalence() Constructor for use by subclasses.

Method Summary

static Equivalence<String>	caseInsensitive() Returns the String equivalence that uses String.equalsIgnoreCase(java.lang.String) to compare strings.
static <K,V> Equivalence<Map.Entry<K,V>>	entryEquivalence(Equivalence<K> keyEquivalence, Equivalence<V> valueEquivalence) Returns a Map.Entry equivalence for the given key and value equivalences.
abstract boolean	equals(Object o) This method is made abstract to force the final implementation to override it.
abstract boolean	equivalent(T a, T b) Returns true if a and b are considered equivalent, false otherwise.
abstract int	hash(T t) Returns a hash code for the given object.
abstract int	hashCode() This method is made abstract to force the final implementation to override it.
static Equivalence<Object>	identity() Returns the equivalence that uses == to compare objects and System.identityHashCode(Object) to compute the hash code.
boolean	nullableEquivalent(T a, T b) Returns true if a and b are considered equivalent, false otherwise.
int	nullableHash(T t) Returns a hash code for the given object.

Methods inherited from class java.lang.Object

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

Constructor Detail

Equivalence

protected Equivalence()

Constructor for use by subclasses.

Method Detail

identity

@Nonnull
public static Equivalence<Object> identity()

Returns the equivalence that uses == to compare objects and System.identityHashCode(Object) to compute the hash code. nullableEquivalent(T, T) returns true if a == b, including in the case when a and b are both null.

This equivalence could be implemented as follows:

final class Identity extends StatelessEquivalence<Object> {
     static final Identity INSTANCE = new Identity();
     private Identity() {}
     @Override
     public boolean equivalent(@Nonnull Object a, @Nonnull Object b) {
         return a == b;
     }
     @Override
     public int hash(@Nonnull Object t) {
         return System.identityHashCode(t);
     }
 }
 

Returns:

the identity equivalence

caseInsensitive

@Nonnull
public static Equivalence<String> caseInsensitive()

Returns the String equivalence that uses String.equalsIgnoreCase(java.lang.String) to compare strings.

This equivalence could be implemented as follows:

final class CaseInsensitive extends StatelessEquivalence<String> {
     static final CaseInsensitive INSTANCE = new CaseInsensitive();
     private CaseInsensitive() {}
     @Override
     public boolean equivalent(@Nonnull String a, @Nonnull String b) {
         return a.equalsIgnoreCase(b);
     }
     @Override
     public int hash(@Nonnull String s) {
         return s.toLowerCase().hashCode();
     }
 }
 

Returns:

the case-insensitive String equivalence

entryEquivalence

@Nullable
public static <K,V> Equivalence<Map.Entry<K,V>> entryEquivalence(@Nullable
                                                                          Equivalence<K> keyEquivalence,
                                                                          @Nullable
                                                                          Equivalence<V> valueEquivalence)

Returns a Map.Entry equivalence for the given key and value equivalences.

Type Parameters:

K - the entry key type

V - the entry value type

Parameters:

keyEquivalence - the entry key equivalence

valueEquivalence - the entry value equivalence

Returns:

a Map.Entry equivalence for the given key and value equivalences

nullableEquivalent

public boolean nullableEquivalent(@Nullable
                                  T a,
                                  @Nullable
                                  T b)

Returns true if a and b are considered equivalent, false otherwise. a and b both might be null.

If the implementation overrides this method, it must ensure that it returns true if both the given objects are nulls and false, if only one of them is null. If both a and b are non-null, this method should perform just the same as equivalent(Object, Object) method does.

Parameters:

a - the first object to compare

b - the second object to compare

Returns:

true if a and b are considered equivalent, false otherwise

equivalent

public abstract boolean equivalent(@Nonnull
                                   T a,
                                   @Nonnull
                                   T b)

Returns true if a and b are considered equivalent, false otherwise. a and b are assumed to be non-null.

This method implements an equivalence relation on object references:

• It is reflexive: for any reference x, 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).

This method is called by nullableEquivalent(Object, Object).

Parameters:

a - the first object to compare

b - the second object to compare

Returns:

true if a and b are considered equivalent, false otherwise

nullableHash

public int nullableHash(@Nullable
                        T t)

Returns a hash code for the given object. The t object might be null.

If the implementation overrides this method, it must ensure that it returns 0 if the given object is null. Otherwise this method should perform just the same as hash(Object) method does.

Parameters:

t - the object to compute hash code for

Returns:

a hash code for the given object

hash

public abstract int hash(@Nonnull
                         T t)

Returns a hash code for the given object. The t object is assumed to be non-null.

This method 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.

This method is called by nullableHash(Object).

Parameters:

t - the object to compute hash code for

Returns:

a hash code for the given object

equals

public abstract boolean equals(Object o)

This method is made abstract to force the final implementation to override it. It is needed because, for example, ObjObjMap's equality depends on key and value Equivalence equality.

Overrides:

equals in class Object

hashCode

public abstract int hashCode()

This method is made abstract to force the final implementation to override it. It is needed because, equals(Object) is needed to be overridden, and in Java Object.equals(Object) and Object.hashCode() should always be overridden simultaneously.

Overrides:

hashCode in class Object