001: /*
002: * Copyright 2001-2004 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.collections;
017:
018: import java.util.Collection;
019: import java.util.Map;
020:
021: /**
022: * Defines a map that holds a collection of values against each key.
023: * <p>
024: * A <code>MultiMap</code> 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: * For example:
029: * <pre>
030: * MultiMap mhm = new MultiHashMap();
031: * mhm.put(key, "A");
032: * mhm.put(key, "B");
033: * mhm.put(key, "C");
034: * Collection coll = (Collection) mhm.get(key);</pre>
035: * <p>
036: * <code>coll</code> will be a collection containing "A", "B", "C".
037: * <p>
038: * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
039: * These were added solely for documentation purposes and do not change the interface
040: * as they were defined in the superinterface <code>Map</code> anyway.
041: *
042: * @since Commons Collections 2.0
043: * @version $Revision: 155406 $ $Date: 2005-02-26 12:55:26 +0000 (Sat, 26 Feb 2005) $
044: *
045: * @author Christopher Berry
046: * @author James Strachan
047: * @author Stephen Colebourne
048: */
049: public interface MultiMap extends Map {
050:
051: /**
052: * Removes a specific value from map.
053: * <p>
054: * The item is removed from the collection mapped to the specified key.
055: * Other values attached to that key are unaffected.
056: * <p>
057: * If the last value for a key is removed, implementations typically
058: * return <code>null</code> from a subsequant <code>get(Object)</code>, however
059: * they may choose to return an empty collection.
060: *
061: * @param key the key to remove from
062: * @param item the item to remove
063: * @return the value removed (which was passed in), null if nothing removed
064: * @throws UnsupportedOperationException if the map is unmodifiable
065: * @throws ClassCastException if the key or value is of an invalid type
066: * @throws NullPointerException if the key or value is null and null is invalid
067: */
068: public Object remove(Object key, Object item);
069:
070: //-----------------------------------------------------------------------
071: /**
072: * Gets the number of keys in this map.
073: * <p>
074: * Implementations typically return only the count of keys in the map
075: * This cannot be mandated due to backwards compatability of this interface.
076: *
077: * @return the number of key-collection mappings in this map
078: */
079: int size();
080:
081: /**
082: * Gets the collection of values associated with the specified key.
083: * <p>
084: * The returned value will implement <code>Collection</code>. Implementations
085: * are free to declare that they return <code>Collection</code> subclasses
086: * such as <code>List</code> or <code>Set</code>.
087: * <p>
088: * Implementations typically return <code>null</code> if no values have
089: * been mapped to the key, however the implementation may choose to
090: * return an empty collection.
091: * <p>
092: * Implementations may choose to return a clone of the internal collection.
093: *
094: * @param key the key to retrieve
095: * @return the <code>Collection</code> of values, implementations should
096: * return <code>null</code> for no mapping, but may return an empty collection
097: * @throws ClassCastException if the key is of an invalid type
098: * @throws NullPointerException if the key is null and null keys are invalid
099: */
100: Object get(Object key);
101:
102: /**
103: * Checks whether the map contains the value specified.
104: * <p>
105: * Implementations typically check all collections against all keys for the value.
106: * This cannot be mandated due to backwards compatability of this interface.
107: *
108: * @param value the value to search for
109: * @return true if the map contains the value
110: * @throws ClassCastException if the value is of an invalid type
111: * @throws NullPointerException if the value is null and null value are invalid
112: */
113: boolean containsValue(Object value);
114:
115: /**
116: * Adds the value to the collection associated with the specified key.
117: * <p>
118: * Unlike a normal <code>Map</code> the previous value is not replaced.
119: * Instead the new value is added to the collection stored against the key.
120: * The collection may be a <code>List</code>, <code>Set</code> or other
121: * collection dependent on implementation.
122: *
123: * @param key the key to store against
124: * @param value the value to add to the collection at the key
125: * @return typically the value added if the map changed and null if the map did not change
126: * @throws UnsupportedOperationException if the map is unmodifiable
127: * @throws ClassCastException if the key or value is of an invalid type
128: * @throws NullPointerException if the key or value is null and null is invalid
129: * @throws IllegalArgumentException if the key or value is invalid
130: */
131: Object put(Object key, Object value);
132:
133: /**
134: * Removes all values associated with the specified key.
135: * <p>
136: * Implementations typically return <code>null</code> from a subsequant
137: * <code>get(Object)</code>, however they may choose to return an empty collection.
138: *
139: * @param key the key to remove values from
140: * @return the <code>Collection</code> of values removed, implementations should
141: * return <code>null</code> for no mapping found, but may return an empty collection
142: * @throws UnsupportedOperationException if the map is unmodifiable
143: * @throws ClassCastException if the key is of an invalid type
144: * @throws NullPointerException if the key is null and null keys are invalid
145: */
146: Object remove(Object key);
147:
148: /**
149: * Gets a collection containing all the values in the map.
150: * <p>
151: * Inplementations typically return a collection containing the combination
152: * of values from all keys.
153: * This cannot be mandated due to backwards compatability of this interface.
154: *
155: * @return a collection view of the values contained in this map
156: */
157: Collection values();
158:
159: }
|