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 }