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
033public interface MapDifference<K extends @Nullable Object, V extends @Nullable Object> {
034  /**
035   * Returns {@code true} if there are no differences between the two maps; that is, if the maps are
036   * equal.
037   */
038  boolean areEqual();
039
040  /**
041   * Returns an unmodifiable map containing the entries from the left map whose keys are not present
042   * in the right map.
043   */
044  Map<K, V> entriesOnlyOnLeft();
045
046  /**
047   * Returns an unmodifiable map containing the entries from the right map whose keys are not
048   * present in the left map.
049   */
050  Map<K, V> entriesOnlyOnRight();
051
052  /**
053   * Returns an unmodifiable map containing the entries that appear in both maps; that is, the
054   * intersection of the two maps.
055   */
056  Map<K, V> entriesInCommon();
057
058  /**
059   * Returns an unmodifiable map describing keys that appear in both maps, but with different
060   * values.
061   */
062  Map<K, ValueDifference<V>> entriesDiffering();
063
064  /**
065   * Compares the specified object with this instance for equality. Returns {@code true} if the
066   * given object is also a {@code MapDifference} and the values returned by the {@link
067   * #entriesOnlyOnLeft()}, {@link #entriesOnlyOnRight()}, {@link #entriesInCommon()} and {@link
068   * #entriesDiffering()} of the two instances are equal.
069   */
070  @Override
071  boolean equals(@CheckForNull Object object);
072
073  /**
074   * Returns the hash code for this instance. This is defined as the hash code of
075   *
076   * <pre>{@code
077   * Arrays.asList(entriesOnlyOnLeft(), entriesOnlyOnRight(),
078   *     entriesInCommon(), entriesDiffering())
079   * }</pre>
080   */
081  @Override
082  int hashCode();
083
084  /**
085   * A difference between the mappings from two maps with the same key. The {@link #leftValue} and
086   * {@link #rightValue} are not equal, and one but not both of them may be null.
087   *
088   * @since 2.0
089   */
090  @DoNotMock("Use Maps.difference")
091  interface ValueDifference<V extends @Nullable Object> {
092    /** Returns the value from the left map (possibly null). */
093    @ParametricNullness
094    V leftValue();
095
096    /** Returns the value from the right map (possibly null). */
097    @ParametricNullness
098    V rightValue();
099
100    /**
101     * Two instances are considered equal if their {@link #leftValue()} values are equal and their
102     * {@link #rightValue()} values are also equal.
103     */
104    @Override
105    boolean equals(@CheckForNull Object other);
106
107    /**
108     * The hash code equals the value {@code Arrays.asList(leftValue(), rightValue()).hashCode()}.
109     */
110    @Override
111    int hashCode();
112  }
113}