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 */
017 package org.apache.commons.collections;
018
019 import java.util.Collection;
020 import java.util.Map;
021
022 /**
023 * Defines a map that holds a collection of values against each key.
024 * <p>
025 * A <code>MultiMap</code> is a Map with slightly different semantics.
026 * Putting a value into the map will add the value to a Collection at that key.
027 * Getting a value will return a Collection, holding all the values put to that key.
028 * <p>
029 * For example:
030 * <pre>
031 * MultiMap mhm = new MultiHashMap();
032 * mhm.put(key, "A");
033 * mhm.put(key, "B");
034 * mhm.put(key, "C");
035 * Collection coll = (Collection) mhm.get(key);</pre>
036 * <p>
037 * <code>coll</code> will be a collection containing "A", "B", "C".
038 * <p>
039 * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
040 * These were added solely for documentation purposes and do not change the interface
041 * as they were defined in the superinterface <code>Map</code> anyway.
042 *
043 * @since Commons Collections 2.0
044 * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
045 *
046 * @author Christopher Berry
047 * @author James Strachan
048 * @author Stephen Colebourne
049 */
050 public interface MultiMap extends Map {
051
052 /**
053 * Removes a specific value from map.
054 * <p>
055 * The item is removed from the collection mapped to the specified key.
056 * Other values attached to that key are unaffected.
057 * <p>
058 * If the last value for a key is removed, implementations typically
059 * return <code>null</code> from a subsequant <code>get(Object)</code>, however
060 * they may choose to return an empty collection.
061 *
062 * @param key the key to remove from
063 * @param item the item to remove
064 * @return the value removed (which was passed in), null if nothing removed
065 * @throws UnsupportedOperationException if the map is unmodifiable
066 * @throws ClassCastException if the key or value is of an invalid type
067 * @throws NullPointerException if the key or value is null and null is invalid
068 */
069 public Object remove(Object key, Object item);
070
071 //-----------------------------------------------------------------------
072 /**
073 * Gets the number of keys in this map.
074 * <p>
075 * Implementations typically return only the count of keys in the map
076 * This cannot be mandated due to backwards compatability of this interface.
077 *
078 * @return the number of key-collection mappings in this map
079 */
080 int size();
081
082 /**
083 * Gets the collection of values associated with the specified key.
084 * <p>
085 * The returned value will implement <code>Collection</code>. Implementations
086 * are free to declare that they return <code>Collection</code> subclasses
087 * such as <code>List</code> or <code>Set</code>.
088 * <p>
089 * Implementations typically return <code>null</code> if no values have
090 * been mapped to the key, however the implementation may choose to
091 * return an empty collection.
092 * <p>
093 * Implementations may choose to return a clone of the internal collection.
094 *
095 * @param key the key to retrieve
096 * @return the <code>Collection</code> of values, implementations should
097 * return <code>null</code> for no mapping, but may return an empty collection
098 * @throws ClassCastException if the key is of an invalid type
099 * @throws NullPointerException if the key is null and null keys are invalid
100 */
101 Object get(Object key);
102
103 /**
104 * Checks whether the map contains the value specified.
105 * <p>
106 * Implementations typically check all collections against all keys for the value.
107 * This cannot be mandated due to backwards compatability of this interface.
108 *
109 * @param value the value to search for
110 * @return true if the map contains the value
111 * @throws ClassCastException if the value is of an invalid type
112 * @throws NullPointerException if the value is null and null value are invalid
113 */
114 boolean containsValue(Object value);
115
116 /**
117 * Adds the value to the collection associated with the specified key.
118 * <p>
119 * Unlike a normal <code>Map</code> the previous value is not replaced.
120 * Instead the new value is added to the collection stored against the key.
121 * The collection may be a <code>List</code>, <code>Set</code> or other
122 * collection dependent on implementation.
123 *
124 * @param key the key to store against
125 * @param value the value to add to the collection at the key
126 * @return typically the value added if the map changed and null if the map did not change
127 * @throws UnsupportedOperationException if the map is unmodifiable
128 * @throws ClassCastException if the key or value is of an invalid type
129 * @throws NullPointerException if the key or value is null and null is invalid
130 * @throws IllegalArgumentException if the key or value is invalid
131 */
132 Object put(Object key, Object value);
133
134 /**
135 * Removes all values associated with the specified key.
136 * <p>
137 * Implementations typically return <code>null</code> from a subsequant
138 * <code>get(Object)</code>, however they may choose to return an empty collection.
139 *
140 * @param key the key to remove values from
141 * @return the <code>Collection</code> of values removed, implementations should
142 * return <code>null</code> for no mapping found, but may return an empty collection
143 * @throws UnsupportedOperationException if the map is unmodifiable
144 * @throws ClassCastException if the key is of an invalid type
145 * @throws NullPointerException if the key is null and null keys are invalid
146 */
147 Object remove(Object key);
148
149 /**
150 * Gets a collection containing all the values in the map.
151 * <p>
152 * Inplementations typically return a collection containing the combination
153 * of values from all keys.
154 * This cannot be mandated due to backwards compatability of this interface.
155 *
156 * @return a collection view of the values contained in this map
157 */
158 Collection values();
159
160 }