Java tutorial
/* * Copyright 2001-2004 The Apache Software Foundation * * Licensed 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.collections; import java.util.Collection; import java.util.Map; /** * Defines a map that holds a collection of values against each key. * <p> * A <code>MultiMap</code> 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. * <p> * For example: * <pre> * MultiMap mhm = new MultiHashMap(); * mhm.put(key, "A"); * mhm.put(key, "B"); * mhm.put(key, "C"); * Collection coll = (Collection) mhm.get(key);</pre> * <p> * <code>coll</code> will be a collection containing "A", "B", "C". * <p> * 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 <code>Map</code> anyway. * * @since Commons Collections 2.0 * @version $Revision: 1.12 $ $Date: 2004/03/14 15:33:57 $ * * @author Christopher Berry * @author James Strachan * @author Stephen Colebourne */ public interface MultiMap extends Map { /** * Removes a specific value from map. * <p> * The item is removed from the collection mapped to the specified key. * Other values attached to that key are unaffected. * <p> * If the last value for a key is removed, implementations typically * return <code>null</code> from a subsequant <code>get(Object)</code>, however * they may choose to return an empty collection. * * @param key the key to remove from * @param item the item to remove * @return the value removed (which was passed in), null if nothing removed * @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 */ public Object remove(Object key, Object item); //----------------------------------------------------------------------- /** * Gets the number of keys in this map. * <p> * Implementations typically return only the count of keys in the map * This cannot be mandated due to backwards compatability 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. * <p> * The returned value will implement <code>Collection</code>. Implementations * are free to declare that they return <code>Collection</code> subclasses * such as <code>List</code> or <code>Set</code>. * <p> * Implementations typically return <code>null</code> if no values have * been mapped to the key, however the implementation may choose to * return an empty collection. * <p> * Implementations may choose to return a clone of the internal collection. * * @param key the key to retrieve * @return the <code>Collection</code> of values, implementations should * return <code>null</code> 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); /** * Checks whether the map contains the value specified. * <p> * Implementations typically check all collections against all keys for the value. * This cannot be mandated due to backwards compatability 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. * <p> * Unlike a normal <code>Map</code> the previous value is not replaced. * Instead the new value is added to the collection stored against the key. * The collection may be a <code>List</code>, <code>Set</code> 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(Object key, Object value); /** * Removes all values associated with the specified key. * <p> * Implementations typically return <code>null</code> from a subsequant * <code>get(Object)</code>, however they may choose to return an empty collection. * * @param key the key to remove values from * @return the <code>Collection</code> of values removed, implementations should * return <code>null</code> 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); /** * Gets a collection containing all the values in the map. * <p> * Inplementations typically return a collection containing the combination * of values from all keys. * This cannot be mandated due to backwards compatability of this interface. * * @return a collection view of the values contained in this map */ Collection values(); }