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