net.sf.eBus.util

Class MultiKey

java.lang.Object

net.sf.eBus.util.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:

   
     Object[] keys;
     int i;
     int hashCode;

     for (i = 0, hashCode = 0; i < keys.length; ++i)
     {
         if (keys[i] != null)
         {
             hashCode ^= keys[i].hashCode();
         }
     }
   
 

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 discrepency 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 and Description
MultiKey(Object... keys) Creates a multiple key container for the given objects.

Method Summary

Modifier and Type	Method and 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.

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiKey

public MultiKey(Object... keys)
         throws IndexOutOfBoundsException

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)
              throws ClassCastException

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.

size

public int size()

Returns the number of key values.

Returns:

the number of key values.

key

public Object key(int index)
           throws IndexOutOfBoundsException

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.

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.