Package net.sf.eBus.util

Class MultiKey

  • All Implemented Interfaces:
    Serializable, Comparable<MultiKey>
    Direct Known Subclasses:
    MultiKey2, MultiKey3, MultiKey4
    public class MultiKey
extends Object
implements Comparable<MultiKey>, Serializable
    Allows multi-valued keys to be used in Java's single key Map collections. If an Order object is associated with a tuple (String customer, Date timestamp, OrderId id), Java cannot handle multi-object keys but only a single object key. The solutions to this mismatch is:
    1. Use nested Map objects: Map<String, Map<Date, Map<OrderId, Order>>>. This solution is both cumbersome to implement, uses much memory and is not recommended.
    2. Write a class to store the tuple objects and provides the appropriate hash code for the key values. This is the only solution if MultiKey's hash code is insufficient.
    MultiMap stores multiple key values in a general class obviating the need to write a proprietary key class. The hash code algorithm is Arrays.hashCode(Object[]). Note: that Arrays.hashCode(Object[]) allows Object[] to contain null references.

    Unlike a proprietary key class, MultiKey cannot enforce key value number and type requirements. It is possible to use keys of differing lengths and type within the same map. If MultiKey's size and type ordering enforcement is required, use the subclasses MultiKey2, MultiKey3 or MultiKey4.

    It is recommended that only immutable objects be used in the key but if mutable objects are used and are modified after creating the MultiKey, the MultiKey hash code is unaffected because the hash code is calculated once in the constructor. This results in a discrepancy between the key's values and hash code.

    Since:
    Commons Collections 3.0
    Version:
    $Revision: 1.1 $ $Date: 2005/10/28 14:37:52 $
    Author:
    Howard Lewis Ship, Stephen Colebourne, Charles W. Rapp
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      MultiKey​(Object... keys)
      Creates a multiple key container for the given objects.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(MultiKey key)
      Returns a negative integer, zero or a positive integer if this object is less than, equal to or greater than the argument, respectively.
      boolean equals​(Object o)
      Returns true if key is a non-null MultiKey instance with the same number of key values and the key values are equal and in the same order.
      int hashCode()
      Returns a hash code value for this multi-valued key.
      Object key​(int index)
      Returns the key value at the specified index.
      Object[] keys()
      Returns a copy of the key array.
      int size()
      Returns the number of key values.
      String toString()
      Returns a textual representation of this multi-valued key.

    • Constructor Detail

      • MultiKey

        public MultiKey​(Object... keys)
        Creates a multiple key container for the given objects.
        Parameters:
        keys - One or more key objects. May contain null references.
        Throws:
        IndexOutOfBoundsException - if no keys are specified.

    • Method Detail

      • compareTo

        public int compareTo​(MultiKey key)
        Returns a negative integer, zero or a positive integer if this object is less than, equal to or greater than the argument, respectively.

        The comparison is done as follows:

        1. If this key's size does not equal key's size, then returns this.size() - key.size().
        2. Otherwise iterates over the keys, comparing each key in turn until a non-zero value is found or all the keys are compared.
        Specified by:
        compareTo in interface Comparable<MultiKey>
        Parameters:
        key - compare against this multi-valued key.
        Returns:
        a negative integer, zero or a positive integer if this object is less than, equal to or greater than the argument, respectively.
        Throws:
        ClassCastException - if the keys contain incompatible or incomparable types.

      • equals

        public boolean equals​(Object o)
        Returns true if key is a non-null MultiKey instance with the same number of key values and the key values are equal and in the same order. Returns false otherwise.
        Overrides:
        equals in class Object
        Parameters:
        o - Test equality with this object.
        Returns:
        true if key is a non-null MultiKey instance with the same number of key values and the key values are equal and in the same order; false otherwise.

      • hashCode

        public int hashCode()
        Returns a hash code value for this multi-valued key.

        The hash code is calculated once in the constructor and cached. If any key objects is modified after construction, its new hash code will not be reflected in this MultiKey object's hash code.

        The hash code calculation is: 

           
     Object[] keys;
     int i;
     int hashCode;

     for (i = 0, hashCode = 0; i < keys.length; ++i)
     {
         if (keys[i] != null)
         {
             hashCode ^= keys[i].hashCode();
         }
     }
        Overrides:
        hashCode in class Object
        Returns:
        a hash code value for this multi-valued key.

      • toString

        public String toString()
        Returns a textual representation of this multi-valued key.
        Overrides:
        toString in class Object
        Returns:
        a textual representation of this multi-valued key.

      • size

        public int size()
        Returns the number of key values.
        Returns:
        the number of key values.

      • key

        public Object key​(int index)
        Returns the key value at the specified index.

        If the returned object is mutable, modifying it will result in unspecified behavior by the map.

        Parameters:
        index - Index to desired key value.
        Returns:
        the key value at the specified index.
        Throws:
        IndexOutOfBoundsException - if index is either < zero or > key size.

      • keys

        public Object[] keys()
        Returns a copy of the key array.

        If any of the returned key objects is mutable, modifying a key will result in unspecified behavior by the map.

        Returns:
        the key array copy.