MultiKeyMap (Apache Commons Collections 3.2.2 API)

java.lang.Object
- org.apache.commons.collections.map.MultiKeyMap

All Implemented Interfaces:

Serializable, Map, IterableMap
```
public class MultiKeyMap
extends Object
implements IterableMap, Serializable
```
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.
Since:

Commons Collections 3.1

Version:

$Revision: 972404 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $

Author:

Stephen Colebourne

See Also:
Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from interface java.util.Map
  Map.Entry

Field Summary

Fields
Modifier and Type Field and Description

protected AbstractHashedMap map
The decorated map

Fields
Modifier and Type	Field and Description
`protected AbstractHashedMap`	`map` The decorated map

Constructor Summary

Constructors
Modifier	Constructor and Description
	`MultiKeyMap()` Constructs a new MultiKeyMap that decorates a `HashedMap`.
`protected`	`MultiKeyMap(AbstractHashedMap map)` Constructor that decorates the specified map and is called from `decorate(AbstractHashedMap)`.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`checkKey(Object key)` Check to ensure that input keys are valid MultiKey objects.
`void`	`clear()`
`Object`	`clone()` Clones the map without cloning the keys or values.
`boolean`	`containsKey(Object key)`
`boolean`	`containsKey(Object key1, Object key2)` Checks whether the map contains the specified multi-key.
`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)` 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`	`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 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 key1, Object key2, Object key3, Object key4)` Gets the value mapped to the specified multi-key.
`Object`	`get(Object key1, Object key2, Object key3, Object key4, Object key5)` Gets the value mapped to the specified multi-key.
`protected int`	`hash(Object key1, Object key2)` Gets the hash code for the specified multi-key.
`protected int`	`hash(Object key1, Object key2, Object key3)` Gets the hash code for the specified multi-key.
`protected int`	`hash(Object key1, Object key2, Object key3, Object key4)` Gets the hash code for the specified multi-key.
`protected int`	`hash(Object key1, Object key2, Object key3, Object key4, Object key5)` Gets the hash code for the specified multi-key.
`int`	`hashCode()`
`boolean`	`isEmpty()`
`protected boolean`	`isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2)` Is the key equal to the combined key.
`protected boolean`	`isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3)` Is the key equal to the combined key.
`protected boolean`	`isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4)` Is the key equal to the combined key.
`protected boolean`	`isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4, Object key5)` Is the key equal to the combined key.
`Set`	`keySet()`
`MapIterator`	`mapIterator()` Obtains a `MapIterator` over the map.
`Object`	`put(Object key, Object value)` Puts the key and value into the map, where the key must be a non-null MultiKey object.
`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 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.
`void`	`putAll(Map mapToCopy)` Copies all of the keys and values from the specified map to this map.
`Object`	`remove(Object key)`
`Object`	`remove(Object key1, Object key2)` Removes the specified multi-key from 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)` 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.
`boolean`	`removeAll(Object key1)` Removes all mappings where the first key is that specified.
`boolean`	`removeAll(Object key1, Object key2)` Removes all mappings where the first two keys are those specified.
`boolean`	`removeAll(Object key1, Object key2, Object key3)` Removes all mappings where the first three keys are those specified.
`boolean`	`removeAll(Object key1, Object key2, Object key3, Object key4)` Removes all mappings where the first four keys are those specified.
`int`	`size()`
`String`	`toString()`
`Collection`	`values()`

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - map
```
protected final AbstractHashedMap map
```
    The decorated map
- Constructor Detail
  - MultiKeyMap
```
public MultiKeyMap()
```
    Constructs a new MultiKeyMap that decorates a HashedMap.
  - MultiKeyMap
```
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
- Method Detail
  - decorate
```
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
  - get
```
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
  - containsKey
```
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
  - put
```
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
  - remove
```
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
  - hash
```
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
  - isEqualKey
```
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
  - get
```
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
  - containsKey
```
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
  - put
```
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
  - remove
```
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
  - hash
```
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
  - isEqualKey
```
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
  - get
```
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
  - containsKey
```
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
  - put
```
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
  - remove
```
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
  - hash
```
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
  - isEqualKey
```
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
  - get
```
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
  - containsKey
```
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
  - put
```
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
  - remove
```
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
  - hash
```
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
  - isEqualKey
```
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
  - removeAll
```
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
  - removeAll
```
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
  - removeAll
```
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
  - removeAll
```
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
  - checkKey
```
protected void checkKey(Object key)
```
    Check to ensure that input keys are valid MultiKey objects.
    
    Parameters:
    key - the key to check
  - clone
```
public Object clone()
```
    Clones the map without cloning the keys or values.
    
    Overrides:
    
    clone in class Object
    
    Returns:
    a shallow clone
  - put
```
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.
    
    Specified by:
    
    put in interface Map
    
    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
  - putAll
```
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.
    
    Specified by:
    
    putAll in interface Map
    
    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
  - mapIterator
```
public MapIterator mapIterator()
```
    Description copied from interface: IterableMap
    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");
 }
 
```
    Specified by:
    
    mapIterator in interface IterableMap
    
    Returns:
    a map iterator
  - size
```
public int size()
```
    Specified by:
    
    size in interface Map
  - isEmpty
```
public boolean isEmpty()
```
    Specified by:
    
    isEmpty in interface Map
  - containsKey
```
public boolean containsKey(Object key)
```
    Specified by:
    
    containsKey in interface Map
  - containsValue
```
public boolean containsValue(Object value)
```
    Specified by:
    
    containsValue in interface Map
  - get
```
public Object get(Object key)
```
    Specified by:
    
    get in interface Map
  - remove
```
public Object remove(Object key)
```
    Specified by:
    
    remove in interface Map
  - clear
```
public void clear()
```
    Specified by:
    
    clear in interface Map
  - keySet
```
public Set keySet()
```
    Specified by:
    
    keySet in interface Map
  - values
```
public Collection values()
```
    Specified by:
    
    values in interface Map
  - entrySet
```
public Set entrySet()
```
    Specified by:
    
    entrySet in interface Map
  - equals
```
public boolean equals(Object obj)
```
    Specified by:
    
    equals in interface Map
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Specified by:
    
    hashCode in interface Map
    
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class MultiKeyMap

Nested Class Summary

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

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

map

Constructor Detail

MultiKeyMap

MultiKeyMap

Method Detail

decorate

get

containsKey

put

remove

hash

isEqualKey

get

containsKey

put

remove

hash

isEqualKey

get

containsKey

put

remove

hash

isEqualKey

get

containsKey

put

remove

hash

isEqualKey

removeAll

removeAll

removeAll

removeAll

checkKey

clone

put

putAll

mapIterator

size

isEmpty

containsKey

containsValue

get

remove

clear

keySet

values

entrySet

equals

hashCode

toString