Package org.apache.commons.collections4.keyvalue

# Class MultiKey<K>

java.lang.Object
org.apache.commons.collections4.keyvalue.MultiKey<K>

Type Parameters:
  `K` - the type of keys

All Implemented Interfaces:
  `Serializable`

public class MultiKey<K> extends Object implements Serializable
A `MultiKey` allows multiple map keys to be merged together.

The purpose of this class is to avoid the need to write code to handle maps of maps. An example might be the need to look up a file name by key and locale. The typical solution might be nested maps. This class can be used instead by creating an instance passing in the key and locale.

Example usage:

     // populate map with data mapping key+locale to localizedText
     Map map = new HashMap();
     MultiKey multiKey = new MultiKey(key, locale);
     map.put(multiKey, localizedText);

     // later retrieve the localized text
     MultiKey multiKey = new MultiKey(key, locale);
     String localizedText = (String) map.get(multiKey);

Since:
  3.0
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MultiKey(K[] keys)`
  Constructor taking an array of keys which is cloned.
  `MultiKey(K[] keys, boolean makeClone)`
  Constructor taking an array of keys, optionally choosing whether to clone.
  `MultiKey(K key1, K key2)`
  Constructor taking two keys.
  `MultiKey(K key1, K key2, K key3)`
  Constructor taking three keys.
  `MultiKey(K key1, K key2, K key3, K key4)`
  Constructor taking four keys.
  `MultiKey(K key1, K key2, K key3, K key4, K key5)`
  Constructor taking five keys.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object other)`
  Compares this object to another.
  `K`
  `getKey(int index)`
  Gets the key at the specified index.
  `K[]`
  `getKeys()`
  Gets a clone of the array of keys.
  `int`
  `hashCode()`
  Gets the combined hash code that is computed from all the keys.
  `protected Object`
  `readResolve()`
  Recalculate the hash code after deserialization.
  `int`
  `size()`
  Gets the size of the list of keys.
  `String`
  `toString()`
  Gets a debugging string version of the key.

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

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

- ## Constructor Details

  - ### MultiKey

    public MultiKey(K key1, K key2)
    Constructor taking two keys.

    The keys should be immutable. If they are not then they must not be changed after adding to the MultiKey.

    Parameters:
      `key1` - the first key
      `key2` - the second key

  - ### MultiKey

    public MultiKey(K key1, K key2, K key3)
    Constructor taking three keys.

    The keys should be immutable If they are not then they must not be changed after adding to the MultiKey.

    Parameters:
      `key1` - the first key
      `key2` - the second key
      `key3` - the third key

  - ### MultiKey

    public MultiKey(K key1, K key2, K key3, K key4)
    Constructor taking four keys.

    The keys should be immutable. If they are not then they must not be changed after adding to the MultiKey.

    Parameters:
      `key1` - the first key
      `key2` - the second key
      `key3` - the third key
      `key4` - the fourth key

  - ### MultiKey

    public MultiKey(K key1, K key2, K key3, K key4, K key5)
    Constructor taking five keys.

    The keys should be immutable. If they are not then they must not be changed after adding to the MultiKey.

    Parameters:
      `key1` - the first key
      `key2` - the second key
      `key3` - the third key
      `key4` - the fourth key
      `key5` - the fifth key

  - ### MultiKey

    public MultiKey(K[] keys)
    Constructor taking an array of keys which is cloned.

    The keys should be immutable. If they are not then they must not be changed after adding to the MultiKey.

    This is equivalent to `new MultiKey(keys, true)`.

    Parameters:
      `keys` - the array of keys, not null
    Throws:
      `NullPointerException` - if the key array is null

  - ### MultiKey

    public MultiKey(K[] keys, boolean makeClone)
    Constructor taking an array of keys, optionally choosing whether to clone.

    If the array is not cloned, then it must not be modified.

    This method is public for performance reasons only, to avoid a clone. The hash code is calculated once here in this method. Therefore, changing the array passed in would not change the hash code but would change the equals method, which is a bug.

    This is the only fully safe usage of this constructor, as the object array is never made available in a variable:

         new MultiKey(new Object[] {...}, false);

    The keys should be immutable. If they are not then they must not be changed after adding to the MultiKey.

    Parameters:
      `keys` - the array of keys, not null
      `makeClone` - true to clone the array, false to assign it
    Throws:
      `NullPointerException` - if the key array is null
    Since:
      3.1

- ## Method Details

  - ### equals

    public boolean equals(Object other)
    Compares this object to another.

    To be equal, the other object must be a `MultiKey` with the same number of keys which are also equal.

    Overrides:
      `equals` in class `Object`
    Parameters:
      `other` - the other object to compare to
    Returns:
      true if equal

  - ### getKey

    public K getKey(int index)
    Gets the key at the specified index.

    The key should be immutable. If it is not then it must not be changed.

    Parameters:
      `index` - the index to retrieve
    Returns:
      the key at the index
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid
    Since:
      3.1

  - ### getKeys

    public K[] getKeys()
    Gets a clone of the array of keys.

    The keys should be immutable If they are not then they must not be changed.

    Returns:
      the individual keys

  - ### hashCode

    public int hashCode()
    Gets the combined hash code that is computed from all the keys.

    This value is computed once and then cached, so elements should not change their hash codes once created (note that this is the same constraint that would be used if the individual keys elements were themselves `Map` keys).

    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code

  - ### readResolve

    protected Object readResolve()
    Recalculate the hash code after deserialization. The hash code of some keys might have change (hash codes based on the system hash code are only stable for the same process).
    Returns:
      the instance with recalculated hash code

  - ### size

    public int size()
    Gets the size of the list of keys.
    Returns:
      the size of the list of keys
    Since:
      3.1

  - ### toString

    public String toString()
    Gets a debugging string version of the key.
    Overrides:
      `toString` in class `Object`
    Returns:
      a debugging string