Class MultiKey

  • All Implemented Interfaces:
    java.io.Serializable

    public class MultiKey
    extends java.lang.Object
    implements java.io.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 lookup a filename 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 retireve the localized text
     MultiKey multiKey = new MultiKey(key, locale);
     String localizedText = (String) map.get(multiKey);
     
    Since:
    Commons Collections 3.0
    Version:
    $Revision: 1713176 $ $Date: 2015-11-07 21:53:57 +0100 (Sat, 07 Nov 2015) $
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private int hashCode
      The cached hashCode
      private java.lang.Object[] keys
      The individual keys
      private static long serialVersionUID
      Serialisation version
    • Constructor Summary

      Constructors 
      Constructor Description
      MultiKey​(java.lang.Object[] keys)
      Constructor taking an array of keys which is cloned.
      MultiKey​(java.lang.Object[] keys, boolean makeClone)
      Constructor taking an array of keys, optionally choosing whether to clone.
      MultiKey​(java.lang.Object key1, java.lang.Object key2)
      Constructor taking two keys.
      MultiKey​(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3)
      Constructor taking three keys.
      MultiKey​(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4)
      Constructor taking four keys.
      MultiKey​(java.lang.Object key1, java.lang.Object key2, java.lang.Object key3, java.lang.Object key4, java.lang.Object key5)
      Constructor taking five keys.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void calculateHashCode​(java.lang.Object[] keys)
      Calculate the hash code of the instance using the provided keys.
      boolean equals​(java.lang.Object other)
      Compares this object to another.
      java.lang.Object getKey​(int index)
      Gets the key at the specified index.
      java.lang.Object[] getKeys()
      Gets a clone of the array of keys.
      int hashCode()
      Gets the combined hash code that is computed from all the keys.
      private java.lang.Object readResolve()
      Recalculate the hash code after deserialization.
      int size()
      Gets the size of the list of keys.
      java.lang.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
    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Serialisation version
        See Also:
        Constant Field Values
      • keys

        private final java.lang.Object[] keys
        The individual keys
      • hashCode

        private transient int hashCode
        The cached hashCode
    • Constructor Detail

      • MultiKey

        public MultiKey​(java.lang.Object key1,
                        java.lang.Object 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​(java.lang.Object key1,
                        java.lang.Object key2,
                        java.lang.Object 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​(java.lang.Object key1,
                        java.lang.Object key2,
                        java.lang.Object key3,
                        java.lang.Object 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​(java.lang.Object key1,
                        java.lang.Object key2,
                        java.lang.Object key3,
                        java.lang.Object key4,
                        java.lang.Object 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​(java.lang.Object[] 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:
        java.lang.IllegalArgumentException - if the key array is null
      • MultiKey

        public MultiKey​(java.lang.Object[] 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 hashcode is calculated once here in this method. Therefore, changing the array passed in would not change the hashcode 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:
        java.lang.IllegalArgumentException - if the key array is null
        Since:
        Commons Collections 3.1
    • Method Detail

      • getKeys

        public java.lang.Object[] 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
      • getKey

        public java.lang.Object 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:
        java.lang.IndexOutOfBoundsException - if the index is invalid
        Since:
        Commons Collections 3.1
      • size

        public int size()
        Gets the size of the list of keys.
        Returns:
        the size of the list of keys
        Since:
        Commons Collections 3.1
      • equals

        public boolean equals​(java.lang.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 java.lang.Object
        Parameters:
        other - the other object to compare to
        Returns:
        true if equal
      • 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 java.lang.Object
        Returns:
        the hash code
      • toString

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

        private void calculateHashCode​(java.lang.Object[] keys)
        Calculate the hash code of the instance using the provided keys.
        Parameters:
        keys -
      • readResolve

        private java.lang.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