Dépôt officiel du code source de l'ERP OpenConcerto

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 * 
 * Copyright 2011 OpenConcerto, by ILM Informatique. All rights reserved.
 * 
 * The contents of this file are subject to the terms of the GNU General Public License Version 3
 * only ("GPL"). You may not use this file except in compliance with the License. You can obtain a
 * copy of the License at http://www.gnu.org/licenses/gpl-3.0.html See the License for the specific
 * language governing permissions and limitations under the License.
 * 
 * When distributing the software, include this License Header Notice in each file.
 */
 
 package org.openconcerto.utils;

import org.openconcerto.utils.CollectionMap2.Mode;

import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import java.util.function.Function;

public interface CollectionMap2Itf<K, C extends Collection<V>, V> extends Map<K, C> {

    public static interface ListMapItf<K, V> extends CollectionMap2Itf<K, List<V>, V> {
        /**
         * Change this instance and return an unmodifiable Map view. After this method, this
         * instance shouldn't be modified, e.g. if a new entry (with a modifiable collection) is
         * added then the returned object will be able to modify it. Contrary to
         * {@link ListMap#unmodifiableMap(ListMapItf)}, the returned object doesn't allocate any
         * memory.
         * 
         * @return an unmodifiable Map view.
         * @see CollectionMap2Itf#convertToUnmodifiableMap(Function)
         */
        public default Map<K, List<V>> convertToUnmodifiableMap() {
            return convertToUnmodifiableMap(Collections::unmodifiableList);
        }
    }

    public static interface SetMapItf<K, V> extends CollectionMap2Itf<K, Set<V>, V> {
        /**
         * Change this instance and return an unmodifiable Map view. After this method, this
         * instance shouldn't be modified, e.g. if a new entry (with a modifiable collection) is
         * added then the returned object will be able to modify it. Contrary to
         * {@link SetMap#unmodifiableMap(ListMapItf)}, the returned object doesn't allocate any
         * memory.
         * 
         * @return an unmodifiable Map view.
         * @see CollectionMap2Itf#convertToUnmodifiableMap(Function)
         */
        public default Map<K, Set<V>> convertToUnmodifiableMap() {
            return convertToUnmodifiableMap(Collections::unmodifiableSet);
        }
    }

    public Mode getMode();

    public boolean isEmptyCollSameAsNoColl();

    public C getNonNull(K key);

    /**
     * Get the collection mapped to the passed key. Note : <code>get(key, true, true)</code> is
     * equivalent to <code>get(key)</code>.
     * 
     * @param key the key whose associated value is to be returned.
     * @param nullIfMissing only relevant if the key isn't contained : if <code>true</code>
     *        <code>null</code> will be returned, otherwise an empty collection.
     * @param nullIfPresent only relevant if the key is mapped to <code>null</code> : if
     *        <code>true</code> <code>null</code> will be returned, otherwise an empty collection.
     * @return the non {@code null} value to which the specified key is mapped, otherwise
     *         {@code null} or empty collection depending on the other parameters.
     */
    public C get(Object key, final boolean nullIfMissing, final boolean nullIfPresent);

    public C getCollection(Object key);

    /**
     * Returns <tt>true</tt> if the collection mapped to the passed key contains the specified
     * element.
     * 
     * @param key the key.
     * @param element element whose presence in the collection is to be tested.
     * @return <tt>true</tt> if the collection mapped to the passed key contains the specified
     *         element or if the key exists, its collection is <code>null</code> and the
     *         {@link #getMode() mode} is {@link Mode#NULL_MEANS_ALL} <br>
     *         <code>false</code> if <code>!this.containsKey(key)</code>.
     * @throws NullPointerException if the key exists, its collection is <code>null</code> and the
     *         {@link #getMode() mode} is not {@link Mode#NULL_MEANS_ALL}.
     */
    public boolean containsInCollection(K key, V element) throws NullPointerException;

    /**
     * Returns a {@link Collection} view of all the values contained in this map. The collection is
     * backed by the map, so changes to the map are reflected in the collection, and vice-versa. If
     * the map is modified while an iteration over the collection is in progress (except through the
     * iterator's own <tt>remove</tt> operation), the results of the iteration are undefined. The
     * collection supports element removal, which removes the corresponding values from the map, via
     * the <tt>Iterator.remove</tt>, <tt>Collection.remove</tt>, <tt>removeAll</tt>,
     * <tt>retainAll</tt> and <tt>clear</tt> operations. Note that it doesn't remove entries only
     * values : keySet() doesn't change, use {@link #removeAllEmptyCollections()} and
     * {@link #removeAllNullCollections()} afterwards. It does not support the <tt>add</tt> or
     * <tt>addAll</tt> operations.
     * 
     * @return a view all values in all entries, <code>null</code> collections are ignored.
     */
    public Collection<V> allValues();

    // copy passed collection
    public C putCollection(final K key, final Collection<? extends V> value);

    public boolean add(final K k, final V v);

    public boolean addAll(final K k, final Collection<? extends V> v);

    /**
     * Call {@link #addAll(Object, Collection)} for each entry.
     * 
     * @param mm the collection map to merge.
     */
    public void merge(final Map<? extends K, ? extends Collection<? extends V>> mm);

    /**
     * Call {@link #add(Object, Object)} for each entry.
     * 
     * @param scalarMap the map to merge.
     */
    public void mergeScalarMap(final Map<? extends K, ? extends V> scalarMap);

    // cannot be called just "remove" since it conflicts with the new method in java 8
    public boolean removeOne(final K k, final V v);

    public boolean removeAllInstancesOfItem(final K k, final V v);

    public boolean removeAll(final K k, final Collection<? extends V> v);

    public boolean removeAll(final Map<? extends K, ? extends Collection<? extends V>> mm);

    public boolean removeAllScalar(final Map<? extends K, ? extends V> m);

    public Set<K> removeAllEmptyCollections();

    public Set<K> removeAllNullCollections();

    public default void replaceAllNonNullValues(final Function<? super C, ? extends C> function) {
        this.replaceAll((k, v) -> v == null ? null : function.apply(v));
    }

    /**
     * Change this instance and return an unmodifiable Map view. After this method, this instance
     * shouldn't be modified, e.g. if a new entry (with a modifiable collection) is added then the
     * returned object will be able to modify it. The returned object doesn't allocate any memory.
     * 
     * @param toUnmodifiable how to replace collections with unmodifiable views, never passed
     *        <code>null</code>.
     * @return an unmodifiable Map view.
     * @see SetMapItf#convertToUnmodifiableMap()
     * @see ListMapItf#convertToUnmodifiableMap()
     */
    public default Map<K, C> convertToUnmodifiableMap(final Function<? super C, ? extends C> toUnmodifiable) {
        this.replaceAllNonNullValues(Objects.requireNonNull(toUnmodifiable));
        return Collections.unmodifiableMap(this);
    }
}