MultiMap


1   /*
2    *  Copyright 2001-2004 The Apache Software Foundation
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.apache.commons.collections;
17  
18  import java.util.Collection  ;
19  import java.util.Map  ;
20  
21  /** 
22   * Defines a map that holds a collection of values against each key.
23   * <p>
24   * A <code>MultiMap</code> is a Map with slightly different semantics.
25   * Putting a value into the map will add the value to a Collection at that key.
26   * Getting a value will return a Collection, holding all the values put to that key.
27   * <p>
28   * For example:
29   * <pre>
30   * MultiMap mhm = new MultiHashMap();
31   * mhm.put(key, "A");
32   * mhm.put(key, "B");
33   * mhm.put(key, "C");
34   * Collection coll = (Collection) mhm.get(key);</pre>
35   * <p>
36   * <code>coll</code> will be a collection containing "A", "B", "C".
37   * <p>
38   * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
39   * These were added solely for documentation purposes and do not change the interface
40   * as they were defined in the superinterface <code>Map</code> anyway.
41   *
42   * @since Commons Collections 2.0
43   * @version $Revision: 1.12 $ $Date: 2004/03/14 15:33:57 $
44   * 
45   * @author Christopher Berry
46   * @author James Strachan
47   * @author Stephen Colebourne
48   */
49  public interface MultiMap extends Map   {
50  
51      /**
52       * Removes a specific value from map.
53       * <p>
54       * The item is removed from the collection mapped to the specified key.
55       * Other values attached to that key are unaffected.
56       * <p>
57       * If the last value for a key is removed, implementations typically
58       * return <code>null</code> from a subsequant <code>get(Object)</code>, however
59       * they may choose to return an empty collection.
60       * 
61       * @param key  the key to remove from
62       * @param item  the item to remove
63       * @return the value removed (which was passed in), null if nothing removed
64       * @throws UnsupportedOperationException if the map is unmodifiable
65       * @throws ClassCastException if the key or value is of an invalid type
66       * @throws NullPointerException if the key or value is null and null is invalid
67       */
68      public Object   remove(Object   key, Object   item);
69  
70      //-----------------------------------------------------------------------
71      /**
72       * Gets the number of keys in this map.
73       * <p>
74       * Implementations typically return only the count of keys in the map
75       * This cannot be mandated due to backwards compatability of this interface.
76       *
77       * @return the number of key-collection mappings in this map
78       */
79      int size();
80  
81      /**
82       * Gets the collection of values associated with the specified key.
83       * <p>
84       * The returned value will implement <code>Collection</code>. Implementations
85       * are free to declare that they return <code>Collection</code> subclasses
86       * such as <code>List</code> or <code>Set</code>.
87       * <p>
88       * Implementations typically return <code>null</code> if no values have
89       * been mapped to the key, however the implementation may choose to
90       * return an empty collection.
91       * <p>
92       * Implementations may choose to return a clone of the internal collection.
93       *
94       * @param key  the key to retrieve
95       * @return the <code>Collection</code> of values, implementations should
96       *  return <code>null</code> for no mapping, but may return an empty collection
97       * @throws ClassCastException if the key is of an invalid type
98       * @throws NullPointerException if the key is null and null keys are invalid
99       */
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 }
160
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags