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