Interface representing key-value mappings, containing a possible other map that may be respected in lookup operations.

ChildMap.java

package io.github.sauranbone.plang.core.abstraction;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.function.Function;

/**
 * Interface representing key-value mappings, containing possible parent
 * maps whose are not mutated through any operations in a child map.
 * <p>If a parent is respected in operations, typically the parent's
 * parents are also respected, quite possibly leading to recursion. That
 * map will always have the highest precedence in those operations, then
 * its potential parent and then the parent's parents and so forth.
 *
 * @author Vinzent Zeband
 * @version 16:31 CET, 10.06.2022
 * @see #getParent()
 * @since 1.0
 */
public interface ChildMap<K, V> {

    boolean DEFAULT_DEEP = true;

    /**
     * Returns the independent parent of this child map.
     * <p>A child map that is used as a parent is never mutated through
     * operations on a map obtaining that child map as parent.
     * <p>Methods that may respect the parent are usually having a boolean
     * as a required parameter, that states whether the parent's mappings
     * are respected in that operation. That parameter is primarily called
     * or referred to as the {@code "deep"}-boolean.
     * <p>When respected in operations, typically the parent's parents are
     * also respected, quite possibly leading to recursion. This map will
     * always have the highest precedence in those operations, then the
     * parent and then the parent's parents and so forth.
     *
     * @return the potential parent of this child map, that may be
     * respected in lookup operations, {@code nullable}
     */
    @Nullable
    ChildMap<K, V> getParent();

    /**
     * Returns true if this map contains a parent as composition.
     *
     * @return true if this map has a parent
     * @see #getParent()
     */
    boolean hasParent();

    /**
     * Defines an association with the output of given function to given
     * key, if given key does not have an association. Optional operation.
     * <p>If key already is mapped, the value of that mapping is returned
     * and given function not called. Thus, this method will not mutate
     * this instance. Otherwise, if key is not mapped within this map when
     * this operation is performed, given function is called and its output
     * is associated to the key that was passed as argument to that
     * invocation. The result of that operation, so the output of the
     * invocation of given function, is returned.
     * <p>If {@code deep} is true and given key is mapped in this or any
     * of this {@link #getParent() parents}, the value associated with
     * given key having the highest precedence is returned. Otherwise, only
     * this instance is respected.
     *
     * @param key      the key to lookup and possibly associate to
     * @param supplier the value supplying function, taking in the key to
     *                 which the output will be mapped, {@code not null}
     * @param deep     true to also include all parents of this map. False
     *                 to only respect the mappings contained in this map.
     * @return the value associated to given key, {@code nullable}
     */
    @Nullable
    V define(K key, @Nonnull Function<K, V> supplier, boolean deep);

    /**
     * Defines an association with the output of given function to given
     * key, if given key does not have an association. Optional operation.
     * <p>If key already is mapped, the value of that mapping is returned
     * and given function not called. Thus, this method will not mutate
     * this instance. Otherwise, if key is not mapped within this map when
     * this operation is performed, given function is called and its output
     * is associated to the key that was passed as argument to that
     * invocation. The result of that operation, so the output of the
     * invocation of given function, is returned.
     *
     * @param key      the key to lookup and possibly associate to
     * @param supplier the value supplying function, taking in the key to
     *                 which the output will be mapped, {@code not null}
     * @return the value associated to given key, {@code nullable}
     * @implSpec The default implementation returns the result of the
     * invocation of this {@link #define(Object, Function, boolean)},
     * passing in given arguments in order and {@link #DEFAULT_DEEP} as
     * deep-boolean.
     * @see #define(Object, Function, boolean)
     * @see #DEFAULT_DEEP
     */
    @Nullable
    default V define(K key, @Nonnull Function<K, V> supplier) {
        return define(key, supplier, DEFAULT_DEEP);
    }

    /**
     * Maps given value and key as pair into this map, returning the
     * previous value associated with given key. Optional operation.
     * <p>No parent is mutated nor respected in this operation, as only
     * this map is possibly mutated through a direct call. The resulting
     * mapping will have the highest precedence in this map, being the same
     * as every other mapping in this map, excluding any parent.
     *
     * @param key   the key that is associated to
     * @param value the value to be associated to given key
     * @return the with previously with given key associated value
     * @throws NullPointerException if {@code key} is null and the
     *                              underlying implementation does not
     *                              permit null keys
     * @see #define(Object, Function, boolean)
     * @see #getParent()
     */
    @Nullable
    V set(K key, V value);

    /**
     * Returns the with given key mapped value having the highest
     * precedence in this map, including all parents if deep is true.
     * <p>If key is not mapped in any respected map, null is returned.
     *
     * @param key  the key to lookup
     * @param deep true to also include all parents of this map. False to
     *             only respect the mappings contained in this map.
     * @return the with given key associated value, having the highest
     * precedence, {@code nullable}
     * @throws NullPointerException if {@code key} is null and the
     *                              underlying implementation does not
     *                              permit null keys
     * @see #getParent()
     * @see #set(Object, Object)
     * @see #define(Object, Function, boolean)
     */
    @Nullable
    V get(K key, boolean deep);

    /**
     * Returns the with given key mapped value having the highest
     * precedence in this map, including all parents if deep is true.
     * <p>If key is not mapped in any respected map, an exception is
     * thrown.
     *
     * @param key  the key to lookup
     * @param deep true to also include all parents of this map. False to
     *             only respect the mappings contained in this map.
     * @return the with given key associated value, having the highest
     * precedence
     * @throws NullPointerException     if {@code key} is null and the
     *                                  underlying implementation does not
     *                                  permit null keys
     * @throws IllegalArgumentException if given key has no mapping in any
     *                                  respected map
     * @see #getParent()
     * @see #get(Object, boolean)
     * @see #set(Object, Object)
     * @see #define(Object, Function, boolean)
     */
    @Nullable
    V require(K key, boolean deep);

    /**
     * Returns true if given key is mapped in this map, or any of this
     * parents if deep is true.
     *
     * @param key  the key to lookup
     * @param deep true to also include all parents of this map. False to
     *             only respect the mappings contained in this map.
     * @return true if given key is mapped in any respected map
     * @throws NullPointerException if {@code key} is null and the
     *                              underlying implementation does not
     *                              permit null keys
     */
    boolean containsKey(K key, boolean deep);

    /**
     * Returns true if given value is mapped with a key in this map, or any
     * of this parents if deep is true.
     *
     * @param value the value to lookup
     * @param deep  true to also include all parents of this map. False to
     *              only respect the mappings contained in this map.
     * @return true if this map or any other respected map has a mapping,
     * containing a value being given value
     */
    boolean containsValue(V value, boolean deep);

    /**
     * Returns an immutable collection containing all value mappings in
     * this map, including every mapping of all parents if deep is true.
     * <p>The returning value collection is quite possibly derived from
     * the entries contained in all respected maps. If there is two or more
     * values in different respected maps all having the same mapped key,
     * only the value with higher precedence is added and the others
     * ignored.
     *
     * @param deep true to also include all parents of this map. False to
     *             only respect the mappings contained in this map.
     * @return an immutable collection containing all value mappings of the
     * respected maps, {@code not null}
     * @see #getParent()
     */
    @Nonnull
    Collection<V> values(boolean deep);

    /**
     * Returns a set of all key mappings in this map, including every key
     * that is mapped in all parents if deep is true.
     * <p>If multiple keys are the same in different respected maps, the
     * key with the highest precedence is used and the rest ignored.
     *
     * @param deep true to also include all parents of this map. False to
     *             only respect the mappings contained in this map.
     * @return all key mappings contained in the respected maps,
     * {@code not null}
     * @see #getParent()
     */
    @Nonnull
    Set<K> keySet(boolean deep);

    /**
     * Returns a set of all mappings in this map, including every mapping
     * in all parents if deep is true.
     * <p>If multiple keys are the same in different maps, the mapping
     * having the highest precedence is used and the rest ignored.
     *
     * @param deep true to also include all parents of this map. False to
     *             only respect the mappings contained in this map.
     * @return all key-value mappings contained in the respected maps,
     * {@code not null}
     */
    @Nonnull
    Set<Map.Entry<K, V>> entrySet(boolean deep);

}