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 21 import java.util.Map; 22 23 import javax.annotation.Nullable; 24 25 /** 26 * An object representing the differences between two maps. 27 * 28 * @author Kevin Bourrillion 29 * @since 2.0 (imported from Google Collections Library) 30 */ 31 @GwtCompatible 32 public interface MapDifference<K, V> { 33 /** 34 * Returns {@code true} if there are no differences between the two maps; 35 * that is, if the maps are equal. 36 */ 37 boolean areEqual(); 38 39 /** 40 * Returns an unmodifiable map containing the entries from the left map whose 41 * keys are not present in the right map. 42 */ 43 Map<K, V> entriesOnlyOnLeft(); 44 45 /** 46 * Returns an unmodifiable map containing the entries from the right map whose 47 * keys are not present in the left map. 48 */ 49 Map<K, V> entriesOnlyOnRight(); 50 51 /** 52 * Returns an unmodifiable map containing the entries that appear in both 53 * maps; that is, the intersection of the two maps. 54 */ 55 Map<K, V> entriesInCommon(); 56 57 /** 58 * Returns an unmodifiable map describing keys that appear in both maps, but 59 * with different values. 60 */ 61 Map<K, ValueDifference<V>> entriesDiffering(); 62 63 /** 64 * Compares the specified object with this instance for equality. Returns 65 * {@code true} if the given object is also a {@code MapDifference} and the 66 * values returned by the {@link #entriesOnlyOnLeft()}, {@link 67 * #entriesOnlyOnRight()}, {@link #entriesInCommon()} and {@link 68 * #entriesDiffering()} of the two instances are equal. 69 */ 70 @Override 71 boolean equals(@Nullable Object object); 72 73 /** 74 * Returns the hash code for this instance. This is defined as the hash code 75 * of <pre> {@code 76 * 77 * Arrays.asList(entriesOnlyOnLeft(), entriesOnlyOnRight(), 78 * entriesInCommon(), entriesDiffering())}</pre> 79 */ 80 @Override 81 int hashCode(); 82 83 /** 84 * A difference between the mappings from two maps with the same key. The 85 * {@link #leftValue} and {@link #rightValue} are not equal, and one but not 86 * both of them may be null. 87 * 88 * @since 2.0 (imported from Google Collections Library) 89 */ 90 interface ValueDifference<V> { 91 /** 92 * Returns the value from the left map (possibly null). 93 */ 94 V leftValue(); 95 96 /** 97 * Returns the value from the right map (possibly null). 98 */ 99 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 boolean equals(@Nullable Object other); 106 107 /** 108 * The hash code equals the value 109 * {@code Arrays.asList(leftValue(), rightValue()).hashCode()}. 110 */ 111 @Override int hashCode(); 112 } 113 114 } 115
