javax.ws.rs.core
Class MultivaluedHashMap<K,V>

java.lang.Object
  javax.ws.rs.core.MultivaluedHashMap<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Implemented Interfaces:

java.util.Map<K,java.util.List<V>>, MultivaluedMap<K,V>

public class MultivaluedHashMap<K,V>
extends java.lang.Object
implements MultivaluedMap<K,V>

A hash table based implementation of MultivaluedMap interface. This implementation provides all of the optional map operations. This class makes no guarantees as to the order of the map; in particular, it does not guarantee that the order will remain constant over time. The implementation permits null key. By default the implementation does also permit null values, but ignores them. This behavior can be customized by overriding the protected addNull(...) and addFirstNull(...) methods.

This implementation provides constant-time performance for the basic operations (get and put), assuming the hash function disperses the elements properly among the buckets. Iteration over collection views requires time proportional to the "capacity" of the map instance (the number of buckets) plus its size (the number of key-value mappings). Thus, it's very important not to set the initial capacity too high (or the load factor too low) if iteration performance is important.

An instance of MultivaluedHashMap has two parameters that affect its performance: initial capacity and load factor. The capacity is the number of buckets in the hash table, and the initial capacity is simply the capacity at the time the hash table is created. The load factor is a measure of how full the hash table is allowed to get before its capacity is automatically increased. When the number of entries in the hash table exceeds the product of the load factor and the current capacity, the hash table is rehashed (that is, internal data structures are rebuilt) so that the hash table has approximately twice the number of buckets.

As a general rule, the default load factor (.75) offers a good tradeoff between time and space costs. Higher values decrease the space overhead but increase the lookup cost (reflected in most of the operations of the HashMap class, including get and put). The expected number of entries in the map and its load factor should be taken into account when setting its initial capacity, so as to minimize the number of rehash operations. If the initial capacity is greater than the maximum number of entries divided by the load factor, no rehash operations will ever occur.

If many mappings are to be stored in a MultivaluedHashMap instance, creating it with a sufficiently large capacity will allow the mappings to be stored more efficiently than letting it perform automatic rehashing as needed to grow the table.

Note that this implementation is not guaranteed to be synchronized. If multiple threads access a hash map concurrently, and at least one of the threads modifies the map structurally, it must be synchronized externally. (A structural modification is any operation that adds or deletes one or more mappings; merely changing the value associated with a key that an instance already contains is not a structural modification.) This is typically accomplished by synchronizing on some object that naturally encapsulates the map.

The iterators returned by all of this class's "collection view methods" are fail-fast: if the map is structurally modified at any time after the iterator is created, in any way except through the iterator's own remove method, the iterator will throw a ConcurrentModificationException. Thus, in the face of concurrent modification, the iterator fails quickly and cleanly, rather than risking arbitrary, non-deterministic behavior at an undetermined time in the future.

Note that the fail-fast behavior of an iterator cannot be guaranteed as it is, generally speaking, impossible to make any hard guarantees in the presence of unsynchronized concurrent modification. Fail-fast iterators throw ConcurrentModificationException on a best-effort basis. Therefore, it would be wrong to write a program that depended on this exception for its correctness: the fail-fast behavior of iterators should be used only to detect bugs.

Since:

2.0

Author:

Paul Sandoz, Marek Potociar

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Constructor Summary

MultivaluedHashMap()
Constructs an empty multivalued hash map with the default initial capacity (16) and the default load factor (0.75).

MultivaluedHashMap(int initialCapacity)
Constructs an empty multivalued hash map with the specified initial capacity and the default load factor (0.75).

MultivaluedHashMap(int initialCapacity, float loadFactor)
Constructs an empty multivalued hash map with the specified initial capacity and load factor.

MultivaluedHashMap(java.util.Map<? extends K,? extends V> map)
Constructs a new multivalued hash map with the same mappings as the specified single-valued Map.

MultivaluedHashMap(MultivaluedMap<? extends K,? extends V> map)
Constructs a new multivalued hash map with the same mappings as the specified MultivaluedMap.

Method Summary

void	add(K key, V value) Add a value to the current list of values for the supplied key.
void	addAll(K key, java.util.List<V> valueList) Add all the values from the supplied value list to the current list of values for the supplied key.
void	addAll(K key, V... newValues) Add multiple values to the current list of values for the supplied key.
void	addFirst(K key, V value) Add a value to the first position in the current list of values for the supplied key.
protected void	addFirstNull(java.util.List<V> values) Define the behavior for adding a null values to the first position in the value list.
protected void	addNull(java.util.List<V> values) Define the behavior for adding a null values to the value list.
void	clear()
java.lang.Object	clone()
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
java.util.Set<java.util.Map.Entry<K,java.util.List<V>>>	entrySet()
boolean	equals(java.lang.Object o)
java.util.List<V>	get(java.lang.Object key)
V	getFirst(K key) A shortcut to get the first value of the supplied key.
protected java.util.List<V>	getValues(K key) Return a non-null list of values for a given key.
int	hashCode()
boolean	isEmpty()
java.util.Set<K>	keySet()
java.util.List<V>	put(K key, java.util.List<V> value)
void	putAll(java.util.Map<? extends K,? extends java.util.List<V>> m)
void	putSingle(K key, V value) Set the value for the key to be a one item list consisting of the supplied value.
java.util.List<V>	remove(java.lang.Object key)
int	size()
java.lang.String	toString()
java.util.Collection<java.util.List<V>>	values()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MultivaluedHashMap

public MultivaluedHashMap()

Constructs an empty multivalued hash map with the default initial capacity (16) and the default load factor (0.75).

MultivaluedHashMap

public MultivaluedHashMap(int initialCapacity)

Constructs an empty multivalued hash map with the specified initial capacity and the default load factor (0.75).

Parameters:

initialCapacity - the initial capacity.

Throws:

java.lang.IllegalArgumentException - if the initial capacity is negative.

MultivaluedHashMap

public MultivaluedHashMap(int initialCapacity,
                          float loadFactor)

Constructs an empty multivalued hash map with the specified initial capacity and load factor.

Parameters:

initialCapacity - the initial capacity

loadFactor - the load factor

Throws:

java.lang.IllegalArgumentException - if the initial capacity is negative or the load factor is nonpositive

MultivaluedHashMap

public MultivaluedHashMap(MultivaluedMap<? extends K,? extends V> map)

Constructs a new multivalued hash map with the same mappings as the specified MultivaluedMap. The List instances holding the values of each key are created anew instead of being reused.

Parameters:

map - the multivalued map whose mappings are to be placed in this multivalued map.

Throws:

java.lang.NullPointerException - if the specified map is null

MultivaluedHashMap

public MultivaluedHashMap(java.util.Map<? extends K,? extends V> map)

Constructs a new multivalued hash map with the same mappings as the specified single-valued Map.

Parameters:

map - the single-valued map whose mappings are to be placed in this multivalued map.

Throws:

java.lang.NullPointerException - if the specified map is null

Method Detail

putSingle

public final void putSingle(K key,
                            V value)

Set the value for the key to be a one item list consisting of the supplied value. Any existing values will be replaced.

NOTE: This implementation ignores null values; A supplied value of null is ignored and not added to the purged value list. As a result of such operation, empty value list would be registered for the supplied key. Overriding implementations may modify this behavior by redefining the addNull(java.util.List) method.

Specified by:

putSingle in interface MultivaluedMap<K,V>

Parameters:

key - the key

value - the single value of the key. If the value is null it will be ignored.

addNull

protected void addNull(java.util.List<V> values)

Define the behavior for adding a null values to the value list.

Default implementation is a no-op, i.e. the null values are ignored. Overriding implementations may modify this behavior by providing their own definitions of this method.

Parameters:

values - value list where the null value addition is being requested.

addFirstNull

protected void addFirstNull(java.util.List<V> values)

Define the behavior for adding a null values to the first position in the value list.

Default implementation is a no-op, i.e. the null values are ignored. Overriding implementations may modify this behavior by providing their own definitions of this method.

Parameters:

values - value list where the null value addition is being requested.

add

public final void add(K key,
                      V value)

Description copied from interface: MultivaluedMap

Add a value to the current list of values for the supplied key.

Specified by:

add in interface MultivaluedMap<K,V>

Parameters:

key - the key

value - the value to be added.

addAll

public final void addAll(K key,
                         V... newValues)

Add multiple values to the current list of values for the supplied key. If the supplied array of new values is empty, method returns immediately. Method throws a NullPointerException if the supplied array of values is null.

NOTE: This implementation ignores null values; Any of the supplied values of null is ignored and not added to the value list. Overriding implementations may modify this behavior by redefining the addNull(java.util.List) method.

Parameters:

key - the key.

newValues - the values to be added.

Throws:

java.lang.NullPointerException - if the supplied array of new values is null.

addAll

public final void addAll(K key,
                         java.util.List<V> valueList)

Add all the values from the supplied value list to the current list of values for the supplied key. If the supplied value list is empty, method returns immediately. Method throws a NullPointerException if the supplied array of values is null.

NOTE: This implementation ignores null values; Any null value in the supplied value list is ignored and not added to the value list. Overriding implementations may modify this behavior by redefining the addNull(java.util.List) method.

Parameters:

key - the key.

valueList - the list of values to be added.

Throws:

java.lang.NullPointerException - if the supplied value list is null.

getFirst

public final V getFirst(K key)

Description copied from interface: MultivaluedMap

A shortcut to get the first value of the supplied key.

Specified by:

getFirst in interface MultivaluedMap<K,V>

Parameters:

key - the key

Returns:

the first value for the specified key or null if the key is not in the map.

addFirst

public final void addFirst(K key,
                           V value)

Add a value to the first position in the current list of values for the supplied key.

NOTE: This implementation ignores null values; A supplied value of null is ignored and not added to the purged value list. Overriding implementations may modify this behavior by redefining the addFirstNull(java.util.List) method.

Parameters:

key - the key

value - the value to be added.

getValues

protected final java.util.List<V> getValues(K key)

Return a non-null list of values for a given key. The returned list may be empty.

If there is no entry for the key in the map, a new empty List instance is created, registered within the map to hold the values of the key and returned from the method.

Parameters:

key - the key.

Returns:

value list registered with the key. The method is guaranteed to never return null.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Map<K,java.util.List<V>>

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Specified by:

equals in interface java.util.Map<K,java.util.List<V>>

Overrides:

equals in class java.lang.Object

values

public java.util.Collection<java.util.List<V>> values()

Specified by:

values in interface java.util.Map<K,java.util.List<V>>

size

public int size()

Specified by:

size in interface java.util.Map<K,java.util.List<V>>

remove

public java.util.List<V> remove(java.lang.Object key)

Specified by:

remove in interface java.util.Map<K,java.util.List<V>>

putAll

public void putAll(java.util.Map<? extends K,? extends java.util.List<V>> m)

Specified by:

putAll in interface java.util.Map<K,java.util.List<V>>

put

public java.util.List<V> put(K key,
                             java.util.List<V> value)

Specified by:

put in interface java.util.Map<K,java.util.List<V>>

keySet

public java.util.Set<K> keySet()

Specified by:

keySet in interface java.util.Map<K,java.util.List<V>>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Map<K,java.util.List<V>>

get

public java.util.List<V> get(java.lang.Object key)

Specified by:

get in interface java.util.Map<K,java.util.List<V>>

entrySet

public java.util.Set<java.util.Map.Entry<K,java.util.List<V>>> entrySet()

Specified by:

entrySet in interface java.util.Map<K,java.util.List<V>>

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

containsValue in interface java.util.Map<K,java.util.List<V>>

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

containsKey in interface java.util.Map<K,java.util.List<V>>

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object

clear

public void clear()

Specified by:

clear in interface java.util.Map<K,java.util.List<V>>