All Downloads are FREE. Search and download functionalities are using the official Maven repository.

jersey.repackaged.com.google.common.base.Equivalence Maven / Gradle / Ivy

There is a newer version: 2.22.2
Show newest version
/*
 * 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 jersey.repackaged.com.google.common.base;

import static jersey.repackaged.com.google.common.base.Preconditions.checkNotNull;

import jersey.repackaged.com.google.common.annotations.Beta;
import jersey.repackaged.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}.
 *
 * @author Bob Lee
 * @author Ben Yu
 * @author Gregory Kick
 * @since 10.0 (mostly source-compatible since 4.0)
 */
@GwtCompatible
public abstract class Equivalence {
  /**
   * Constructor for use by subclasses.
   */
  protected Equivalence() {}

  /**
   * Returns {@code true} if the given objects are considered equivalent.
   *
   * 

The {@code equivalent} method implements an equivalence relation on object references: * *

    *
  • It is reflexive: for any reference {@code x}, including null, {@code * equivalent(x, x)} returns {@code true}. *
  • It is symmetric: for any references {@code x} and {@code y}, {@code * equivalent(x, y) == equivalent(y, x)}. *
  • 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}. *
  • 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). *
*/ 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. * *

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}. * *

The {@code hash} has the following properties: *

    *
  • 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. *
  • It is distributable accross equivalence: for any references {@code x} and {@code y}, * if {@code equivalent(x, y)}, then {@code hash(x) == hash(y)}. It is not necessary * that the hash be distributable accorss inequivalence. If {@code equivalence(x, y)} * is false, {@code hash(x) == hash(y)} may still be true. *
  • {@code hash(null)} is {@code 0}. *
*/ 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}. * *

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. * *

For example:

   {@code
   *
   *    Equivalence SAME_AGE = Equivalence.equals().onResultOf(GET_PERSON_AGE);
   * }
* *

{@code function} will never be invoked with a null value. * *

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 Equivalence onResultOf(Function function) { return new FunctionalEquivalence(function, this); } /** * Returns a wrapper of {@code reference} that implements * {@link Wrapper#equals(Object) Object.equals()} such that * {@code wrap(this, a).equals(wrap(this, b))} if and only if {@code this.equivalent(a, b)}. * * @since 10.0 */ public final Wrapper wrap(@Nullable S reference) { return new Wrapper(this, reference); } /** * Wraps an object so that {@link #equals(Object)} and {@link #hashCode()} delegate to an * {@link Equivalence}. * *

For example, given an {@link Equivalence} for {@link String strings} named {@code equiv} * that tests equivalence using their lengths: * *

   {@code
   *   equiv.wrap("a").equals(equiv.wrap("b")) // true
   *   equiv.wrap("a").equals(equiv.wrap("hello")) // false
   * }
* *

Note in particular that an equivalence wrapper is never equal to the object it wraps. * *

   {@code
   *   equiv.wrap(obj).equals(obj) // always false
   * }
* * @since 10.0 */ public static final class Wrapper implements Serializable { private final Equivalence equivalence; @Nullable private final T reference; private Wrapper(Equivalence 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; } else if (obj instanceof Wrapper) { Wrapper that = (Wrapper) obj; /* * We cast to Equivalence here because we can't check the type of the reference held * by the other wrapper. But, by checking that the Equivalences are equal, we know that * whatever type it is, it is assignable to the type handled by this wrapper's equivalence. */ @SuppressWarnings("unchecked") Equivalence equivalence = (Equivalence) this.equivalence; return equivalence.equals(that.equivalence) && equivalence.equivalent(this.reference, that.reference); } else { return false; } } /** * Returns the result of {@link Equivalence#hash(Object)} applied to the the wrapped reference. */ @Override public int hashCode() { return equivalence.hash(reference); } /** * Returns a string representation for this equivalence wrapper. The form of this string * representation is not specified. */ @Override public String toString() { return equivalence + ".wrap(" + reference + ")"; } private static final long serialVersionUID = 0; } /** * Returns an equivalence over iterables based on the equivalence of their elements. More * specifically, two iterables are considered equivalent if they both contain the same number of * elements, and each pair of corresponding elements is equivalent according to * {@code this}. Null iterables are equivalent to one another. * *

Note that this method performs a similar function for equivalences as {@link * jersey.repackaged.com.google.common.collect.Ordering#lexicographical} does for orderings. * * @since 10.0 */ @GwtCompatible(serializable = true) public final Equivalence> pairwise() { // Ideally, the returned equivalence would support Iterable. However, // the need for this is so rare that it's not worth making callers deal with the ugly wildcard. return new PairwiseEquivalence(this); } /** * Returns a predicate that evaluates to true if and only if the input is * equivalent to {@code target} according to this equivalence relation. * * @since 10.0 */ @Beta public final Predicate equivalentTo(@Nullable T target) { return new EquivalentToPredicate(this, target); } private static final class EquivalentToPredicate implements Predicate, Serializable { private final Equivalence equivalence; @Nullable private final T target; EquivalentToPredicate(Equivalence equivalence, @Nullable T target) { this.equivalence = checkNotNull(equivalence); this.target = target; } @Override public boolean apply(@Nullable T input) { return equivalence.equivalent(input, target); } @Override public boolean equals(@Nullable Object obj) { if (this == obj) { return true; } if (obj instanceof EquivalentToPredicate) { EquivalentToPredicate that = (EquivalentToPredicate) obj; return equivalence.equals(that.equivalence) && Objects.equal(target, that.target); } return false; } @Override public int hashCode() { return Objects.hashCode(equivalence, target); } @Override public String toString() { return equivalence + ".equivalentTo(" + target + ")"; } private static final long serialVersionUID = 0; } /** * Returns an equivalence that delegates to {@link Object#equals} and {@link Object#hashCode}. * {@link Equivalence#equivalent} returns {@code true} if both values are null, or if neither * value is null and {@link Object#equals} returns {@code true}. {@link Equivalence#hash} returns * {@code 0} if passed a null value. * * @since 13.0 * @since 8.0 (in Equivalences with null-friendly behavior) * @since 4.0 (in Equivalences) */ public static Equivalence equals() { return Equals.INSTANCE; } /** * Returns an equivalence that uses {@code ==} to compare values and {@link * System#identityHashCode(Object)} to compute the hash code. {@link Equivalence#equivalent} * returns {@code true} if {@code a == b}, including in the case that a and b are both null. * * @since 13.0 * @since 4.0 (in Equivalences) */ public static Equivalence identity() { return Identity.INSTANCE; } static final class Equals extends Equivalence implements Serializable { static final Equals INSTANCE = new Equals(); @Override protected boolean doEquivalent(Object a, Object b) { return a.equals(b); } @Override public int doHash(Object o) { return o.hashCode(); } private Object readResolve() { return INSTANCE; } private static final long serialVersionUID = 1; } static final class Identity extends Equivalence implements Serializable { static final Identity INSTANCE = new Identity(); @Override protected boolean doEquivalent(Object a, Object b) { return false; } @Override protected int doHash(Object o) { return System.identityHashCode(o); } private Object readResolve() { return INSTANCE; } private static final long serialVersionUID = 1; } }