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. import java.util.Collection;
  18. import java.util.Map;
  19. /**
  20. * Defines a map that holds a collection of values against each key.
  21. * <p>
  22. * A <code>MultiMap</code> is a Map with slightly different semantics.
  23. * Putting a value into the map will add the value to a Collection at that key.
  24. * Getting a value will return a Collection, holding all the values put to that key.
  25. * <p>
  26. * For example:
  27. * <pre>
  28. * MultiMap mhm = new MultiHashMap();
  29. * mhm.put(key, "A");
  30. * mhm.put(key, "B");
  31. * mhm.put(key, "C");
  32. * Collection coll = (Collection) mhm.get(key);</pre>
  33. * <p>
  34. * <code>coll</code> will be a collection containing "A", "B", "C".
  35. * <p>
  36. * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
  37. * These were added solely for documentation purposes and do not change the interface
  38. * as they were defined in the superinterface <code>Map</code> anyway.
  39. *
  40. * @since Commons Collections 2.0
  41. * @version $Revision: 1.12 $ $Date: 2004/03/14 15:33:57 $
  42. *
  43. * @author Christopher Berry
  44. * @author James Strachan
  45. * @author Stephen Colebourne
  46. */
  47. public interface MultiMap extends Map {
  48. /**
  49. * Removes a specific value from map.
  50. * <p>
  51. * The item is removed from the collection mapped to the specified key.
  52. * Other values attached to that key are unaffected.
  53. * <p>
  54. * If the last value for a key is removed, implementations typically
  55. * return <code>null</code> from a subsequant <code>get(Object)</code>, however
  56. * they may choose to return an empty collection.
  57. *
  58. * @param key the key to remove from
  59. * @param item the item to remove
  60. * @return the value removed (which was passed in), null if nothing removed
  61. * @throws UnsupportedOperationException if the map is unmodifiable
  62. * @throws ClassCastException if the key or value is of an invalid type
  63. * @throws NullPointerException if the key or value is null and null is invalid
  64. */
  65. public Object remove(Object key, Object item);
  66. //-----------------------------------------------------------------------
  67. /**
  68. * Gets the number of keys in this map.
  69. * <p>
  70. * Implementations typically return only the count of keys in the map
  71. * This cannot be mandated due to backwards compatability of this interface.
  72. *
  73. * @return the number of key-collection mappings in this map
  74. */
  75. int size();
  76. /**
  77. * Gets the collection of values associated with the specified key.
  78. * <p>
  79. * The returned value will implement <code>Collection</code>. Implementations
  80. * are free to declare that they return <code>Collection</code> subclasses
  81. * such as <code>List</code> or <code>Set</code>.
  82. * <p>
  83. * Implementations typically return <code>null</code> if no values have
  84. * been mapped to the key, however the implementation may choose to
  85. * return an empty collection.
  86. * <p>
  87. * Implementations may choose to return a clone of the internal collection.
  88. *
  89. * @param key the key to retrieve
  90. * @return the <code>Collection</code> of values, implementations should
  91. * return <code>null</code> for no mapping, but may return an empty collection
  92. * @throws ClassCastException if the key is of an invalid type
  93. * @throws NullPointerException if the key is null and null keys are invalid
  94. */
  95. Object get(Object key);
  96. /**
  97. * Checks whether the map contains the value specified.
  98. * <p>
  99. * Implementations typically check all collections against all keys for the value.
  100. * This cannot be mandated due to backwards compatability of this interface.
  101. *
  102. * @param value the value to search for
  103. * @return true if the map contains the value
  104. * @throws ClassCastException if the value is of an invalid type
  105. * @throws NullPointerException if the value is null and null value are invalid
  106. */
  107. boolean containsValue(Object value);
  108. /**
  109. * Adds the value to the collection associated with the specified key.
  110. * <p>
  111. * Unlike a normal <code>Map</code> the previous value is not replaced.
  112. * Instead the new value is added to the collection stored against the key.
  113. * The collection may be a <code>List</code>, <code>Set</code> or other
  114. * collection dependent on implementation.
  115. *
  116. * @param key the key to store against
  117. * @param value the value to add to the collection at the key
  118. * @return typically the value added if the map changed and null if the map did not change
  119. * @throws UnsupportedOperationException if the map is unmodifiable
  120. * @throws ClassCastException if the key or value is of an invalid type
  121. * @throws NullPointerException if the key or value is null and null is invalid
  122. * @throws IllegalArgumentException if the key or value is invalid
  123. */
  124. Object put(Object key, Object value);
  125. /**
  126. * Removes all values associated with the specified key.
  127. * <p>
  128. * Implementations typically return <code>null</code> from a subsequant
  129. * <code>get(Object)</code>, however they may choose to return an empty collection.
  130. *
  131. * @param key the key to remove values from
  132. * @return the <code>Collection</code> of values removed, implementations should
  133. * return <code>null</code> for no mapping found, but may return an empty collection
  134. * @throws UnsupportedOperationException if the map is unmodifiable
  135. * @throws ClassCastException if the key is of an invalid type
  136. * @throws NullPointerException if the key is null and null keys are invalid
  137. */
  138. Object remove(Object key);
  139. /**
  140. * Gets a collection containing all the values in the map.
  141. * <p>
  142. * Inplementations typically return a collection containing the combination
  143. * of values from all keys.
  144. * This cannot be mandated due to backwards compatability of this interface.
  145. *
  146. * @return a collection view of the values contained in this map
  147. */
  148. Collection values();
  149. }