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}