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

public Class MultiKeyMap<K, V>

extends AbstractMapDecorator<MultiKey<? extends K>, V>
implements Serializable, Cloneable
Class Inheritance
All Implemented Interfaces
java.lang.Cloneable, java.io.Serializable
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.Map, org.apache.commons.collections4.MapIterator, org.apache.commons.collections4.keyvalue.MultiKey
A Map implementation that uses multiple keys to map the value.

This class is the most efficient way to uses multiple keys to map to a value. The best way to use this class is via the additional map-style methods. These provide get, containsKey, put and remove for individual keys which operate without extra object creation.

The additional methods are the main interface of this map. As such, you will not normally hold this map in a variable of type Map.

The normal map methods take in and return a MultiKey. If you try to use put() with any other object type a ClassCastException is thrown. If you try to use null as the key in put() a NullPointerException is thrown.

This map is implemented as a decorator of a AbstractHashedMap which enables extra behaviour to be added easily.

Note that IdentityMap and ReferenceIdentityMap are unsuitable for use as the key comparison would work on the whole MultiKey, not the elements within.

As an example, consider a least recently used cache that uses a String airline code and a Locale to lookup the airline's name: 

private MultiKeyMap cache = MultiKeyMap.multiKeyMap(new LRUMap(50));

public String getAirlineName(String code, String locale) {
  String name = (String) cache.get(code, locale);
  if (name == null) {
    name = getAirlineNameFromDB(code, locale);
    cache.put(code, locale, name);
  }
  return name;
}

Note that MultiKeyMap 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.1

Field Summary

Modifier and TypeField and Description
private static final long
serialVersionUID

Serialisation version

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

Constructor Summary

AccessConstructor and Description
public
MultiKeyMap()

Constructs a new MultiKeyMap that decorates a HashedMap.

protected
MultiKeyMap(final AbstractHashedMap<MultiKey<? extends K>, V>
the map to decorate
map)

Constructor that decorates the specified map and is called from multiKeyMap(AbstractHashedMap).

Method Summary

Modifier and TypeMethod and Description
protected void
checkKey(final MultiKey<?>
the key to check
key)

Check to ensure that input keys are valid MultiKey objects.

public MultiKeyMap<K, V>

Returns:

a shallow clone
clone()

Overrides java.lang.Object.clone.

Clones the map without cloning the keys or values.
public boolean

Returns:

true if the map contains the key
containsKey(final Object
the first key
key1, final Object
the second key
key2)

Checks whether the map contains the specified multi-key.

public boolean

Returns:

true if the map contains the key
containsKey(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3)

Checks whether the map contains the specified multi-key.

public boolean

Returns:

true if the map contains the key
containsKey(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4)

Checks whether the map contains the specified multi-key.

public boolean

Returns:

true if the map contains the key
containsKey(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4, final Object
the fifth key
key5)

Checks whether the map contains the specified multi-key.

protected AbstractHashedMap<MultiKey<? extends K>, V>
decorated()

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

Gets the map being decorated.
public V

Returns:

the mapped value, null if no match
get(final Object
the first key
key1, final Object
the second key
key2)

Gets the value mapped to the specified multi-key.

public V

Returns:

the mapped value, null if no match
get(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3)

Gets the value mapped to the specified multi-key.

public V

Returns:

the mapped value, null if no match
get(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4)

Gets the value mapped to the specified multi-key.

public V

Returns:

the mapped value, null if no match
get(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4, final Object
the fifth key
key5)

Gets the value mapped to the specified multi-key.

protected int

Returns:

the hash code
hash(final Object
the first key
key1, final Object
the second key
key2)

Gets the hash code for the specified multi-key.

protected int

Returns:

the hash code
hash(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3)

Gets the hash code for the specified multi-key.

protected int

Returns:

the hash code
hash(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4)

Gets the hash code for the specified multi-key.

protected int

Returns:

the hash code
hash(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4, final Object
the fifth key
key5)

Gets the hash code for the specified multi-key.

protected boolean

Returns:

true if the key matches
isEqualKey(final AbstractHashedMap.HashEntry<MultiKey<? extends K>, V>
the entry to compare to
entry, final Object
the first key
key1, final Object
the second key
key2)

Is the key equal to the combined key.

protected boolean

Returns:

true if the key matches
isEqualKey(final AbstractHashedMap.HashEntry<MultiKey<? extends K>, V>
the entry to compare to
entry, final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3)

Is the key equal to the combined key.

protected boolean

Returns:

true if the key matches
isEqualKey(final AbstractHashedMap.HashEntry<MultiKey<? extends K>, V>
the entry to compare to
entry, final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4)

Is the key equal to the combined key.

protected boolean

Returns:

true if the key matches
isEqualKey(final AbstractHashedMap.HashEntry<MultiKey<? extends K>, V>
the entry to compare to
entry, final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4, final Object
the fifth key
key5)

Is the key equal to the combined key.

public MapIterator<MultiKey<? extends K>, V>
mapIterator()

Overrides org.apache.commons.collections4.map.AbstractIterableMap.mapIterator.

Implements org.apache.commons.collections4.IterableGet.mapIterator.

Obtains a MapIterator over the map.
public static <
the key type
K,
the value type
V> MultiKeyMap<K, V>

Returns:

a new multi key map
multiKeyMap(final AbstractHashedMap<MultiKey<? extends K>, V>
the map to decorate, not null
map)

Decorates the specified map to add the MultiKeyMap API and fast query.

public V

Returns:

the value previously mapped to this combined key, null if none
put(final K
the first key
key1, final K
the second key
key2, final V
the value to store
value)

Stores the value against the specified multi-key.

public V

Returns:

the value previously mapped to this combined key, null if none
put(final K
the first key
key1, final K
the second key
key2, final K
the third key
key3, final V
the value to store
value)

Stores the value against the specified multi-key.

public V

Returns:

the value previously mapped to this combined key, null if none
put(final K
the first key
key1, final K
the second key
key2, final K
the third key
key3, final K
the fourth key
key4, final V
the value to store
value)

Stores the value against the specified multi-key.

public V

Returns:

the value previously mapped to this combined key, null if none
put(final K
the first key
key1, final K
the second key
key2, final K
the third key
key3, final K
the fourth key
key4, final K
the fifth key
key5, final V
the value to store
value)

Stores the value against the specified multi-key.

public V

Returns:

the previous value for the key
put(final MultiKey<? extends K>
the non-null MultiKey object
key, final V
the value to store
value)

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

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

Puts the key and value into the map, where the key must be a non-null MultiKey object.
public void
putAll(final Map<? extends MultiKey<? extends K>, ? extends V>
to this map
mapToCopy)

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

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

Copies all of the keys and values from the specified map to this map.
private void
readObject(final ObjectInputStream
the input stream
in)

Read the map in using a custom routine.

public boolean

Returns:

true if any elements were removed
removeAll(final Object
the first key
key1)

Removes all mappings where the first key is that specified.

public boolean

Returns:

true if any elements were removed
removeAll(final Object
the first key
key1, final Object
the second key
key2)

Removes all mappings where the first two keys are those specified.

public boolean

Returns:

true if any elements were removed
removeAll(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3)

Removes all mappings where the first three keys are those specified.

public boolean

Returns:

true if any elements were removed
removeAll(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4)

Removes all mappings where the first four keys are those specified.

public V

Returns:

the value mapped to the removed key, null if key not in map
removeMultiKey(final Object
the first key
key1, final Object
the second key
key2)

Removes the specified multi-key from this map.

public V

Returns:

the value mapped to the removed key, null if key not in map
removeMultiKey(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3)

Removes the specified multi-key from this map.

public V

Returns:

the value mapped to the removed key, null if key not in map
removeMultiKey(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4)

Removes the specified multi-key from this map.

public V

Returns:

the value mapped to the removed key, null if key not in map
removeMultiKey(final Object
the first key
key1, final Object
the second key
key2, final Object
the third key
key3, final Object
the fourth key
key4, final Object
the fifth key
key5)

Removes the specified multi-key from this 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:
clearcontainsKeycontainsValueentrySetequalsgethashCodeisEmptykeySetremovesizetoStringvalues

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Serialisation version

Constructor Detail

MultiKeyMapback to summary
public MultiKeyMap()

Constructs a new MultiKeyMap that decorates a HashedMap.

MultiKeyMapback to summary
protected MultiKeyMap(final AbstractHashedMap<MultiKey<? extends K>, V> map)

Constructor that decorates the specified map and is called from multiKeyMap(AbstractHashedMap). The map must not be null and should be empty or only contain valid keys. This constructor performs no validation.

Parameters
map:AbstractHashedMap<MultiKey<? extends K>, V>

the map to decorate

Method Detail

checkKeyback to summary
protected void checkKey(final MultiKey<?> key)

Check to ensure that input keys are valid MultiKey objects.

Parameters
key:MultiKey<?>

the key to check

cloneback to summary
public MultiKeyMap<K, V> clone()

Overrides java.lang.Object.clone.

Clones the map without cloning the keys or values.

Returns:MultiKeyMap<K, V>

a shallow clone

Annotations
@SuppressWarnings:unchecked
@Override
containsKeyback to summary
public boolean containsKey(final Object key1, final Object key2)

Checks whether the map contains the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

Returns:boolean

true if the map contains the key

containsKeyback to summary
public boolean containsKey(final Object key1, final Object key2, final Object key3)

Checks whether the map contains the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

Returns:boolean

true if the map contains the key

containsKeyback to summary
public boolean containsKey(final Object key1, final Object key2, final Object key3, final Object key4)

Checks whether the map contains the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

Returns:boolean

true if the map contains the key

containsKeyback to summary
public boolean containsKey(final Object key1, final Object key2, final Object key3, final Object key4, final Object key5)

Checks whether the map contains the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

key5:Object

the fifth key

Returns:boolean

true if the map contains the key

decoratedback to summary
protected AbstractHashedMap<MultiKey<? extends K>, V> decorated()

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

Doc from org.apache.commons.collections4.map.AbstractMapDecorator.decorated.

Gets the map being decorated.

Returns:AbstractHashedMap<MultiKey<? extends K>, V>

the decorated map

Annotations
@Override
getback to summary
public V get(final Object key1, final Object key2)

Gets the value mapped to the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

Returns:V

the mapped value, null if no match

getback to summary
public V get(final Object key1, final Object key2, final Object key3)

Gets the value mapped to the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

Returns:V

the mapped value, null if no match

getback to summary
public V get(final Object key1, final Object key2, final Object key3, final Object key4)

Gets the value mapped to the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

Returns:V

the mapped value, null if no match

getback to summary
public V get(final Object key1, final Object key2, final Object key3, final Object key4, final Object key5)

Gets the value mapped to the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

key5:Object

the fifth key

Returns:V

the mapped value, null if no match

hashback to summary
protected int hash(final Object key1, final Object key2)

Gets the hash code for the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

Returns:int

the hash code

hashback to summary
protected int hash(final Object key1, final Object key2, final Object key3)

Gets the hash code for the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

Returns:int

the hash code

hashback to summary
protected int hash(final Object key1, final Object key2, final Object key3, final Object key4)

Gets the hash code for the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

Returns:int

the hash code

hashback to summary
protected int hash(final Object key1, final Object key2, final Object key3, final Object key4, final Object key5)

Gets the hash code for the specified multi-key.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

key5:Object

the fifth key

Returns:int

the hash code

isEqualKeyback to summary
protected boolean isEqualKey(final AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry, final Object key1, final Object key2)

Is the key equal to the combined key.

Parameters
entry:AbstractHashedMap.HashEntry<MultiKey<? extends K>, V>

the entry to compare to

key1:Object

the first key

key2:Object

the second key

Returns:boolean

true if the key matches

isEqualKeyback to summary
protected boolean isEqualKey(final AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry, final Object key1, final Object key2, final Object key3)

Is the key equal to the combined key.

Parameters
entry:AbstractHashedMap.HashEntry<MultiKey<? extends K>, V>

the entry to compare to

key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

Returns:boolean

true if the key matches

isEqualKeyback to summary
protected boolean isEqualKey(final AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry, final Object key1, final Object key2, final Object key3, final Object key4)

Is the key equal to the combined key.

Parameters
entry:AbstractHashedMap.HashEntry<MultiKey<? extends K>, V>

the entry to compare to

key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

Returns:boolean

true if the key matches

isEqualKeyback to summary
protected boolean isEqualKey(final AbstractHashedMap.HashEntry<MultiKey<? extends K>, V> entry, final Object key1, final Object key2, final Object key3, final Object key4, final Object key5)

Is the key equal to the combined key.

Parameters
entry:AbstractHashedMap.HashEntry<MultiKey<? extends K>, V>

the entry to compare to

key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

key5:Object

the fifth key

Returns:boolean

true if the key matches

mapIteratorback to summary
public MapIterator<MultiKey<? extends K>, V> mapIterator()

Overrides org.apache.commons.collections4.map.AbstractIterableMap.mapIterator.

Implements org.apache.commons.collections4.IterableGet.mapIterator.

Doc from org.apache.commons.collections4.map.AbstractIterableMap.mapIterator.

Obtains a MapIterator over the map.

A map iterator is an efficient way of iterating over maps. There is no need to access the entry set or use Map Entry objects. 

IterableMap<String,Integer> map = new HashedMap<String,Integer>();
MapIterator<String,Integer> it = map.mapIterator();
while (it.hasNext()) {
  String key = it.next();
  Integer value = it.getValue();
  it.setValue(value + 1);
}
Returns:MapIterator<MultiKey<? extends K>, V>

Doc from org.apache.commons.collections4.IterableGet.mapIterator.

a map iterator

Annotations
@Override
multiKeyMapback to summary
public static <K, V> MultiKeyMap<K, V> multiKeyMap(final AbstractHashedMap<MultiKey<? extends K>, V> map)

Decorates the specified map to add the MultiKeyMap API and fast query. The map must not be null and must be empty.

Parameters
<K>
the key type
<V>
the value type
map:AbstractHashedMap<MultiKey<? extends K>, V>

the map to decorate, not null

Returns:MultiKeyMap<K, V>

a new multi key map

Exceptions
NullPointerException:
if map is null
IllegalArgumentException:
if the map is not empty
Since
4.0
putback to summary
public V put(final K key1, final K key2, final V value)

Stores the value against the specified multi-key.

Parameters
key1:K

the first key

key2:K

the second key

value:V

the value to store

Returns:V

the value previously mapped to this combined key, null if none

putback to summary
public V put(final K key1, final K key2, final K key3, final V value)

Stores the value against the specified multi-key.

Parameters
key1:K

the first key

key2:K

the second key

key3:K

the third key

value:V

the value to store

Returns:V

the value previously mapped to this combined key, null if none

putback to summary
public V put(final K key1, final K key2, final K key3, final K key4, final V value)

Stores the value against the specified multi-key.

Parameters
key1:K

the first key

key2:K

the second key

key3:K

the third key

key4:K

the fourth key

value:V

the value to store

Returns:V

the value previously mapped to this combined key, null if none

putback to summary
public V put(final K key1, final K key2, final K key3, final K key4, final K key5, final V value)

Stores the value against the specified multi-key.

Parameters
key1:K

the first key

key2:K

the second key

key3:K

the third key

key4:K

the fourth key

key5:K

the fifth key

value:V

the value to store

Returns:V

the value previously mapped to this combined key, null if none

putback to summary
public V put(final MultiKey<? extends K> key, final V value)

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

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

Puts the key and value into the map, where the key must be a non-null MultiKey object.

Parameters
key:MultiKey<? extends K>

the non-null MultiKey object

value:V

the value to store

Returns:V

the previous value for the key

Annotations
@Override
Exceptions
NullPointerException:
if the key is null
ClassCastException:
if the key is not a MultiKey
putAllback to summary
public void putAll(final Map<? extends MultiKey<? extends K>, ? extends V> mapToCopy)

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

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

Copies all of the keys and values from the specified map to this map. Each key must be non-null and a MultiKey object.

Parameters
mapToCopy:Map<? extends MultiKey<? extends K>, ? extends V>

to this map

Annotations
@Override
Exceptions
NullPointerException:
if the mapToCopy or any key within is null
ClassCastException:
if any key in mapToCopy is not a MultiKey
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
removeAllback to summary
public boolean removeAll(final Object key1)

Removes all mappings where the first key is that specified.

This method removes all the mappings where the MultiKey has one or more keys, and the first matches that specified.

Parameters
key1:Object

the first key

Returns:boolean

true if any elements were removed

removeAllback to summary
public boolean removeAll(final Object key1, final Object key2)

Removes all mappings where the first two keys are those specified.

This method removes all the mappings where the MultiKey has two or more keys, and the first two match those specified.

Parameters
key1:Object

the first key

key2:Object

the second key

Returns:boolean

true if any elements were removed

removeAllback to summary
public boolean removeAll(final Object key1, final Object key2, final Object key3)

Removes all mappings where the first three keys are those specified.

This method removes all the mappings where the MultiKey has three or more keys, and the first three match those specified.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

Returns:boolean

true if any elements were removed

removeAllback to summary
public boolean removeAll(final Object key1, final Object key2, final Object key3, final Object key4)

Removes all mappings where the first four keys are those specified.

This method removes all the mappings where the MultiKey has four or more keys, and the first four match those specified.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

Returns:boolean

true if any elements were removed

removeMultiKeyback to summary
public V removeMultiKey(final Object key1, final Object key2)

Removes the specified multi-key from this map.

Parameters
key1:Object

the first key

key2:Object

the second key

Returns:V

the value mapped to the removed key, null if key not in map

Since
4.0 (previous name: remove(Object, Object))
removeMultiKeyback to summary
public V removeMultiKey(final Object key1, final Object key2, final Object key3)

Removes the specified multi-key from this map.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

Returns:V

the value mapped to the removed key, null if key not in map

Since
4.0 (previous name: remove(Object, Object, Object))
removeMultiKeyback to summary
public V removeMultiKey(final Object key1, final Object key2, final Object key3, final Object key4)

Removes the specified multi-key from this map.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

Returns:V

the value mapped to the removed key, null if key not in map

Since
4.0 (previous name: remove(Object, Object, Object, Object))
removeMultiKeyback to summary
public V removeMultiKey(final Object key1, final Object key2, final Object key3, final Object key4, final Object key5)

Removes the specified multi-key from this map.

Parameters
key1:Object

the first key

key2:Object

the second key

key3:Object

the third key

key4:Object

the fourth key

key5:Object

the fifth key

Returns:V

the value mapped to the removed key, null if key not in map

Since
4.0 (previous name: remove(Object, Object, Object, Object, Object))
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