Home | History | Annotate | Download | only in collect
      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