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