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

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

All Implemented Interfaces:
  IterableMap, Map, Serializable

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;
     }

Since:
  Commons Collections 3.1
Version:
  $Revision: 1.3 $ $Date: 2004/06/07 21:00:58 $
Author:
  Stephen Colebourne
See Also:
  Serialized Form

Nested Class Summary

Nested classes inherited from class java.util.Map
`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(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)` Puts all the keys and values into 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.

  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)

  Puts all the keys and values into this map. Each key must be non-null and a MultiKey object.

  Specified by:
    `putAll` in interface `Map`
  Returns:
    the previous value for the key
  Throws:
    `NullPointerException` - if the mapToCopy or any key within is null
    `ClassCastException` - if any key 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`

### hashCode

    public int hashCode()

  Specified by:
    `hashCode` in interface `Map`

### toString

    public String toString()

Copyright © 2001-2005 Apache Software Foundation. All Rights Reserved.