001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.collect;
018
019import com.google.common.annotations.GwtCompatible;
020import com.google.errorprone.annotations.DoNotMock;
021import java.util.Map;
022import javax.annotation.CheckForNull;
023import org.checkerframework.checker.nullness.qual.Nullable;
024
025/**
026 * An object representing the differences between two maps.
027 *
028 * @author Kevin Bourrillion
029 * @since 2.0
030 */
031@DoNotMock("Use Maps.difference")
032@GwtCompatible
033@ElementTypesAreNonnullByDefault
034public interface MapDifference<K extends @Nullable Object, V extends @Nullable Object> {
035  /**
036   * Returns {@code true} if there are no differences between the two maps; that is, if the maps are
037   * equal.
038   */
039  boolean areEqual();
040
041  /**
042   * Returns an unmodifiable map containing the entries from the left map whose keys are not present
043   * in the right map.
044   */
045  Map<K, V> entriesOnlyOnLeft();
046
047  /**
048   * Returns an unmodifiable map containing the entries from the right map whose keys are not
049   * present in the left map.
050   */
051  Map<K, V> entriesOnlyOnRight();
052
053  /**
054   * Returns an unmodifiable map containing the entries that appear in both maps; that is, the
055   * intersection of the two maps.
056   */
057  Map<K, V> entriesInCommon();
058
059  /**
060   * Returns an unmodifiable map describing keys that appear in both maps, but with different
061   * values.
062   */
063  Map<K, ValueDifference<V>> entriesDiffering();
064
065  /**
066   * Compares the specified object with this instance for equality. Returns {@code true} if the
067   * given object is also a {@code MapDifference} and the values returned by the {@link
068   * #entriesOnlyOnLeft()}, {@link #entriesOnlyOnRight()}, {@link #entriesInCommon()} and {@link
069   * #entriesDiffering()} of the two instances are equal.
070   */
071  @Override
072  boolean equals(@CheckForNull Object object);
073
074  /**
075   * Returns the hash code for this instance. This is defined as the hash code of
076   *
077   * <pre>{@code
078   * Arrays.asList(entriesOnlyOnLeft(), entriesOnlyOnRight(),
079   *     entriesInCommon(), entriesDiffering())
080   * }</pre>
081   */
082  @Override
083  int hashCode();
084
085  /**
086   * A difference between the mappings from two maps with the same key. The {@link #leftValue} and
087   * {@link #rightValue} are not equal, and one but not both of them may be null.
088   *
089   * @since 2.0
090   */
091  @DoNotMock("Use Maps.difference")
092  interface ValueDifference<V extends @Nullable Object> {
093    /** Returns the value from the left map (possibly null). */
094    @ParametricNullness
095    V leftValue();
096
097    /** Returns the value from the right map (possibly null). */
098    @ParametricNullness
099    V rightValue();
100
101    /**
102     * Two instances are considered equal if their {@link #leftValue()} values are equal and their
103     * {@link #rightValue()} values are also equal.
104     */
105    @Override
106    boolean equals(@CheckForNull Object other);
107
108    /**
109     * The hash code equals the value {@code Arrays.asList(leftValue(), rightValue()).hashCode()}.
110     */
111    @Override
112    int hashCode();
113  }
114}