org.apache.commons.collections.map

## Class MultiKeyMap

- 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: 646777 $ $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

  - ### 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`

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.