org.apache.commons.collections.map

Class MultiKeyMap

public class MultiKeyMap extends Object implements IterableMap, Serializable

A Map implementation that uses multiple keys to map the value.

This class is the most efficient way to uses multiple keys to map to a value. The best way to use this class is via the additional map-style methods. These provide get, containsKey, put and remove for individual keys which operate without extra object creation.

The additional methods are the main interface of this map. As such, you will not normally hold this map in a variable of type Map.

The normal map methods take in and return a MultiKey. If you try to use put() with any other object type a ClassCastException is thrown. If you try to use null as the key in put() a NullPointerException is thrown.

This map is implemented as a decorator of a AbstractHashedMap which enables extra behaviour to be added easily.

Note that IdentityMap and ReferenceIdentityMap are unsuitable for use as the key comparison would work on the whole MultiKey, not the elements within.

As an example, consider a least recently used cache that uses a String airline code and a Locale to lookup the airline's name:

 private MultiKeyMap cache = MultiKeyMap.decorate(new LRUMap(50));
 
 public String getAirlineName(String code, String locale) {
   String name = (String) cache.get(code, locale);
   if (name == null) {
     name = getAirlineNameFromDB(code, locale);
     cache.put(code, locale, name);
   }
   return name;
 }
 

Note that MultiKeyMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization. This class may throw exceptions when accessed by concurrent threads without synchronization.

Since: Commons Collections 3.1

Version: $Revision: 348007 $ $Date: 2005-11-21 22:52:57 +0000 (Mon, 21 Nov 2005) $

Author: Stephen Colebourne

Field Summary
protected AbstractHashedMapmap
The decorated map
Constructor Summary
MultiKeyMap()
Constructs a new MultiKeyMap that decorates a HashedMap.
protected MultiKeyMap(AbstractHashedMap map)
Constructor that decorates the specified map and is called from decorate.
Method Summary
protected voidcheckKey(Object key)
Check to ensure that input keys are valid MultiKey objects.
voidclear()
Objectclone()
Clones the map without cloning the keys or values.
booleancontainsKey(Object key1, Object key2)
Checks whether the map contains the specified multi-key.
booleancontainsKey(Object key1, Object key2, Object key3)
Checks whether the map contains the specified multi-key.
booleancontainsKey(Object key1, Object key2, Object key3, Object key4)
Checks whether the map contains the specified multi-key.
booleancontainsKey(Object key1, Object key2, Object key3, Object key4, Object key5)
Checks whether the map contains the specified multi-key.
booleancontainsKey(Object key)
booleancontainsValue(Object value)
static MultiKeyMapdecorate(AbstractHashedMap map)
Decorates the specified map to add the MultiKeyMap API and fast query.
SetentrySet()
booleanequals(Object obj)
Objectget(Object key1, Object key2)
Gets the value mapped to the specified multi-key.
Objectget(Object key1, Object key2, Object key3)
Gets the value mapped to the specified multi-key.
Objectget(Object key1, Object key2, Object key3, Object key4)
Gets the value mapped to the specified multi-key.
Objectget(Object key1, Object key2, Object key3, Object key4, Object key5)
Gets the value mapped to the specified multi-key.
Objectget(Object key)
protected inthash(Object key1, Object key2)
Gets the hash code for the specified multi-key.
protected inthash(Object key1, Object key2, Object key3)
Gets the hash code for the specified multi-key.
protected inthash(Object key1, Object key2, Object key3, Object key4)
Gets the hash code for the specified multi-key.
protected inthash(Object key1, Object key2, Object key3, Object key4, Object key5)
Gets the hash code for the specified multi-key.
inthashCode()
booleanisEmpty()
protected booleanisEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2)
Is the key equal to the combined key.
protected booleanisEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3)
Is the key equal to the combined key.
protected booleanisEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4)
Is the key equal to the combined key.
protected booleanisEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4, Object key5)
Is the key equal to the combined key.
SetkeySet()
MapIteratormapIterator()
Objectput(Object key1, Object key2, Object value)
Stores the value against the specified multi-key.
Objectput(Object key1, Object key2, Object key3, Object value)
Stores the value against the specified multi-key.
Objectput(Object key1, Object key2, Object key3, Object key4, Object value)
Stores the value against the specified multi-key.
Objectput(Object key1, Object key2, Object key3, Object key4, Object key5, Object value)
Stores the value against the specified multi-key.
Objectput(Object key, Object value)
Puts the key and value into the map, where the key must be a non-null MultiKey object.
voidputAll(Map mapToCopy)
Copies all of the keys and values from the specified map to this map.
Objectremove(Object key1, Object key2)
Removes the specified multi-key from this map.
Objectremove(Object key1, Object key2, Object key3)
Removes the specified multi-key from this map.
Objectremove(Object key1, Object key2, Object key3, Object key4)
Removes the specified multi-key from this map.
Objectremove(Object key1, Object key2, Object key3, Object key4, Object key5)
Removes the specified multi-key from this map.
Objectremove(Object key)
booleanremoveAll(Object key1)
Removes all mappings where the first key is that specified.
booleanremoveAll(Object key1, Object key2)
Removes all mappings where the first two keys are those specified.
booleanremoveAll(Object key1, Object key2, Object key3)
Removes all mappings where the first three keys are those specified.
booleanremoveAll(Object key1, Object key2, Object key3, Object key4)
Removes all mappings where the first four keys are those specified.
intsize()
StringtoString()
Collectionvalues()

Field Detail

map

protected final AbstractHashedMap map
The decorated map

Constructor Detail

MultiKeyMap

public MultiKeyMap()
Constructs a new MultiKeyMap that decorates a HashedMap.

MultiKeyMap

protected MultiKeyMap(AbstractHashedMap map)
Constructor that decorates the specified map and is called from decorate. The map must not be null and should be empty or only contain valid keys. This constructor performs no validation.

Parameters: map the map to decorate

Method Detail

checkKey

protected void checkKey(Object key)
Check to ensure that input keys are valid MultiKey objects.

Parameters: key the key to check

clear

public void clear()

clone

public Object clone()
Clones the map without cloning the keys or values.

Returns: a shallow clone

containsKey

public boolean containsKey(Object key1, Object key2)
Checks whether the map contains the specified multi-key.

Parameters: key1 the first key key2 the second key

Returns: true if the map contains the key

containsKey

public boolean containsKey(Object key1, Object key2, Object key3)
Checks whether the map contains the specified multi-key.

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

Returns: true if the map contains the key

containsKey

public boolean containsKey(Object key1, Object key2, Object key3, Object key4)
Checks whether the map contains the specified multi-key.

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

Returns: true if the map contains the key

containsKey

public boolean containsKey(Object key1, Object key2, Object key3, Object key4, Object key5)
Checks whether the map contains the specified multi-key.

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

Returns: true if the map contains the key

containsKey

public boolean containsKey(Object key)

containsValue

public boolean containsValue(Object value)

decorate

public static MultiKeyMap decorate(AbstractHashedMap map)
Decorates the specified map to add the MultiKeyMap API and fast query. The map must not be null and must be empty.

Parameters: map the map to decorate, not null

Throws: IllegalArgumentException if the map is null or not empty

entrySet

public Set entrySet()

equals

public boolean equals(Object obj)

get

public Object get(Object key1, Object key2)
Gets the value mapped to the specified multi-key.

Parameters: key1 the first key key2 the second key

Returns: the mapped value, null if no match

get

public Object get(Object key1, Object key2, Object key3)
Gets the value mapped to the specified multi-key.

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

Returns: the mapped value, null if no match

get

public Object get(Object key1, Object key2, Object key3, Object key4)
Gets the value mapped to the specified multi-key.

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

Returns: the mapped value, null if no match

get

public Object get(Object key1, Object key2, Object key3, Object key4, Object key5)
Gets the value mapped to the specified multi-key.

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

Returns: the mapped value, null if no match

get

public Object get(Object key)

hash

protected int hash(Object key1, Object key2)
Gets the hash code for the specified multi-key.

Parameters: key1 the first key key2 the second key

Returns: the hash code

hash

protected int hash(Object key1, Object key2, Object key3)
Gets the hash code for the specified multi-key.

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

Returns: the hash code

hash

protected int hash(Object key1, Object key2, Object key3, Object key4)
Gets the hash code for the specified multi-key.

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

Returns: the hash code

hash

protected int hash(Object key1, Object key2, Object key3, Object key4, Object key5)
Gets the hash code for the specified multi-key.

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

Returns: the hash code

hashCode

public int hashCode()

isEmpty

public boolean isEmpty()

isEqualKey

protected boolean isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2)
Is the key equal to the combined key.

Parameters: entry the entry to compare to key1 the first key key2 the second key

Returns: true if the key matches

isEqualKey

protected boolean isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3)
Is the key equal to the combined key.

Parameters: entry the entry to compare to key1 the first key key2 the second key key3 the third key

Returns: true if the key matches

isEqualKey

protected boolean isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4)
Is the key equal to the combined key.

Parameters: entry the entry to compare to key1 the first key key2 the second key key3 the third key key4 the fourth key

Returns: true if the key matches

isEqualKey

protected boolean isEqualKey(AbstractHashedMap.HashEntry entry, Object key1, Object key2, Object key3, Object key4, Object key5)
Is the key equal to the combined key.

Parameters: entry the entry to compare to key1 the first key key2 the second key key3 the third key key4 the fourth key key5 the fifth key

Returns: true if the key matches

keySet

public Set keySet()

mapIterator

public MapIterator mapIterator()

put

public Object put(Object key1, Object key2, Object value)
Stores the value against the specified multi-key.

Parameters: key1 the first key key2 the second key value the value to store

Returns: the value previously mapped to this combined key, null if none

put

public Object put(Object key1, Object key2, Object key3, Object value)
Stores the value against the specified multi-key.

Parameters: key1 the first key key2 the second key key3 the third key value the value to store

Returns: the value previously mapped to this combined key, null if none

put

public Object put(Object key1, Object key2, Object key3, Object key4, Object value)
Stores the value against the specified multi-key.

Parameters: key1 the first key key2 the second key key3 the third key key4 the fourth key value the value to store

Returns: the value previously mapped to this combined key, null if none

put

public Object put(Object key1, Object key2, Object key3, Object key4, Object key5, Object value)
Stores the value against the specified multi-key.

Parameters: key1 the first key key2 the second key key3 the third key key4 the fourth key key5 the fifth key value the value to store

Returns: the value previously mapped to this combined key, null if none

put

public Object put(Object key, Object value)
Puts the key and value into the map, where the key must be a non-null MultiKey object.

Parameters: key the non-null MultiKey object value the value to store

Returns: the previous value for the key

Throws: NullPointerException if the key is null ClassCastException if the key is not a MultiKey

putAll

public void putAll(Map mapToCopy)
Copies all of the keys and values from the specified map to this map. Each key must be non-null and a MultiKey object.

Parameters: mapToCopy to this map

Throws: NullPointerException if the mapToCopy or any key within is null ClassCastException if any key in mapToCopy is not a MultiKey

remove

public Object remove(Object key1, Object key2)
Removes the specified multi-key from this map.

Parameters: key1 the first key key2 the second key

Returns: the value mapped to the removed key, null if key not in map

remove

public Object remove(Object key1, Object key2, Object key3)
Removes the specified multi-key from this map.

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

Returns: the value mapped to the removed key, null if key not in map

remove

public Object remove(Object key1, Object key2, Object key3, Object key4)
Removes the specified multi-key from this map.

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

Returns: the value mapped to the removed key, null if key not in map

remove

public Object remove(Object key1, Object key2, Object key3, Object key4, Object key5)
Removes the specified multi-key from this map.

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

Returns: the value mapped to the removed key, null if key not in map

remove

public Object remove(Object key)

removeAll

public boolean removeAll(Object key1)
Removes all mappings where the first key is that specified.

This method removes all the mappings where the MultiKey has one or more keys, and the first matches that specified.

Parameters: key1 the first key

Returns: true if any elements were removed

removeAll

public boolean removeAll(Object key1, Object key2)
Removes all mappings where the first two keys are those specified.

This method removes all the mappings where the MultiKey has two or more keys, and the first two match those specified.

Parameters: key1 the first key key2 the second key

Returns: true if any elements were removed

removeAll

public boolean removeAll(Object key1, Object key2, Object key3)
Removes all mappings where the first three keys are those specified.

This method removes all the mappings where the MultiKey has three or more keys, and the first three match those specified.

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

Returns: true if any elements were removed

removeAll

public boolean removeAll(Object key1, Object key2, Object key3, Object key4)
Removes all mappings where the first four keys are those specified.

This method removes all the mappings where the MultiKey has four or more keys, and the first four match those specified.

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

Returns: true if any elements were removed

size

public int size()

toString

public String toString()

values

public Collection values()
Copyright © 2001-2008 Apache Software Foundation. All Rights Reserved.