IMMUTABLE_TREE_R0: ImmMap.java

package org.sophie2.base.commons.util;

import java.util.Comparator;

/**
 * Interface that provides necessary functionality for immutable map
 * 
 * @author stefan
 * 
 * @param <K>
 *            Type of the key.
 * @param <V>
 *            Type of the value.
 * @extends {@link ImmCollection}
 */
public interface ImmMap<K, V> extends ImmCollection<ImmMap.ImmEntry<K, V>> {
        /**
         * Inner class that is used for storing relation key - value.
         * 
         * @author stefan
         * 
         * @param <K>
         * @param <V>
         */
        public static class ImmEntry<K, V> {
                private final K key;
                private final V value;

                /**
                 * @param key
                 * @param data
                 */
                public ImmEntry(K key, V data) {
                        this.key = key;
                        this.value = data;
                }

                /**
                 * Returns key.
                 * 
                 * @return key
                 */
                public K getKey() {
                        return this.key;
                }

                /**
                 * Returns value.
                 * 
                 * @return value
                 */
                public V getValue() {
                        return this.value;
                }

                @Override
                public String toString() {
                        return ("(" + this.key.toString() + ", " + this.value.toString() + ")");
                }
        }

        /**
         * Gets value from {@link ImmMap.ImmEntry} that has key.
         * 
         * @param key
         * @return value for a given key.
         */
        V get(K key);

        /**
         * Puts value at the {@link ImmMap.ImmEntry} that has key.
         * 
         * @param key
         * @param value
         * @return new {@link ImmMap} with all changes applied.
         */
        ImmMap<K, V> put(K key, V value);

        /**
         * @param key
         * @return boolean If map contains given key
         */
        boolean contains(K key);

        /**
         * Removes {@link ImmMap.ImmEntry} from the map that has key.
         * 
         * @param key
         * @return new {@link ImmMap} with all changes applied.
         */
        ImmMap<K, V> remove(K key);

        /**
         * Gets the {@link Comparator} used to arrange elements in the set by keys.
         * 
         * @return {@link Comparator}.
         */
        Comparator<K> getComparator();

        /**
         * Gives sub {@link ImmMap} of the current <code>ImmMap</code> (including)
         * <var>fromKey</var> and (excluding) <var>toKey</var>
         * 
         * @param fromKey
         * @param toKey
         * @return new {@link ImmMap} containing elements in the given range.
         */
        ImmMap<K, V> subMap(K fromKey, K toKey);
}