    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.collections4;
    018
    019import java.util.Collection;
    020
    021/**
    022 * Defines a map that holds a collection of values against each key.
    023 * <p>
    024 * A {@code MultiMap} is a Map with slightly different semantics.
    025 * Putting a value into the map will add the value to a Collection at that key.
    026 * Getting a value will return a Collection, holding all the values put to that key.
    027 * </p>
    028 * <p>
    029 * For example:
    030 * </p>
    031 * <pre>
    032 * MultiMap mhm = new MultiValueMap();
    033 * mhm.put(key, "A");
    034 * mhm.put(key, "B");
    035 * mhm.put(key, "C");
    036 * Collection coll = (Collection) mhm.get(key);</pre>
    037 * <p>
    038 * {@code coll} will be a collection containing "A", "B", "C".
    039 * </p>
    040 * <p>
    041 * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
    042 * These were added solely for documentation purposes and do not change the interface
    043 * as they were defined in the superinterface {@code Map} anyway.
    044 * </p>
    045 *
    046 * @param <K> the type of the keys in this map
    047 * @param <V> the type of the values in this map
    048 * @since 2.0
    049 * @deprecated since 4.1, use {@link MultiValuedMap} instead
    050 */
    051@Deprecated
    052public interface MultiMap<K, V> extends IterableMap<K, Object> {
    053
    054    /**
    055     * Checks whether the map contains the value specified.
    056     * <p>
    057     * Implementations typically check all collections against all keys for the value.
    058     * This cannot be mandated due to backwards compatibility of this interface.
    059     * </p>
    060     *
    061     * @param value  the value to search for
    062     * @return true if the map contains the value
    063     * @throws ClassCastException if the value is of an invalid type
    064     * @throws NullPointerException if the value is null and null value are invalid
    065     */
    066    @Override
    067    boolean containsValue(Object value);
    068
    069    /**
    070     * Gets the collection of values associated with the specified key.
    071     * <p>
    072     * The returned value will implement {@code Collection}. Implementations
    073     * are free to declare that they return {@code Collection} subclasses
    074     * such as {@code List} or {@code Set}.
    075     * </p>
    076     * <p>
    077     * Implementations typically return {@code null} if no values have
    078     * been mapped to the key, however the implementation may choose to
    079     * return an empty collection.
    080     * </p>
    081     * <p>
    082     * Implementations may choose to return a clone of the internal collection.
    083     * </p>
    084     *
    085     * @param key  the key to retrieve
    086     * @return the {@code Collection} of values, implementations should
    087     *  return {@code null} for no mapping, but may return an empty collection
    088     * @throws ClassCastException if the key is of an invalid type
    089     * @throws NullPointerException if the key is null and null keys are invalid
    090     */
    091    @Override
    092    Object get(Object key); // Cannot use get(K key) as that does not properly implement Map#get
    093
    094    /**
    095     * Adds the value to the collection associated with the specified key.
    096     * <p>
    097     * Unlike a normal {@code Map} the previous value is not replaced.
    098     * Instead, the new value is added to the collection stored against the key.
    099     * The collection may be a {@code List}, {@code Set} or other
    100     * collection dependent on implementation.
    101     * </p>
    102     *
    103     * @param key  the key to store against
    104     * @param value  the value to add to the collection at the key
    105     * @return typically the value added if the map changed and null if the map did not change
    106     * @throws UnsupportedOperationException if the map is unmodifiable
    107     * @throws ClassCastException if the key or value is of an invalid type
    108     * @throws NullPointerException if the key or value is null and null is invalid
    109     * @throws IllegalArgumentException if the key or value is invalid
    110     */
    111    @Override
    112    Object put(K key, Object value);
    113
    114    /**
    115     * Removes all values associated with the specified key.
    116     * <p>
    117     * Implementations typically return {@code null} from a subsequent
    118     * {@code get(Object)}, however they may choose to return an empty collection.
    119     * </p>
    120     *
    121     * @param key  the key to remove values from
    122     * @return the {@code Collection} of values removed, implementations should
    123     *  return {@code null} for no mapping found, but may return an empty collection
    124     * @throws UnsupportedOperationException if the map is unmodifiable
    125     * @throws ClassCastException if the key is of an invalid type
    126     * @throws NullPointerException if the key is null and null keys are invalid
    127     */
    128    @Override
    129    Object remove(Object key); // Cannot use remove(K key) as that does not properly implement Map#remove
    130
    131    /**
    132     * Removes a specific value from map.
    133     * <p>
    134     * The item is removed from the collection mapped to the specified key.
    135     * Other values attached to that key are unaffected.
    136     * </p>
    137     * <p>
    138     * If the last value for a key is removed, implementations typically
    139     * return {@code null} from a subsequent {@code get(Object)}, however
    140     * they may choose to return an empty collection.
    141     * </p>
    142     *
    143     * @param key  the key to remove from
    144     * @param item  the item to remove
    145     * @return {@code true} if the mapping was removed, {@code false} otherwise
    146     * @throws UnsupportedOperationException if the map is unmodifiable
    147     * @throws ClassCastException if the key or value is of an invalid type
    148     * @throws NullPointerException if the key or value is null and null is invalid
    149     * @since 4.0 (signature in previous releases: V remove(K, V))
    150     */
    151    boolean removeMapping(K key, V item);
    152
    153    /**
    154     * Gets the number of keys in this map.
    155     * <p>
    156     * Implementations typically return only the count of keys in the map
    157     * This cannot be mandated due to backwards compatibility of this interface.
    158     * </p>
    159     *
    160     * @return the number of key-collection mappings in this map
    161     */
    162    @Override
    163    int size();
    164
    165    /**
    166     * Gets a collection containing all the values in the map.
    167     * <p>
    168     * Implementations typically return a collection containing the combination
    169     * of values from all keys.
    170     * This cannot be mandated due to backwards compatibility of this interface.
    171     * </p>
    172     *
    173     * @return a collection view of the values contained in this map
    174     */
    175    @Override
    176    Collection<Object> values();
    177
    178}