map and
+ * maps keys to collections of type collectionClass.
+ *
+ * @param map the map to wrap
+ * @param collectionClass the type of the collection class
+ */
+ public static Map decorate(Map map, Class collectionClass) {
+ return new MultiValueMap(map, collectionClass);
+ }
+
+ /**
+ * Creates a map which decorates the given map and
+ * creates the value collections using the supplied collectionFactory.
+ *
+ * @param map the map to decorate
+ * @param collectionFactory the collection factory (must return a Collection object).
+ */
+ public static Map decorate(Map map, Factory collectionFactory) {
+ return new MultiValueMap(map, collectionFactory);
+ }
+
+ /**
+ * Creates a MultiValueMap which wraps the given map and
+ * maps keys to ArrayLists.
+ *
+ * @param map the map to wrap
+ */
+ protected MultiValueMap(Map map) {
+ this(map, ArrayList.class);
+ }
+
+ /**
+ * Creates a MultiValueMap which decorates the given map and
+ * maps keys to collections of type collectionClass.
+ *
+ * @param map the map to wrap
+ * @param collectionClass the type of the collection class
+ */
+ protected MultiValueMap(Map map, Class collectionClass) {
+ this(map, new ReflectionFactory(collectionClass));
+ }
+
+ /**
+ * Creates a MultiValueMap which decorates the given map and
+ * creates the value collections using the supplied collectionFactory.
+ *
+ * @param map the map to decorate
+ * @param collectionFactory the collection factory (must return a Collection object).
+ */
+ protected MultiValueMap(Map map, Factory collectionFactory) {
+ super(map);
+ this.collectionFactory = collectionFactory;
+ }
+
+ /**
+ * Clear the map.
+ * + * This clears each collection in the map, and so may be slow. + */ + public void clear() { + Set pairs = getMap().entrySet(); + Iterator pairsIterator = pairs.iterator(); + while(pairsIterator.hasNext()) { + Map.Entry keyValuePair = (Map.Entry) pairsIterator.next(); + Collection coll = (Collection) keyValuePair.getValue(); + coll.clear(); + } + getMap().clear(); + } + + /** + * Removes a specific value from map. + *
+ * The item is removed from the collection mapped to the specified key. + * Other values attached to that key are unaffected. + *
+ * If the last value for a key is removed, null will be returned
+ * from a subsequant get(key).
+ *
+ * @param key the key to remove from
+ * @param value the value to remove
+ * @return the value removed (which was passed in), null if nothing removed
+ */
+ public Object remove(Object key, Object value) {
+ Collection valuesForKey = getCollection(key);
+ if(valuesForKey == null) {
+ return null;
+ }
+ boolean removed = valuesForKey.remove(value);
+ if(removed == false) {
+ return null;
+ }
+ if(valuesForKey.isEmpty()) {
+ remove(key);
+ }
+ return value;
+ }
+
+ /**
+ * Checks whether the map contains the value specified.
+ *
+ * This checks all collections against all keys for the value, and thus could be slow. + * + * @param value the value to search for + * @return true if the map contains the value + */ + public boolean containsValue(Object value) { + Set pairs = getMap().entrySet(); + if(pairs == null) { + return false; + } + Iterator pairsIterator = pairs.iterator(); + while(pairsIterator.hasNext()) { + Map.Entry keyValuePair = (Map.Entry) pairsIterator.next(); + Collection coll = (Collection) keyValuePair.getValue(); + if(coll.contains(value)) { + return true; + } + } + return false; + } + + /** + * Removes a specific value from map. + *
+ * The item is removed from the collection mapped to the specified key. + * Other values attached to that key are unaffected. + *
+ * If the last value for a key is removed, null will be returned
+ * from a subsequant get(key).
+ *
+ * @param key the key to remove from
+ * @param value the value to remove
+ * @return the value removed (which was passed in), null if nothing removed
+ */
+ public Object put(Object key, Object value) {
+ Collection c = getCollection(key);
+ if(c == null) {
+ c = (Collection) collectionFactory.create();
+ getMap().put(key, c);
+ }
+ boolean results = c.add(value);
+ return (results ? value : null);
+ }
+
+ /**
+ * Gets a collection containing all the values in the map.
+ *
+ * This returns a collection containing the combination of values from all keys.
+ *
+ * @return a collection view of the values contained in this map
+ */
+ public Collection values() {
+ Collection vs = values;
+ return (vs != null ? vs : (values = new Values()));
+ }
+
+ /**
+ * Checks whether the collection at the specified key contains the value.
+ *
+ * @param value the value to search for
+ * @return true if the map contains the value
+ */
+ public boolean containsValue(Object key, Object value) {
+ Collection coll = getCollection(key);
+ if(coll == null) {
+ return false;
+ }
+ return coll.contains(value);
+ }
+
+ /**
+ * Gets the collection mapped to the specified key.
+ * This method is a convenience method to typecast the result of get(key).
+ *
+ * @param key the key to retrieve
+ * @return the collection mapped to the key, null if no mapping
+ */
+ public Collection getCollection(Object key) {
+ return (Collection) getMap().get(key);
+ }
+
+ /**
+ * Gets the size of the collection mapped to the specified key.
+ *
+ * @param key the key to get size for
+ * @return the size of the collection at the key, zero if key not in map
+ */
+ public int size(Object key) {
+ Collection coll = getCollection(key);
+ if(coll == null) {
+ return 0;
+ }
+ return coll.size();
+ }
+
+ /**
+ * Adds a collection of values to the collection associated with the specified key.
+ *
+ * @param key the key to store against
+ * @param values the values to add to the collection at the key, null ignored
+ * @return true if this map changed
+ */
+ public boolean putAll(Object key, Collection values) {
+ if(values == null || values.size() == 0) {
+ return false;
+ }
+ Collection coll = getCollection(key);
+ if(coll == null) {
+ coll = (Collection) collectionFactory.create();
+ getMap().put(key, coll);
+ }
+ return coll.addAll(values);
+ }
+
+ /**
+ * Gets an iterator for the collection mapped to the specified key.
+ *
+ * @param key the key to get an iterator for
+ * @return the iterator of the collection at the key, empty iterator if key not in map
+ */
+ public Iterator iterator(Object key) {
+ if(!containsKey(key)) {
+ return EmptyIterator.INSTANCE;
+ }
+ else {
+ return new ValuesIterator(key);
+ }
+ }
+
+ /**
+ * Gets the total size of the map by counting all the values.
+ *
+ * @return the total size of the map counting all values
+ */
+ public int totalSize() {
+ int total = 0;
+ Collection values = getMap().values();
+ for(Iterator it = values.iterator(); it.hasNext();) {
+ Collection coll = (Collection) it.next();
+ total += coll.size();
+ }
+ return total;
+ }
+
+ private class Values extends AbstractCollection {
+ public Iterator iterator() {
+ final IteratorChain chain = new IteratorChain();
+ for(Iterator i = keySet().iterator(); i.hasNext();) {
+ chain.addIterator(new ValuesIterator(i.next()));
+ }
+ return chain;
+ }
+
+ public int size() {
+ return totalSize();
+ }
+
+ public void clear() {
+ MultiValueMap.this.clear();
+ }
+ }
+
+ private class ValuesIterator implements Iterator {
+ private final Object key;
+ private final Collection values;
+ private final Iterator iterator;
+
+ public ValuesIterator(Object key) {
+ this.key = key;
+ this.values = getCollection(key);
+ this.iterator = values.iterator();
+ }
+
+ public void remove() {
+ iterator.remove();
+ if(values.isEmpty()) {
+ MultiValueMap.this.remove(key);
+ }
+ }
+
+ public boolean hasNext() {
+ return iterator.hasNext();
+ }
+
+ public Object next() {
+ return iterator.next();
+ }
+ }
+
+ private static class ReflectionFactory implements Factory {
+ private final Class clazz;
+
+ public ReflectionFactory(Class clazz) {
+ this.clazz = clazz;
+ }
+
+ public Object create() {
+ try {
+ return clazz.newInstance();
+ }
+ catch(Exception e) {
+ throw new RuntimeException("Cannot instantiate class " + clazz + ".", e);
+ }
+ }
+ }
+}
diff --git a/src/test/org/apache/commons/collections/map/TestMultiValueMap.java b/src/test/org/apache/commons/collections/map/TestMultiValueMap.java
new file mode 100644
index 000000000..99bdd8a56
--- /dev/null
+++ b/src/test/org/apache/commons/collections/map/TestMultiValueMap.java
@@ -0,0 +1,136 @@
+/*
+ * Copyright 2001-2005 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.collections.map;
+
+import junit.framework.TestCase;
+
+import java.util.HashMap;
+import java.util.LinkedList;
+import java.util.HashSet;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Iterator;
+import java.util.Collection;
+
+import org.apache.commons.collections.IteratorUtils;
+
+/**
+ * TestMultiValueMap
+ *
+ * @author James Carman
+ * @since Commons Collections 3.2
+ */
+public class TestMultiValueMap extends TestCase {
+ public void testNoMappingReturnsNull() {
+ final MultiValueMap map = createTestMap();
+ assertNull(map.get("whatever"));
+ }
+
+ public void testValueCollectionType() {
+ final MultiValueMap map = createTestMap(LinkedList.class);
+ assertTrue(map.get("one") instanceof LinkedList);
+ }
+
+ public void testMultipleValues() {
+ final MultiValueMap map = createTestMap(HashSet.class);
+ final HashSet expected = new HashSet();
+ expected.add("uno");
+ expected.add("un");
+ assertEquals(expected, map.get("one"));
+ }
+
+ public void testContainsValue() {
+ final MultiValueMap map = createTestMap(HashSet.class);
+ assertTrue(map.containsValue("uno"));
+ assertTrue(map.containsValue("un"));
+ assertTrue(map.containsValue("dos"));
+ assertTrue(map.containsValue("deux"));
+ assertTrue(map.containsValue("tres"));
+ assertTrue(map.containsValue("trois"));
+ assertFalse(map.containsValue("quatro"));
+ }
+
+ public void testKeyContainsValue() {
+ final MultiValueMap map = createTestMap(HashSet.class);
+ assertTrue(map.containsValue("one", "uno"));
+ assertTrue(map.containsValue("one", "un"));
+ assertTrue(map.containsValue("two", "dos"));
+ assertTrue(map.containsValue("two", "deux"));
+ assertTrue(map.containsValue("three", "tres"));
+ assertTrue(map.containsValue("three", "trois"));
+ assertFalse(map.containsValue("four", "quatro"));
+ }
+
+ public void testValues() {
+ final MultiValueMap map = createTestMap(HashSet.class);
+ final HashSet expected = new HashSet();
+ expected.add("uno");
+ expected.add("dos");
+ expected.add("tres");
+ expected.add("un");
+ expected.add("deux");
+ expected.add("trois");
+ final Collection c = map.values();
+ assertEquals(6, c.size());
+ assertEquals(expected, new HashSet(c));
+ }
+
+ private MultiValueMap createTestMap() {
+ return createTestMap(ArrayList.class);
+ }
+
+ private MultiValueMap createTestMap(Class collectionClass) {
+ final MultiValueMap map = new MultiValueMap(new HashMap(), collectionClass);
+ map.put("one", "uno");
+ map.put("one", "un");
+ map.put("two", "dos");
+ map.put("two", "deux");
+ map.put("three", "tres");
+ map.put("three", "trois");
+ return map;
+ }
+
+ public void testKeyedIterator() {
+ final MultiValueMap map = createTestMap();
+ final ArrayList actual = new ArrayList(IteratorUtils.toList(map.iterator("one")));
+ final ArrayList expected = new ArrayList(Arrays.asList(new String[]{"uno", "un"}));
+ assertEquals(expected, actual);
+ }
+
+ public void testRemoveAllViaIterator() {
+ final MultiValueMap map = createTestMap();
+ for(Iterator i = map.values().iterator(); i.hasNext();) {
+ i.next();
+ i.remove();
+ }
+ assertNull(map.get("one"));
+ assertTrue(map.isEmpty());
+ }
+
+ public void testRemoveAllViaKeyedIterator() {
+ final MultiValueMap map = createTestMap();
+ for(Iterator i = map.iterator("one"); i.hasNext();) {
+ i.next();
+ i.remove();
+ }
+ assertNull(map.get("one"));
+ assertEquals(4, map.totalSize());
+ }
+
+ public void testTotalSize() {
+ assertEquals(6, createTestMap().totalSize());
+ }
+}