Top Description Inners Fields Constructors Methods
org.apache.commons.collections4.map

public Class MultiValueMap<K, V>

extends AbstractMapDecorator<K, Object>
implements MultiMap<K, V>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, org.apache.commons.collections4.MultiMap, org.apache.commons.collections4.IterableMap, org.apache.commons.collections4.IterableGet, org.apache.commons.collections4.Get, org.apache.commons.collections4.Put, java.util.Map
Annotations
@Deprecated
Type Parameters
<K>
the type of the keys in this map
<V>
the type of the values in this map
Imports
java.io.IOException, .ObjectInputStream, .ObjectOutputStream, .Serializable, java.util.AbstractCollection, .ArrayList, .Collection, .HashMap, .Iterator, .Map, .Set, org.apache.commons.collections4.CollectionUtils, .Factory, .FunctorException, .MultiMap, .Transformer, org.apache.commons.collections4.iterators.EmptyIterator, .IteratorChain, .LazyIteratorChain, .TransformIterator

Deprecated

since 4.1, use MultiValuedMap instead

A MultiValueMap decorates another map, allowing it to have more than one value for a key.

A MultiMap is a Map with slightly different semantics. Putting a value into the map will add the value to a Collection at that key. Getting a value will return a Collection, holding all the values put to that key.

This implementation is a decorator, allowing any Map implementation to be used as the base.

In addition, this implementation allows the type of collection used for the values to be controlled. By default, an ArrayList is used, however a Class to instantiate may be specified, or a factory that returns a Collection instance.

Note that MultiValueMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization. This class may throw exceptions when accessed by concurrent threads without synchronization.

Since
3.2

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
MultiValueMap.ReflectionFactory<T extends Collection<?>>

Inner class that provides a simple reflection factory.

private class
MultiValueMap.Values

Inner class that provides the values view.

private class
MultiValueMap.ValuesIterator

Inner class that provides the values iterator.

Field Summary

Modifier and TypeField and Description
private final Factory<? extends Collection<V>>
collectionFactory

The factory for creating value collections.

private static final long
serialVersionUID

Serialization version

private transient Collection<V>
valuesView

The cached values.

Inherited from org.apache.commons.collections4.map.AbstractMapDecorator:
map

Constructor Summary

AccessConstructor and Description
public
MultiValueMap()

Creates a MultiValueMap based on a HashMap and storing the multiple values in an ArrayList.

protected <
the collection class type
C extends Collection<V>
>
MultiValueMap(final Map<K, ? super C>
the map to decorate
map
,
final Factory<C>
the collection factory which must return a Collection instance
collectionFactory
)

Creates a MultiValueMap which decorates the given map and creates the value collections using the supplied collectionFactory.

Method Summary

Modifier and TypeMethod and Description
public void
public boolean

Returns:

true if the map contains the value
containsValue
(final Object
the value to search for
value
)

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.containsValue.

Implements org.apache.commons.collections4.MultiMap.containsValue, java.util.Map.containsValue, org.apache.commons.collections4.Get.containsValue.

Checks whether the map contains the value specified.
public boolean

Returns:

true if the map contains the value
containsValue
(final Object
the key to search for
key
,
final Object
the value to search for
value
)

Checks whether the collection at the specified key contains the value.

protected Collection<V>

Returns:

the new collection
createCollection
(final int
the collection size that is about to be added
size
)

Creates a new instance of the map value Collection container using the factory.

public Set<Map.Entry<K, Object>>
public Collection<V>

Returns:

the collection mapped to the key, null if no mapping
getCollection
(final Object
the key to retrieve
key
)

Gets the collection mapped to the specified key.

public Iterator<V>

Returns:

the iterator of the collection at the key, empty iterator if key not in map
iterator
(final Object
the key to get an iterator for
key
)

Gets an iterator for the collection mapped to the specified key.

public Iterator<Map.Entry<K, V>>

Returns:

the iterator of all mappings in this map
iterator
()

Gets an iterator for all mappings stored in this MultiValueMap.

public static <
the key type
K
,
the value type
V
>
MultiValueMap<K, V>

Returns:

a new multi-value map
multiValueMap
(final Map<K, ? super Collection<V>>
the map to wrap
map
)

Deprecated as a consequence of MultiValueMap being deprecated.
Creates a map which wraps the given map and maps keys to ArrayLists.
public static <
the key type
K
,
the value type
V
,
the collection class type
C extends Collection<V>
>
MultiValueMap<K, V>

Returns:

a new multi-value map
multiValueMap
(final Map<K, ? super C>
the map to wrap
map
,
final Class<C>
the type of the collection class
collectionClass
)

Deprecated as a consequence of MultiValueMap being deprecated.
Creates a map which decorates the given map and maps keys to collections of type collectionClass.
public static <
the key type
K
,
the value type
V
,
the collection class type
C extends Collection<V>
>
MultiValueMap<K, V>

Returns:

a new multi-value map
multiValueMap
(final Map<K, ? super C>
the map to decorate
map
,
final Factory<C>
the collection factory (must return a Collection object).
collectionFactory
)

Deprecated as a consequence of MultiValueMap being deprecated.
Creates a map which decorates the given map and creates the value collections using the supplied collectionFactory.
public Object

Returns:

the value added if the map changed and null if the map did not change
put
(final K
the key to store against
key
,
final Object
the value to add to the collection at the key
value
)

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.put.

Implements org.apache.commons.collections4.MultiMap.put, java.util.Map.put, org.apache.commons.collections4.Put.put.

Adds the value to the collection associated with the specified key.
public void
putAll(final Map<? extends K, ?>
the map to copy (either a normal or multi map)
map
)

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.putAll.

Implements java.util.Map.putAll, org.apache.commons.collections4.Put.putAll.

Override superclass to ensure that MultiMap instances are correctly handled.
public boolean

Returns:

true if this map changed
putAll
(final K
the key to store against
key
,
final Collection<V>
the values to add to the collection at the key, null ignored
values
)

Adds a collection of values to the collection associated with the specified key.

private void
readObject(final ObjectInputStream
the input stream
in
)

Read the map in using a custom routine.

public boolean

Returns:

true if the mapping was removed, false otherwise
removeMapping
(final Object
the key to remove from
key
,
final Object
the value to remove
value
)

Implements org.apache.commons.collections4.MultiMap.removeMapping.

Removes a specific value from map.
public int

Returns:

the size of the collection at the key, zero if key not in map
size
(final Object
the key to get size for
key
)

Gets the size of the collection mapped to the specified key.

public int

Returns:

the total size of the map counting all values
totalSize
()

Gets the total size of the map by counting all the values.

public Collection<Object>

Returns:

a collection view of the values contained in this map
values
()

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.values.

Implements org.apache.commons.collections4.MultiMap.values, java.util.Map.values, org.apache.commons.collections4.Get.values.

Gets a collection containing all the values in the map.
private void
writeObject(final ObjectOutputStream
the output stream
out
)

Write the map out using a custom routine.

Inherited from org.apache.commons.collections4.map.AbstractMapDecorator:
containsKeydecoratedequalsgethashCodeisEmptykeySetremovesizetoString

Field Detail

collectionFactoryback to summary
private final Factory<? extends Collection<V>> collectionFactory

The factory for creating value collections.

serialVersionUIDback to summary
private static final long serialVersionUID

Serialization version

valuesViewback to summary
private transient Collection<V> valuesView

The cached values.

Constructor Detail

MultiValueMapback to summary
public MultiValueMap()

Creates a MultiValueMap based on a HashMap and storing the multiple values in an ArrayList.

Annotations
@SuppressWarnings:unchecked, rawtypes
MultiValueMapback to summary
protected <C extends Collection<V>> MultiValueMap(final Map<K, ? super C> map, final Factory<C> collectionFactory)

Creates a MultiValueMap which decorates the given map and creates the value collections using the supplied collectionFactory.

Parameters
<C>
the collection class type
map:Map<K, ? super C>

the map to decorate

collectionFactory:Factory<C>

the collection factory which must return a Collection instance

Annotations
@SuppressWarnings:unchecked

Method Detail

clearback to summary
public void clear()

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.clear.

Implements java.util.Map.clear, org.apache.commons.collections4.Put.clear.

Clear the map.

Annotations
@Override
containsValueback to summary
public boolean containsValue(final Object value)

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.containsValue.

Implements org.apache.commons.collections4.MultiMap.containsValue, java.util.Map.containsValue, org.apache.commons.collections4.Get.containsValue.

Checks whether the map contains the value specified.

This checks all collections against all keys for the value, and thus could be slow.

Parameters
value:Object

the value to search for

Returns:boolean

true if the map contains the value

Annotations
@Override
@SuppressWarnings:unchecked
containsValueback to summary
public boolean containsValue(final Object key, final Object value)

Checks whether the collection at the specified key contains the value.

Parameters
key:Object

the key to search for

value:Object

the value to search for

Returns:boolean

true if the map contains the value

createCollectionback to summary
protected Collection<V> createCollection(final int size)

Creates a new instance of the map value Collection container using the factory.

This method can be overridden to perform your own processing instead of using the factory.

Parameters
size:int

the collection size that is about to be added

Returns:Collection<V>

the new collection

entrySetback to summary
public Set<Map.Entry<K, Object>> entrySet()

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.entrySet.

Implements java.util.Map.entrySet, org.apache.commons.collections4.Get.entrySet.

Doc from java.util.Map.entrySet.

Returns a Set view of the mappings contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Note

the returned Entry objects will contain as value a Collection of all values that are mapped to the given key. To get a "flattened" version of all mappings contained in this map, use iterator().

Returns:Set<Map.Entry<K, Object>>

a set view of the mappings contained in this map

Annotations
@Override
See Also
iterator()
getCollectionback to summary
public Collection<V> getCollection(final Object key)

Gets the collection mapped to the specified key. This method is a convenience method to typecast the result of get(key).

Parameters
key:Object

the key to retrieve

Returns:Collection<V>

the collection mapped to the key, null if no mapping

Annotations
@SuppressWarnings:unchecked
iteratorback to summary
public Iterator<V> iterator(final Object key)

Gets an iterator for the collection mapped to the specified key.

Parameters
key:Object

the key to get an iterator for

Returns:Iterator<V>

the iterator of the collection at the key, empty iterator if key not in map

iteratorback to summary
public Iterator<Map.Entry<K, V>> iterator()

Gets an iterator for all mappings stored in this MultiValueMap.

The iterator will return multiple Entry objects with the same key if there are multiple values mapped to this key.

Note

calling java.util.Map.Entry#setValue(Object) on any of the returned elements will result in a UnsupportedOperationException.

Returns:Iterator<Map.Entry<K, V>>

the iterator of all mappings in this map

Since
4.0
multiValueMapback to summary
public static <K, V> MultiValueMap<K, V> multiValueMap(final Map<K, ? super Collection<V>> map)

Deprecated

as a consequence of MultiValueMap being deprecated. See corresponding docs for further information.

Creates a map which wraps the given map and maps keys to ArrayLists.

Parameters
<K>
the key type
<V>
the value type
map:Map<K, ? super Collection<V>>

the map to wrap

Returns:MultiValueMap<K, V>

a new multi-value map

Annotations
@SuppressWarnings:unchecked, rawtypes
Since
4.0
multiValueMapback to summary
public static <K, V, C extends Collection<V>> MultiValueMap<K, V> multiValueMap(final Map<K, ? super C> map, final Class<C> collectionClass)

Deprecated

as a consequence of MultiValueMap being deprecated. See corresponding docs for further information.

Creates a map which decorates the given map and maps keys to collections of type collectionClass.

Parameters
<K>
the key type
<V>
the value type
<C>
the collection class type
map:Map<K, ? super C>

the map to wrap

collectionClass:Class<C>

the type of the collection class

Returns:MultiValueMap<K, V>

a new multi-value map

Since
4.0
multiValueMapback to summary
public static <K, V, C extends Collection<V>> MultiValueMap<K, V> multiValueMap(final Map<K, ? super C> map, final Factory<C> collectionFactory)

Deprecated

as a consequence of MultiValueMap being deprecated. See corresponding docs for further information.

Creates a map which decorates the given map and creates the value collections using the supplied collectionFactory.

Parameters
<K>
the key type
<V>
the value type
<C>
the collection class type
map:Map<K, ? super C>

the map to decorate

collectionFactory:Factory<C>

the collection factory (must return a Collection object).

Returns:MultiValueMap<K, V>

a new multi-value map

Since
4.0
putback to summary
public Object put(final K key, final Object value)

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.put.

Implements org.apache.commons.collections4.MultiMap.put, java.util.Map.put, org.apache.commons.collections4.Put.put.

Adds the value to the collection associated with the specified key.

Unlike a normal Map the previous value is not replaced. Instead the new value is added to the collection stored against the key.

Parameters
key:K

the key to store against

value:Object

the value to add to the collection at the key

Returns:Object

the value added if the map changed and null if the map did not change

Annotations
@Override
@SuppressWarnings:unchecked
putAllback to summary
public void putAll(final Map<? extends K, ?> map)

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.putAll.

Implements java.util.Map.putAll, org.apache.commons.collections4.Put.putAll.

Override superclass to ensure that MultiMap instances are correctly handled.

If you call this method with a normal map, each entry is added using put(Object,Object). If you call this method with a multi map, each entry is added using putAll(Object,Collection).

Parameters
map:Map<? extends K, ?>

the map to copy (either a normal or multi map)

Annotations
@Override
@SuppressWarnings:unchecked
putAllback to summary
public boolean putAll(final K key, final Collection<V> values)

Adds a collection of values to the collection associated with the specified key.

Parameters
key:K

the key to store against

values:Collection<V>

the values to add to the collection at the key, null ignored

Returns:boolean

true if this map changed

readObjectback to summary
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException

Read the map in using a custom routine.

Parameters
in:ObjectInputStream

the input stream

Annotations
@SuppressWarnings:unchecked
Exceptions
IOException:
if an error occurs while reading from the stream
ClassNotFoundException:
if an object read from the stream can not be loaded
Since
4.0
removeMappingback to summary
public boolean removeMapping(final Object key, final Object value)

Implements org.apache.commons.collections4.MultiMap.removeMapping.

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 subsequent get(key).

Parameters
key:Object

the key to remove from

value:Object

the value to remove

Returns:boolean

true if the mapping was removed, false otherwise

Annotations
@Override
sizeback to summary
public int size(final Object key)

Gets the size of the collection mapped to the specified key.

Parameters
key:Object

the key to get size for

Returns:int

the size of the collection at the key, zero if key not in map

totalSizeback to summary
public int totalSize()

Gets the total size of the map by counting all the values.

Returns:int

the total size of the map counting all values

valuesback to summary
public Collection<Object> values()

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.values.

Implements org.apache.commons.collections4.MultiMap.values, java.util.Map.values, org.apache.commons.collections4.Get.values.

Gets a collection containing all the values in the map.

This returns a collection containing the combination of values from all keys.

Returns:Collection<Object>

a collection view of the values contained in this map

Annotations
@Override
@SuppressWarnings:unchecked
writeObjectback to summary
private void writeObject(final ObjectOutputStream out) throws IOException

Write the map out using a custom routine.

Parameters
out:ObjectOutputStream

the output stream

Exceptions
IOException:
if an error occurs while writing to the stream
Since
4.0
org.apache.commons.collections4.map back to summary

private Class MultiValueMap.ReflectionFactory<T extends java.util.Collection<?>>

extends Object
implements Factory<T extends Collection<?>>, Serializable
Class Inheritance
  • java.lang.Object
  • org.apache.commons.collections4.map.MultiValueMap.ReflectionFactory
All Implemented Interfaces
java.io.Serializable, org.apache.commons.collections4.Factory

Inner class that provides a simple reflection factory.

Field Summary

Modifier and TypeField and Description
private final Class<T>
private static final long
serialVersionUID

Serialization version

Constructor Summary

AccessConstructor and Description
public
ReflectionFactory(final Class<T> clazz)

Method Summary

Modifier and TypeMethod and Description
public T
create()

Implements org.apache.commons.collections4.Factory.create.

Create a new object.
private void
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

clazzback to summary
private final Class<T> clazz
serialVersionUIDback to summary
private static final long serialVersionUID

Serialization version

Constructor Detail

ReflectionFactoryback to summary
public ReflectionFactory(final Class<T> clazz)

Method Detail

createback to summary
public T create()

Implements org.apache.commons.collections4.Factory.create.

Doc from org.apache.commons.collections4.Factory.create.

Create a new object.

Returns:T

a new object

Annotations
@Override
readObjectback to summary
private void readObject(final ObjectInputStream is) throws IOException, ClassNotFoundException
org.apache.commons.collections4.map back to summary

private Class MultiValueMap.Values

extends AbstractCollection<V>
Class Inheritance

Inner class that provides the values view.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public void
clear()

Overrides java.util.AbstractCollection.clear.

Implements java.util.Collection.clear.

Removes all of the elements from this collection (optional operation).
public Iterator<V>
iterator()

Implements abstract java.util.AbstractCollection.iterator.

Implements java.util.Collection.iterator.

Returns an iterator over the elements contained in this collection.
public int
size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.Collection.size.

Returns the number of elements in this collection.
Inherited from java.util.AbstractCollection:
addaddAllcontainscontainsAllisEmptyremoveremoveAllretainAlltoArraytoArraytoString

Constructor Detail

Valuesback to summary
private Values()

Method Detail

clearback to summary
public void clear()

Overrides java.util.AbstractCollection.clear.

Implements java.util.Collection.clear.

Doc from java.util.AbstractCollection.clear.

Removes all of the elements from this collection (optional operation). The collection will be empty after this method returns.

Annotations
@Override
iteratorback to summary
public Iterator<V> iterator()

Implements abstract java.util.AbstractCollection.iterator.

Implements java.util.Collection.iterator.

Doc from java.util.AbstractCollection.iterator.

Returns an iterator over the elements contained in this collection.

Returns:Iterator<V>

an iterator over the elements contained in this collection

Annotations
@Override
sizeback to summary
public int size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.Collection.size.

Doc from java.util.Collection.size.

Returns the number of elements in this collection. If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:int

the number of elements in this collection

Annotations
@Override
org.apache.commons.collections4.map back to summary

private Class MultiValueMap.ValuesIterator

extends Object
implements Iterator<V>
Class Inheritance
  • java.lang.Object
  • org.apache.commons.collections4.map.MultiValueMap.ValuesIterator
All Implemented Interfaces
java.util.Iterator

Inner class that provides the values iterator.

Field Summary

Modifier and TypeField and Description
private final Iterator<V>
private final Object
private final Collection<V>

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public boolean
hasNext()

Implements java.util.Iterator.hasNext.

Returns true if the iteration has more elements.
public V
next()

Implements java.util.Iterator.next.

Returns the next element in the iteration.
public void
remove()

Overrides default java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation).
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

iteratorback to summary
private final Iterator<V> iterator
keyback to summary
private final Object key
valuesback to summary
private final Collection<V> values

Constructor Detail

ValuesIteratorback to summary
public ValuesIterator(final Object key)

Method Detail

hasNextback to summary
public boolean hasNext()

Implements java.util.Iterator.hasNext.

Doc from java.util.Iterator.hasNext.

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Returns:boolean

true if the iteration has more elements

Annotations
@Override
nextback to summary
public V next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:V

the next element in the iteration

Annotations
@Override
removeback to summary
public void remove()

Overrides default java.util.Iterator.remove.

Doc from java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.

Annotations
@Override