## org.apache.commons.collections.map
Class MultiKeyMap

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

All Implemented Interfaces:
  java.io.Serializable, java.util.Map, IterableMap

    public class MultiKeyMap

extends java.lang.Object
implements IterableMap, java.io.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: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Stephen Colebourne
See Also:
  Serialized Form

Nested Class Summary

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

Field Summary
`protected AbstractHashedMap` `map` The decorated map

Constructor Summary
`` `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
`protected void` `checkKey(java.lang.Object key)` Check to ensure that input keys are valid MultiKey objects.
`void` `clear()`
`java.lang.Object` `clone()` Clones the map without cloning the keys or values.
`boolean` `containsKey(java.lang.Object key)`
`boolean` `containsKey(java.lang.Object key1, java.lang.Object key2)` Checks whether the map contains the specified multi-key.
`boolean` `containsKey(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3)` Checks whether the map contains the specified multi-key.
`boolean` `containsKey(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4)` Checks whether the map contains the specified multi-key.
`boolean` `containsKey(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4, java.lang.Object key5)` Checks whether the map contains the specified multi-key.
`boolean` `containsValue(java.lang.Object value)`
`static MultiKeyMap` `decorate(AbstractHashedMap map)` Decorates the specified map to add the MultiKeyMap API and fast query.
`java.util.Set` `entrySet()`
`boolean` `equals(java.lang.Object obj)`
`java.lang.Object` `get(java.lang.Object key)`
`java.lang.Object` `get(java.lang.Object key1, java.lang.Object key2)` Gets the value mapped to the specified multi-key.
`java.lang.Object` `get(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3)` Gets the value mapped to the specified multi-key.
`java.lang.Object` `get(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4)` Gets the value mapped to the specified multi-key.
`java.lang.Object` `get(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4, java.lang.Object key5)` Gets the value mapped to the specified multi-key.
`protected int` `hash(java.lang.Object key1, java.lang.Object key2)` Gets the hash code for the specified multi-key.
`protected int` `hash(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3)` Gets the hash code for the specified multi-key.
`protected int` `hash(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4)` Gets the hash code for the specified multi-key.
`protected int` `hash(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4, java.lang.Object key5)` Gets the hash code for the specified multi-key.
`int` `hashCode()`
`boolean` `isEmpty()`
`protected boolean` `isEqualKey(AbstractHashedMap.HashEntry entry, java.lang.Object key1, java.lang.Object key2)` Is the key equal to the combined key.
`protected boolean` `isEqualKey(AbstractHashedMap.HashEntry entry, java.lang.Object key1, java.lang.Object key2, java.lang.Object key3)` Is the key equal to the combined key.
`protected boolean` `isEqualKey(AbstractHashedMap.HashEntry entry, java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4)` Is the key equal to the combined key.
`protected boolean` `isEqualKey(AbstractHashedMap.HashEntry entry, java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4, java.lang.Object key5)` Is the key equal to the combined key.
`java.util.Set` `keySet()`
`MapIterator` `mapIterator()` Obtains a `MapIterator` over the map.
`java.lang.Object` `put(java.lang.Object key, java.lang.Object value)` Puts the key and value into the map, where the key must be a non-null MultiKey object.
`java.lang.Object` `put(java.lang.Object key1, java.lang.Object key2, java.lang.Object value)` Stores the value against the specified multi-key.
`java.lang.Object` `put(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object value)` Stores the value against the specified multi-key.
`java.lang.Object` `put(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4, java.lang.Object value)` Stores the value against the specified multi-key.
`java.lang.Object` `put(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4, java.lang.Object key5, java.lang.Object value)` Stores the value against the specified multi-key.
`void` `putAll(java.util.Map mapToCopy)` Copies all of the keys and values from the specified map to this map.
`java.lang.Object` `remove(java.lang.Object key)`
`java.lang.Object` `remove(java.lang.Object key1, java.lang.Object key2)` Removes the specified multi-key from this map.
`java.lang.Object` `remove(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3)` Removes the specified multi-key from this map.
`java.lang.Object` `remove(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4)` Removes the specified multi-key from this map.
`java.lang.Object` `remove(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4, java.lang.Object key5)` Removes the specified multi-key from this map.
`boolean` `removeAll(java.lang.Object key1)` Removes all mappings where the first key is that specified.
`boolean` `removeAll(java.lang.Object key1, java.lang.Object key2)` Removes all mappings where the first two keys are those specified.
`boolean` `removeAll(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3)` Removes all mappings where the first three keys are those specified.
`boolean` `removeAll(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4)` Removes all mappings where the first four keys are those specified.
`int` `size()`
`java.lang.String` `toString()`
`java.util.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:
    `java.lang.IllegalArgumentException` - if the map is null or not empty

### get

    public java.lang.Object get(java.lang.Object key1,
                                java.lang.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(java.lang.Object key1,
                               java.lang.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 java.lang.Object put(java.lang.Object key1,
                                java.lang.Object key2,
                                java.lang.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 java.lang.Object remove(java.lang.Object key1,
                                   java.lang.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(java.lang.Object key1,
                       java.lang.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,
                                 java.lang.Object key1,
                                 java.lang.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 java.lang.Object get(java.lang.Object key1,
                                java.lang.Object key2,
                                java.lang.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(java.lang.Object key1,
                               java.lang.Object key2,
                               java.lang.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 java.lang.Object put(java.lang.Object key1,
                                java.lang.Object key2,
                                java.lang.Object key3,
                                java.lang.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 java.lang.Object remove(java.lang.Object key1,
                                   java.lang.Object key2,
                                   java.lang.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(java.lang.Object key1,
                       java.lang.Object key2,
                       java.lang.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,
                                 java.lang.Object key1,
                                 java.lang.Object key2,
                                 java.lang.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 java.lang.Object get(java.lang.Object key1,
                                java.lang.Object key2,
                                java.lang.Object key3,
                                java.lang.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(java.lang.Object key1,
                               java.lang.Object key2,
                               java.lang.Object key3,
                               java.lang.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 java.lang.Object put(java.lang.Object key1,
                                java.lang.Object key2,
                                java.lang.Object key3,
                                java.lang.Object key4,
                                java.lang.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 java.lang.Object remove(java.lang.Object key1,
                                   java.lang.Object key2,
                                   java.lang.Object key3,
                                   java.lang.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(java.lang.Object key1,
                       java.lang.Object key2,
                       java.lang.Object key3,
                       java.lang.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,
                                 java.lang.Object key1,
                                 java.lang.Object key2,
                                 java.lang.Object key3,
                                 java.lang.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 java.lang.Object get(java.lang.Object key1,
                                java.lang.Object key2,
                                java.lang.Object key3,
                                java.lang.Object key4,
                                java.lang.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(java.lang.Object key1,
                               java.lang.Object key2,
                               java.lang.Object key3,
                               java.lang.Object key4,
                               java.lang.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 java.lang.Object put(java.lang.Object key1,
                                java.lang.Object key2,
                                java.lang.Object key3,
                                java.lang.Object key4,
                                java.lang.Object key5,
                                java.lang.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 java.lang.Object remove(java.lang.Object key1,
                                   java.lang.Object key2,
                                   java.lang.Object key3,
                                   java.lang.Object key4,
                                   java.lang.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(java.lang.Object key1,
                       java.lang.Object key2,
                       java.lang.Object key3,
                       java.lang.Object key4,
                       java.lang.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,
                                 java.lang.Object key1,
                                 java.lang.Object key2,
                                 java.lang.Object key3,
                                 java.lang.Object key4,
                                 java.lang.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(java.lang.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(java.lang.Object key1,
                             java.lang.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(java.lang.Object key1,
                             java.lang.Object key2,
                             java.lang.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(java.lang.Object key1,
                             java.lang.Object key2,
                             java.lang.Object key3,
                             java.lang.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(java.lang.Object key)

  Check to ensure that input keys are valid MultiKey objects.

  Parameters:
    `key` - the key to check

### clone

    public java.lang.Object clone()

  Clones the map without cloning the keys or values.

  Overrides:
    `clone` in class `java.lang.Object`
  Returns:
    a shallow clone

### put

    public java.lang.Object put(java.lang.Object key,
                                java.lang.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 `java.util.Map`
  Parameters:
    `key` - the non-null MultiKey object
    `value` - the value to store
  Returns:
    the previous value for the key
  Throws:
    `java.lang.NullPointerException` - if the key is null
    `java.lang.ClassCastException` - if the key is not a MultiKey

### putAll

    public void putAll(java.util.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 `java.util.Map`
  Parameters:
    `mapToCopy` - to this map
  Throws:
    `java.lang.NullPointerException` - if the mapToCopy or any key within is null
    `java.lang.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 `java.util.Map`

### isEmpty

    public boolean isEmpty()

  Specified by:
    `isEmpty` in interface `java.util.Map`

### containsKey

    public boolean containsKey(java.lang.Object key)

  Specified by:
    `containsKey` in interface `java.util.Map`

### containsValue

    public boolean containsValue(java.lang.Object value)

  Specified by:
    `containsValue` in interface `java.util.Map`

### get

    public java.lang.Object get(java.lang.Object key)

  Specified by:
    `get` in interface `java.util.Map`

### remove

    public java.lang.Object remove(java.lang.Object key)

  Specified by:
    `remove` in interface `java.util.Map`

### clear

    public void clear()

  Specified by:
    `clear` in interface `java.util.Map`

### keySet

    public java.util.Set keySet()

  Specified by:
    `keySet` in interface `java.util.Map`

### values

    public java.util.Collection values()

  Specified by:
    `values` in interface `java.util.Map`

### entrySet

    public java.util.Set entrySet()

  Specified by:
    `entrySet` in interface `java.util.Map`

### equals

    public boolean equals(java.lang.Object obj)

  Specified by:
    `equals` in interface `java.util.Map`
  Overrides:
    `equals` in class `java.lang.Object`

### hashCode

    public int hashCode()

  Specified by:
    `hashCode` in interface `java.util.Map`
  Overrides:
    `hashCode` in class `java.lang.Object`

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `java.lang.Object`

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.