1 /* 2 * Copyright (C) 2007 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.collect; 18 19 import com.google.common.annotations.GwtCompatible; 20 import com.google.errorprone.annotations.DoNotMock; 21 import java.util.Map; 22 import javax.annotation.CheckForNull; 23 import org.checkerframework.checker.nullness.qual.Nullable; 24 25 /** 26 * An object representing the differences between two maps. 27 * 28 * @author Kevin Bourrillion 29 * @since 2.0 30 */ 31 @DoNotMock("Use Maps.difference") 32 @GwtCompatible 33 @ElementTypesAreNonnullByDefault 34 public interface MapDifference<K extends @Nullable Object, V extends @Nullable Object> { 35 /** 36 * Returns {@code true} if there are no differences between the two maps; that is, if the maps are 37 * equal. 38 */ areEqual()39 boolean areEqual(); 40 41 /** 42 * Returns an unmodifiable map containing the entries from the left map whose keys are not present 43 * in the right map. 44 */ entriesOnlyOnLeft()45 Map<K, V> entriesOnlyOnLeft(); 46 47 /** 48 * Returns an unmodifiable map containing the entries from the right map whose keys are not 49 * present in the left map. 50 */ entriesOnlyOnRight()51 Map<K, V> entriesOnlyOnRight(); 52 53 /** 54 * Returns an unmodifiable map containing the entries that appear in both maps; that is, the 55 * intersection of the two maps. 56 */ entriesInCommon()57 Map<K, V> entriesInCommon(); 58 59 /** 60 * Returns an unmodifiable map describing keys that appear in both maps, but with different 61 * values. 62 */ entriesDiffering()63 Map<K, ValueDifference<V>> entriesDiffering(); 64 65 /** 66 * Compares the specified object with this instance for equality. Returns {@code true} if the 67 * given object is also a {@code MapDifference} and the values returned by the {@link 68 * #entriesOnlyOnLeft()}, {@link #entriesOnlyOnRight()}, {@link #entriesInCommon()} and {@link 69 * #entriesDiffering()} of the two instances are equal. 70 */ 71 @Override equals(@heckForNull Object object)72 boolean equals(@CheckForNull Object object); 73 74 /** 75 * Returns the hash code for this instance. This is defined as the hash code of 76 * 77 * <pre>{@code 78 * Arrays.asList(entriesOnlyOnLeft(), entriesOnlyOnRight(), 79 * entriesInCommon(), entriesDiffering()) 80 * }</pre> 81 */ 82 @Override hashCode()83 int hashCode(); 84 85 /** 86 * A difference between the mappings from two maps with the same key. The {@link #leftValue} and 87 * {@link #rightValue} are not equal, and one but not both of them may be null. 88 * 89 * @since 2.0 90 */ 91 @DoNotMock("Use Maps.difference") 92 interface ValueDifference<V extends @Nullable Object> { 93 /** Returns the value from the left map (possibly null). */ 94 @ParametricNullness leftValue()95 V leftValue(); 96 97 /** Returns the value from the right map (possibly null). */ 98 @ParametricNullness rightValue()99 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 equals(@heckForNull Object other)106 boolean equals(@CheckForNull Object other); 107 108 /** 109 * The hash code equals the value {@code Arrays.asList(leftValue(), rightValue()).hashCode()}. 110 */ 111 @Override hashCode()112 int hashCode(); 113 } 114 } 115