This example Java source code file (Equivalence.java) is included in the alvinalexander.com
"Java Source Code
Warehouse" project. The intent of this project is to help you "Learn
Java by Example" TM.
/*
* Copyright (C) 2010 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.common.base;
import static com.google.common.base.Preconditions.checkNotNull;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
import java.io.Serializable;
import javax.annotation.Nullable;
/**
* A strategy for determining whether two instances are considered equivalent. Examples of
* equivalences are the {@linkplain #identity() identity equivalence} and {@linkplain #equals equals
* equivalence}.
*
* <h3>For Java 8+ users
*
* <p>A future version of this class will implement {@code BiPredicate}. In the meantime, to
* use an equivalence (say, named {@code equivalence}) as a bi-predicate, use the method reference
* {@code equivalence::equivalent}.
*
* @author Bob Lee
* @author Ben Yu
* @author Gregory Kick
* @since 10.0 (<a href="https://github.com/google/guava/wiki/Compatibility">mostly
* source-compatible</a> since 4.0)
*/
@GwtCompatible
public abstract class Equivalence<T> {
/**
* Constructor for use by subclasses.
*/
protected Equivalence() {}
/**
* Returns {@code true} if the given objects are considered equivalent.
*
* <p>The {@code equivalent} method implements an equivalence relation on object references:
*
* <ul>
* <li>It is reflexive: for any reference {@code x}, including null, {@code
* equivalent(x, x)} returns {@code true}.
* <li>It is symmetric: for any references {@code x} and {@code y}, {@code
* equivalent(x, y) == equivalent(y, x)}.
* <li>It is transitive: for any references {@code x}, {@code y}, and {@code z}, if
* {@code equivalent(x, y)} returns {@code true} and {@code equivalent(y, z)} returns {@code
* true}, then {@code equivalent(x, z)} returns {@code true}.
* <li>It is consistent: for any references {@code x} and {@code y}, multiple invocations
* of {@code equivalent(x, y)} consistently return {@code true} or consistently return {@code
* false} (provided that neither {@code x} nor {@code y} is modified).
* </ul>
*/
public final boolean equivalent(@Nullable T a, @Nullable T b) {
if (a == b) {
return true;
}
if (a == null || b == null) {
return false;
}
return doEquivalent(a, b);
}
/**
* Returns {@code true} if {@code a} and {@code b} are considered equivalent.
*
* <p>Called by {@link #equivalent}. {@code a} and {@code b} are not the same object and are not
* nulls.
*
* @since 10.0 (previously, subclasses would override equivalent())
*/
protected abstract boolean doEquivalent(T a, T b);
/**
* Returns a hash code for {@code t}.
*
* <p>The {@code hash} has the following properties:
* <ul>
* <li>It is consistent: for any reference {@code x}, multiple invocations of
* {@code hash(x}} consistently return the same value provided {@code 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.
* <li>It is distributable across equivalence: for any references {@code x} and {@code y},
* if {@code equivalent(x, y)}, then {@code hash(x) == hash(y)}. It is <i>not necessary
* that the hash be distributable across <i>inequivalence. If {@code equivalence(x, y)} is
* false, {@code hash(x) == hash(y)} may still be true.
* <li>{@code hash(null)} is {@code 0}.
* </ul>
*/
public final int hash(@Nullable T t) {
if (t == null) {
return 0;
}
return doHash(t);
}
/**
* Returns a hash code for non-null object {@code t}.
*
* <p>Called by {@link #hash}.
*
* @since 10.0 (previously, subclasses would override hash())
*/
protected abstract int doHash(T t);
/**
* Returns a new equivalence relation for {@code F} which evaluates equivalence by first applying
* {@code function} to the argument, then evaluating using {@code this}. That is, for any pair of
* non-null objects {@code x} and {@code y}, {@code
* equivalence.onResultOf(function).equivalent(a, b)} is true if and only if {@code
* equivalence.equivalent(function.apply(a), function.apply(b))} is true.
*
* <p>For example:
*
* <pre> {@code
* Equivalence<Person> SAME_AGE = Equivalence.equals().onResultOf(GET_PERSON_AGE);}
*
* <p>{@code function} will never be invoked with a null value.
*
* <p>Note that {@code function} must be consistent according to {@code this} equivalence
* relation. That is, invoking {@link Function#apply} multiple times for a given value must return
* equivalent results. For example,
* {@code Equivalence.identity().onResultOf(Functions.toStringFunction())} is broken because it's
* not guaranteed that {@link Object#toString}) always returns the same string instance.
*
* @since 10.0
*/
public final <F> Equivalence onResultOf(Function function) {
return new FunctionalEquivalence<F, T>(function, this);
}
/**
* Returns a wrapper of {@code reference} that implements {@link Wrapper#equals(Object)
* Object.equals()} such that {@code wrap(a).equals(wrap(b))} if and only if
* {@code equivalent(a, b)}.
*
* @since 10.0
*/
public final <S extends T> Wrapper wrap(@Nullable S reference) {
return new Wrapper<S>(this, reference);
}
/**
* Wraps an object so that {@link #equals(Object)} and {@link #hashCode()} delegate to an
* {@link Equivalence}.
*
* <p>For example, given an {@link Equivalence} for {@link String strings} named {@code equiv}
* that tests equivalence using their lengths:
*
* <pre> {@code
* equiv.wrap("a").equals(equiv.wrap("b")) // true
* equiv.wrap("a").equals(equiv.wrap("hello")) // false}</pre>
*
* <p>Note in particular that an equivalence wrapper is never equal to the object it wraps.
*
* <pre> {@code
* equiv.wrap(obj).equals(obj) // always false}</pre>
*
* @since 10.0
*/
public static final class Wrapper<T> implements Serializable {
private final Equivalence<? super T> equivalence;
@Nullable private final T reference;
private Wrapper(Equivalence<? super T> equivalence, @Nullable T reference) {
this.equivalence = checkNotNull(equivalence);
this.reference = reference;
}
/** Returns the (possibly null) reference wrapped by this instance. */
@Nullable
public T get() {
return reference;
}
/**
* Returns {@code true} if {@link Equivalence#equivalent(Object, Object)} applied to the wrapped
* references is {@code true} and both wrappers use the {@link Object#equals(Object) same}
* equivalence.
*/
@Override
public boolean equals(@Nullable Object obj) {
if (obj == this) {
return true;
}
if (obj instanceof Wrapper) {
Wrapper<?> that = (Wrapper) obj; // note: not necessarily a Wrapper
if (this.equivalence.equals(that.equivalence)) {
/*
* We'll accept that as sufficient "proof" that either equivalence should be able to
* handle either reference, so it's safe to circumvent compile-time type checking.
*/
@SuppressWarnings("unchecked")
Equivalence<Object> equivalence = (Equivalence
