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);

    }

}