org.apache.commons.collections4.map

## Class MultiKeyMap<K,V>

- java.lang.Object
- - org.apache.commons.collections4.map.AbstractIterableMap<K,V>
  - - org.apache.commons.collections4.map.AbstractMapDecorator<MultiKey<? extends K>,V>
    - - org.apache.commons.collections4.map.MultiKeyMap<K,V>

- All Implemented Interfaces:
    Serializable, Cloneable, Map<MultiKey<? extends K>,V>, Get<MultiKey<? extends K>,V>, IterableGet<MultiKey<? extends K>,V>, IterableMap<MultiKey<? extends K>,V>, Put<MultiKey<? extends K>,V>

      public class MultiKeyMap<K,V>
      extends AbstractMapDecorator<MultiKey<? extends K>,V>
      implements Serializable, Cloneable

  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.multiKeyMap(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:
    3.1
  Version:
    $Id: MultiKeyMap.java 1543167 2013-11-18 21:21:32Z ggregory $
  See Also:
    Serialized Form

- - ### Nested Class Summary

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

      `Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `MultiKeyMap()` Constructs a new MultiKeyMap that decorates a `HashedMap`.
    `protected` | `MultiKeyMap(AbstractHashedMap<MultiKey<? extends K>,V> map)` Constructor that decorates the specified map and is called from `multiKeyMap(AbstractHashedMap)`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `checkKey(MultiKey<?> key)` Check to ensure that input keys are valid MultiKey objects.
    `MultiKeyMap<K,V>` | `clone()` Clones the map without cloning the keys or values.
    `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.
    `protected AbstractHashedMap<MultiKey<? extends K>,V>` | `decorated()` Gets the map being decorated.
    `V` | `get(Object key1, Object key2)` Gets the value mapped to the specified multi-key.
    `V` | `get(Object key1, Object key2, Object key3)` Gets the value mapped to the specified multi-key.
    `V` | `get(Object key1, Object key2, Object key3, Object key4)` Gets the value mapped to the specified multi-key.
    `V` | `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.
    `protected boolean` | `isEqualKey(AbstractHashedMap.HashEntry<MultiKey<? extends K>,V> entry, Object key1, Object key2)` Is the key equal to the combined key.
    `protected boolean` | `isEqualKey(AbstractHashedMap.HashEntry<MultiKey<? extends K>,V> entry, Object key1, Object key2, Object key3)` Is the key equal to the combined key.
    `protected boolean` | `isEqualKey(AbstractHashedMap.HashEntry<MultiKey<? extends K>,V> entry, Object key1, Object key2, Object key3, Object key4)` Is the key equal to the combined key.
    `protected boolean` | `isEqualKey(AbstractHashedMap.HashEntry<MultiKey<? extends K>,V> entry, Object key1, Object key2, Object key3, Object key4, Object key5)` Is the key equal to the combined key.
    `MapIterator<MultiKey<? extends K>,V>` | `mapIterator()` Obtains a `MapIterator` over the map.
    `static <K,V> MultiKeyMap<K,V>` | `multiKeyMap(AbstractHashedMap<MultiKey<? extends K>,V> map)` Decorates the specified map to add the MultiKeyMap API and fast query.
    `V` | `put(K key1, K key2, K key3, K key4, K key5, V value)` Stores the value against the specified multi-key.
    `V` | `put(K key1, K key2, K key3, K key4, V value)` Stores the value against the specified multi-key.
    `V` | `put(K key1, K key2, K key3, V value)` Stores the value against the specified multi-key.
    `V` | `put(K key1, K key2, V value)` Stores the value against the specified multi-key.
    `V` | `put(MultiKey<? extends K> key, V value)` Puts the key and value into the map, where the key must be a non-null MultiKey object.
    `void` | `putAll(Map<? extends MultiKey<? extends K>,? extends V> mapToCopy)` Copies all of the keys and values from the specified map to 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.
    `V` | `removeMultiKey(Object key1, Object key2)` Removes the specified multi-key from this map.
    `V` | `removeMultiKey(Object key1, Object key2, Object key3)` Removes the specified multi-key from this map.
    `V` | `removeMultiKey(Object key1, Object key2, Object key3, Object key4)` Removes the specified multi-key from this map.
    `V` | `removeMultiKey(Object key1, Object key2, Object key3, Object key4, Object key5)` Removes the specified multi-key from this map.

    - ### Methods inherited from class org.apache.commons.collections4.map.AbstractMapDecorator

      `clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, remove, size, toString, values`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### MultiKeyMap

          public MultiKeyMap()

      Constructs a new MultiKeyMap that decorates a `HashedMap`.

    - #### MultiKeyMap

          protected MultiKeyMap(AbstractHashedMap<MultiKey<? extends K>,V> map)

      Constructor that decorates the specified map and is called from `multiKeyMap(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

    - #### multiKeyMap

          public static <K,V> MultiKeyMap<K,V> multiKeyMap(AbstractHashedMap<MultiKey<? extends K>,V> map)

      Decorates the specified map to add the MultiKeyMap API and fast query. The map must not be null and must be empty.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `map` - the map to decorate, not null
      Returns:
        a new multi key map
      Throws:
        `IllegalArgumentException` - if the map is null or not empty
      Since:
        4.0

    - #### get

          public V 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 V put(K key1,
              K key2,
              V 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

    - #### removeMultiKey

          public V removeMultiKey(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
      Since:
        4.0 (previous name: remove(Object, Object))

    - #### 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<MultiKey<? extends K>,V> 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 V 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 V put(K key1,
              K key2,
              K key3,
              V 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

    - #### removeMultiKey

          public V removeMultiKey(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
      Since:
        4.0 (previous name: remove(Object, Object, Object))

    - #### 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<MultiKey<? extends K>,V> 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 V 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 V put(K key1,
              K key2,
              K key3,
              K key4,
              V 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

    - #### removeMultiKey

          public V removeMultiKey(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
      Since:
        4.0 (previous name: remove(Object, Object, Object, Object))

    - #### 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<MultiKey<? extends K>,V> 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 V 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 V put(K key1,
              K key2,
              K key3,
              K key4,
              K key5,
              V 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

    - #### removeMultiKey

          public V removeMultiKey(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
      Since:
        4.0 (previous name: remove(Object, Object, Object, Object, Object))

    - #### 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<MultiKey<? extends K>,V> 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(MultiKey<?> key)

      Check to ensure that input keys are valid MultiKey objects.
      Parameters:
        `key` - the key to check

    - #### clone

          public MultiKeyMap<K,V> clone()

      Clones the map without cloning the keys or values.
      Overrides:
        `clone` in class `Object`
      Returns:
        a shallow clone

    - #### put

          public V put(MultiKey<? extends K> key,
              V 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<MultiKey<? extends K>,V>`
      Specified by:
        `put` in interface `Put<MultiKey<? extends K>,V>`
      Overrides:
        `put` in class `AbstractMapDecorator<MultiKey<? extends K>,V>`
      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
      See Also:
        `Map.put(Object, Object)`

    - #### putAll

          public void putAll(Map<? extends MultiKey<? extends K>,? extends V> 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<MultiKey<? extends K>,V>`
      Specified by:
        `putAll` in interface `Put<MultiKey<? extends K>,V>`
      Overrides:
        `putAll` in class `AbstractMapDecorator<MultiKey<? extends K>,V>`
      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
      See Also:
        `Map.putAll(Map)`

    - #### mapIterator

          public MapIterator<MultiKey<? extends K>,V> mapIterator()

      Description copied from class: `AbstractIterableMap`
      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 use Map Entry objects.

           IterableMap map = new HashedMap();
           MapIterator it = map.mapIterator();
           while (it.hasNext()) {
             String key = it.next();
             Integer value = it.getValue();
             it.setValue(value + 1);
           }

      Specified by:
        `mapIterator` in interface `IterableGet<MultiKey<? extends K>,V>`
      Overrides:
        `mapIterator` in class `AbstractIterableMap<MultiKey<? extends K>,V>`
      Returns:
        a map iterator

    - #### decorated

          protected AbstractHashedMap<MultiKey<? extends K>,V> decorated()

      Gets the map being decorated.
      Overrides:
        `decorated` in class `AbstractMapDecorator<MultiKey<? extends K>,V>`
      Returns:
        the decorated map

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