All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.groupbyinc.common.apache.commons.collections4.MultiMap Maven / Gradle / Ivy

There is a newer version: 198
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.collections4;

import java.util.Collection;

/**
 * Defines a map that holds a collection of values against each key.
 * 

* A MultiMap is a Map with slightly different semantics. * Putting a value into the map will add the value to a Collection at that key. * Getting a value will return a Collection, holding all the values put to that key. *

* For example: *

 * MultiMap mhm = new MultiValueMap();
 * mhm.put(key, "A");
 * mhm.put(key, "B");
 * mhm.put(key, "C");
 * Collection coll = (Collection) mhm.get(key);
*

* coll will be a collection containing "A", "B", "C". *

* NOTE: Additional methods were added to this interface in Commons Collections 3.1. * These were added solely for documentation purposes and do not change the interface * as they were defined in the superinterface Map anyway. * * @since 2.0 * @version $Id: MultiMap.java 1683018 2015-06-01 22:41:31Z tn $ * @deprecated since 4.1, use {@link MultiValuedMap} instead */ @Deprecated public interface MultiMap extends IterableMap { /** * Removes a specific value from map. *

* The item is removed from the collection mapped to the specified key. * Other values attached to that key are unaffected. *

* If the last value for a key is removed, implementations typically * return null from a subsequent get(Object), however * they may choose to return an empty collection. * * @param key the key to remove from * @param item the item to remove * @return {@code true} if the mapping was removed, {@code false} otherwise * @throws UnsupportedOperationException if the map is unmodifiable * @throws ClassCastException if the key or value is of an invalid type * @throws NullPointerException if the key or value is null and null is invalid * @since 4.0 (signature in previous releases: V remove(K, V)) */ boolean removeMapping(K key, V item); //----------------------------------------------------------------------- /** * Gets the number of keys in this map. *

* Implementations typically return only the count of keys in the map * This cannot be mandated due to backwards compatibility of this interface. * * @return the number of key-collection mappings in this map */ int size(); /** * Gets the collection of values associated with the specified key. *

* The returned value will implement Collection. Implementations * are free to declare that they return Collection subclasses * such as List or Set. *

* Implementations typically return null if no values have * been mapped to the key, however the implementation may choose to * return an empty collection. *

* Implementations may choose to return a clone of the internal collection. * * @param key the key to retrieve * @return the Collection of values, implementations should * return null for no mapping, but may return an empty collection * @throws ClassCastException if the key is of an invalid type * @throws NullPointerException if the key is null and null keys are invalid */ Object get(Object key); // Cannot use get(K key) as that does not properly implement Map#get /** * Checks whether the map contains the value specified. *

* Implementations typically check all collections against all keys for the value. * This cannot be mandated due to backwards compatibility of this interface. * * @param value the value to search for * @return true if the map contains the value * @throws ClassCastException if the value is of an invalid type * @throws NullPointerException if the value is null and null value are invalid */ boolean containsValue(Object value); /** * Adds the value to the collection associated with the specified key. *

* Unlike a normal Map the previous value is not replaced. * Instead the new value is added to the collection stored against the key. * The collection may be a List, Set or other * collection dependent on implementation. * * @param key the key to store against * @param value the value to add to the collection at the key * @return typically the value added if the map changed and null if the map did not change * @throws UnsupportedOperationException if the map is unmodifiable * @throws ClassCastException if the key or value is of an invalid type * @throws NullPointerException if the key or value is null and null is invalid * @throws IllegalArgumentException if the key or value is invalid */ Object put(K key, Object value); /** * Removes all values associated with the specified key. *

* Implementations typically return null from a subsequent * get(Object), however they may choose to return an empty collection. * * @param key the key to remove values from * @return the Collection of values removed, implementations should * return null for no mapping found, but may return an empty collection * @throws UnsupportedOperationException if the map is unmodifiable * @throws ClassCastException if the key is of an invalid type * @throws NullPointerException if the key is null and null keys are invalid */ Object remove(Object key); // Cannot use remove(K key) as that does not properly implement Map#remove /** * Gets a collection containing all the values in the map. *

* Implementations typically return a collection containing the combination * of values from all keys. * This cannot be mandated due to backwards compatibility of this interface. * * @return a collection view of the values contained in this map */ Collection values(); }