org.apache.commons.collections.keyvalue
Class MultiKey<K>

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

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 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: 1.1.1.1 $ $Date: 2005/05/23 04:35:09 $

Author:

Howard Lewis Ship, Matt Hall, John Watkinson, Stephen Colebourne

See Also:

Serialized Form

Constructor Summary

MultiKey(K... keys)
Constructor taking two keys.

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

Method Summary

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.
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 Detail

MultiKey

public MultiKey(K... keys)

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:

keys - the keys

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 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:

IllegalArgumentException - if the key array is null

Since:

Commons Collections 3.1

Method Detail

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

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:

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(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

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

toString

public String toString()

Gets a debugging string version of the key.

Overrides:

toString in class Object

Returns:

a debugging string