public class

MultiKeyMap

extends Object
implements Serializable IterableMap
java.lang.Object
   ↳ org.apache.commons.collections.map.MultiKeyMap

Class Overview

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.

  • MultiKeyMap.decorate(new LinkedMap()) creates an ordered map.
  • MultiKeyMap.decorate(new LRUMap()) creates an least recently used map.
  • MultiKeyMap.decorate(new ReferenceMap()) creates a garbage collector sensitive map.
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.decorate(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.

Summary

Fields
protected final AbstractHashedMap map The decorated map
Public Constructors
MultiKeyMap()
Constructs a new MultiKeyMap that decorates a HashedMap.
Protected Constructors
MultiKeyMap(AbstractHashedMap map)
Constructor that decorates the specified map and is called from decorate(AbstractHashedMap).
Public Methods
void clear()
Object clone()
Clones the map without cloning the keys or values.
boolean containsKey(Object key1, Object key2, Object key3)
Checks whether the map contains the specified multi-key.
boolean containsKey(Object key1, Object key2, Object key3, Object key4, Object key5)
Checks whether the map contains the specified multi-key.
boolean containsKey(Object key1, Object key2, Object key3, Object key4)
Checks whether the map contains the specified multi-key.
boolean containsKey(Object key1, Object key2)
Checks whether the map contains the specified multi-key.
boolean containsKey(Object key)
boolean containsValue(Object value)
static MultiKeyMap decorate(AbstractHashedMap map)
Decorates the specified map to add the MultiKeyMap API and fast query.
Set entrySet()
boolean equals(Object obj)
Object get(Object key1, Object key2, Object key3, Object key4, Object key5)
Gets the value mapped to the specified multi-key.
Object get(Object key1, Object key2, Object key3, Object key4)
Gets the value mapped to the specified multi-key.
Object get(Object key1, Object key2)
Gets the value mapped to the specified multi-key.
Object get(Object key1, Object key2, Object key3)
Gets the value mapped to the specified multi-key.
Object get(Object key)
int hashCode()
boolean isEmpty()
Set keySet()
MapIterator mapIterator()
Obtains a MapIterator over the map.
Object put(Object key1, Object key2, Object key3, Object key4, Object value)
Stores the value against the specified multi-key.
Object put(Object key1, Object key2, Object value)
Stores the value against the specified multi-key.
Object put(Object key1, Object key2, Object key3, Object value)
Stores the value against the specified multi-key.
Object put(Object key1, Object key2, Object key3, Object key4, Object key5, Object value)
Stores the value against the specified multi-key.
Object put(Object key, Object value)
Puts the key and value into the map, where the key must be a non-null MultiKey object.
void putAll(Map mapToCopy)
Copies all of the keys and values from the specified map to this map.
Object remove(Object key1, Object key2, Object key3)
Removes the specified multi-key from this map.
Object remove(Object key1, Object key2, Object key3, Object key4, Object key5)
Removes the specified multi-key from this map.
Object remove(Object key1, Object key2)
Removes the specified multi-key from this map.
Object remove(Object key1, Object key2, Object key3, Object key4)
Removes the specified multi-key from this map.
Object remove(Object key)
boolean removeAll(Object key1, Object key2, Object key3, Object key4)
Removes all mappings where the first four keys are those specified.
boolean removeAll(Object key1, Object key2)
Removes all mappings where the first two keys are those specified.
boolean removeAll(Object key1)
Removes all mappings where the first key is that specified.
boolean removeAll(Object key1, Object key2, Object key3)
Removes all mappings where the first three keys are those specified.
int size()
String toString()
Collection values()
Protected Methods
void checkKey(Object key)
Check to ensure that input keys are valid MultiKey objects.
int hash(Object key1, Object key2, Object key3, Object key4)
Gets the hash code for the specified multi-key.
int hash(Object key1, Object key2, Object key3, Object key4, Object key5)
Gets the hash code for the specified multi-key.
int hash(Object key1, Object key2, Object key3)
Gets the hash code for the specified multi-key.
int hash(Object key1, Object key2)
Gets the hash code for the specified multi-key.
boolean isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3)
Is the key equal to the combined key.
boolean isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2)
Is the key equal to the combined key.
boolean isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4, Object key5)
Is the key equal to the combined key.
boolean isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4)
Is the key equal to the combined key.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.util.Map
From interface org.apache.commons.collections.IterableMap

Fields

protected final AbstractHashedMap map

The decorated map

Public Constructors

public MultiKeyMap ()

Constructs a new MultiKeyMap that decorates a HashedMap.

Protected Constructors

protected MultiKeyMap (AbstractHashedMap map)

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

Parameters
map the map to decorate

Public Methods

public void clear ()

public Object clone ()

Clones the map without cloning the keys or values.

Returns
  • a shallow clone

public boolean containsKey (Object key1, Object key2, Object key3)

Checks whether the map contains the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
Returns
  • true if the map contains the key

public boolean containsKey (Object key1, Object key2, Object key3, Object key4, Object key5)

Checks whether the map contains the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
key5 the fifth key
Returns
  • true if the map contains the key

public boolean containsKey (Object key1, Object key2, Object key3, Object key4)

Checks whether the map contains the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
Returns
  • true if the map contains the key

public boolean containsKey (Object key1, Object key2)

Checks whether the map contains the specified multi-key.

Parameters
key1 the first key
key2 the second key
Returns
  • true if the map contains the key

public boolean containsKey (Object key)

public boolean containsValue (Object value)

public static MultiKeyMap decorate (AbstractHashedMap map)

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

Parameters
map the map to decorate, not null
Throws
IllegalArgumentException if the map is null or not empty

public Set entrySet ()

public boolean equals (Object obj)

public Object get (Object key1, Object key2, Object key3, Object key4, Object key5)

Gets the value mapped to the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
key5 the fifth key
Returns
  • the mapped value, null if no match

public Object get (Object key1, Object key2, Object key3, Object key4)

Gets the value mapped to the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
Returns
  • the mapped value, null if no match

public Object get (Object key1, Object key2)

Gets the value mapped to the specified multi-key.

Parameters
key1 the first key
key2 the second key
Returns
  • the mapped value, null if no match

public Object get (Object key1, Object key2, Object key3)

Gets the value mapped to the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
Returns
  • the mapped value, null if no match

public Object get (Object key)

public int hashCode ()

public boolean isEmpty ()

public Set keySet ()

public MapIterator 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 cast to Map Entry objects. 

 IterableMap map = new HashedMap();
 MapIterator it = map.mapIterator();
 while (it.hasNext()) {
   Object key = it.next();
   Object value = it.getValue();
   it.setValue("newValue");
 }

Returns
  • a map iterator

public Object put (Object key1, Object key2, Object key3, Object key4, Object value)

Stores the value against the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
value the value to store
Returns
  • the value previously mapped to this combined key, null if none

public Object put (Object key1, Object key2, Object value)

Stores the value against the specified multi-key.

Parameters
key1 the first key
key2 the second key
value the value to store
Returns
  • the value previously mapped to this combined key, null if none

public Object put (Object key1, Object key2, Object key3, Object value)

Stores the value against the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
value the value to store
Returns
  • the value previously mapped to this combined key, null if none

public Object put (Object key1, Object key2, Object key3, Object key4, Object key5, Object value)

Stores the value against the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
key5 the fifth key
value the value to store
Returns
  • the value previously mapped to this combined key, null if none

public Object put (Object key, Object value)

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

Parameters
key the non-null MultiKey object
value the value to store
Returns
  • the previous value for the key
Throws
NullPointerException if the key is null
ClassCastException if the key is not a MultiKey

public void putAll (Map mapToCopy)

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 to this map
Throws
NullPointerException if the mapToCopy or any key within is null
ClassCastException if any key in mapToCopy is not a MultiKey

public Object remove (Object key1, Object key2, Object key3)

Removes the specified multi-key from this map.

Parameters
key1 the first key
key2 the second key
key3 the third key
Returns
  • the value mapped to the removed key, null if key not in map

public Object remove (Object key1, Object key2, Object key3, Object key4, Object key5)

Removes the specified multi-key from this map.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
key5 the fifth key
Returns
  • the value mapped to the removed key, null if key not in map

public Object remove (Object key1, Object key2)

Removes the specified multi-key from this map.

Parameters
key1 the first key
key2 the second key
Returns
  • the value mapped to the removed key, null if key not in map

public Object remove (Object key1, Object key2, Object key3, Object key4)

Removes the specified multi-key from this map.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
Returns
  • the value mapped to the removed key, null if key not in map

public Object remove (Object key)

public boolean removeAll (Object key1, Object key2, Object key3, 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 the first key
key2 the second key
key3 the third key
key4 the fourth key
Returns
  • true if any elements were removed

public boolean removeAll (Object key1, 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 the first key
key2 the second key
Returns
  • true if any elements were removed

public boolean removeAll (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 the first key
Returns
  • true if any elements were removed

public boolean removeAll (Object key1, Object key2, 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 the first key
key2 the second key
key3 the third key
Returns
  • true if any elements were removed

public int size ()

public String toString ()

public Collection values ()

Protected Methods

protected void checkKey (Object key)

Check to ensure that input keys are valid MultiKey objects.

Parameters
key the key to check

protected int hash (Object key1, Object key2, Object key3, Object key4)

Gets the hash code for the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
Returns
  • the hash code

protected int hash (Object key1, Object key2, Object key3, Object key4, Object key5)

Gets the hash code for the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
key5 the fifth key
Returns
  • the hash code

protected int hash (Object key1, Object key2, Object key3)

Gets the hash code for the specified multi-key.

Parameters
key1 the first key
key2 the second key
key3 the third key
Returns
  • the hash code

protected int hash (Object key1, Object key2)

Gets the hash code for the specified multi-key.

Parameters
key1 the first key
key2 the second key
Returns
  • the hash code

protected boolean isEqualKey (AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3)

Is the key equal to the combined key.

Parameters
entry the entry to compare to
key1 the first key
key2 the second key
key3 the third key
Returns
  • true if the key matches

protected boolean isEqualKey (AbstractHashedMap.HashEntry entry, Object key1, Object key2)

Is the key equal to the combined key.

Parameters
entry the entry to compare to
key1 the first key
key2 the second key
Returns
  • true if the key matches

protected boolean isEqualKey (AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4, Object key5)

Is the key equal to the combined key.

Parameters
entry the entry to compare to
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
key5 the fifth key
Returns
  • true if the key matches

protected boolean isEqualKey (AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4)

Is the key equal to the combined key.

Parameters
entry the entry to compare to
key1 the first key
key2 the second key
key3 the third key
key4 the fourth key
Returns
  • true if the key matches