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