org.apache.commons.collections.map
Class MultiKeyMap<K,V>

java.lang.Object
  extended by org.apache.commons.collections.map.MultiKeyMap<K,V>
All Implemented Interfaces:
Serializable, Map<MultiKey<K>,V>, IterableMap<MultiKey<K>,V>

public class MultiKeyMap<K,V>
extends Object
implements IterableMap<MultiKey<K>,V>, 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; }

Since:
Commons Collections 3.1
Version:
$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:35:59 $
Author:
Matt Hall, John Watkinson, Stephen Colebourne
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
 
Field Summary
protected  AbstractHashedMap<MultiKey<K>,V> map
          The decorated map
 
Constructor Summary
  MultiKeyMap()
          Constructs a new MultiKeyMap that decorates a HashedMap.
protected MultiKeyMap(AbstractHashedMap<MultiKey<K>,V> map)
          Constructor that decorates the specified map and is called from decorate(AbstractHashedMap).
 
Method Summary
protected  void checkKey(Object key)
          Check to ensure that input keys are valid MultiKey objects.
 void clear()
           
 Object clone()
          Clones the map without cloning the keys or values.
 boolean containsKey(K... keys)
          Checks whether the map contains the specified multi-key.
 boolean containsKey(Object key)
           
 boolean containsValue(Object value)
           
static
<K,V> MultiKeyMap<K,V>
decorate(AbstractHashedMap<MultiKey<K>,V> map)
          Decorates the specified map to add the MultiKeyMap API and fast query.
 Set entrySet()
           
 boolean equals(Object obj)
           
 V get(K... keys)
          Gets the value mapped to the specified multi-key.
 V get(Object key)
           
protected  int hash(K... keys)
          Gets the hash code for the specified multi-key.
 int hashCode()
           
 boolean isEmpty()
           
protected  boolean isEqualKey(AbstractHashedMap.HashEntry<MultiKey<K>,V> entry, K... keys)
          Is the key equal to the combined key.
 Set keySet()
           
 MapIterator mapIterator()
          Obtains a MapIterator over the map.
 V put(K key1, K key2, K key3, K key4, K key5, V value)
          For backwards compatibility, makes a call to the new varargs putMultiKey(V, K...)
 V put(K key1, K key2, K key3, K key4, V value)
          For backwards compatibility, makes a call to the new varargs putMultiKey(V, K...)
 V put(K key1, K key2, K key3, V value)
          For backwards compatibility, makes a call to the new varargs putMultiKey(V, K...)
 V put(K key1, K key2, V value)
          For backwards compatibility, makes a call to the new varargs putMultiKey(V, K...)
 V put(MultiKey<K> key, V value)
          Puts the key and value into the map, where the key must be a non-null MultiKey object.
 void putAll(Map<? extends MultiKey<K>,? extends V> mapToCopy)
          Puts all the keys and values into this map.
 V putMultiKey(V value, K... keys)
          Stores the value against the specified multi-key.
 Object remove(K... keys)
          Removes the specified multi-key from this map.
 V remove(Object key)
           
 boolean removeAll(Object key1)
          Removes all mappings where the first key is that specified.
 boolean removeAll(Object key1, Object key2)
          Removes all mappings where the first two keys are those specified.
 boolean removeAll(Object key1, Object key2, Object key3)
          Removes all mappings where the first three keys are those specified.
 boolean removeAll(Object key1, Object key2, Object key3, Object key4)
          Removes all mappings where the first four keys are those specified.
 int size()
           
 String toString()
           
 Collection values()
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

map

protected final AbstractHashedMap<MultiKey<K>,V> map
The decorated map

Constructor Detail

MultiKeyMap

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


MultiKeyMap

protected MultiKeyMap(AbstractHashedMap<MultiKey<K>,V> map)
Constructor that decorates the specified map and is called from decorate(AbstractHashedMap). 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

decorate

public static <K,V> MultiKeyMap<K,V> decorate(AbstractHashedMap<MultiKey<K>,V> 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

get

public V get(K... keys)
Gets the value mapped to the specified multi-key.

Parameters:
keys - the keys
Returns:
the mapped value, null if no match

containsKey

public boolean containsKey(K... keys)
Checks whether the map contains the specified multi-key.

Parameters:
keys - the keys
Returns:
true if the map contains the key

put

public V put(K key1,
             K key2,
             V value)
For backwards compatibility, makes a call to the new varargs putMultiKey(V, K...)


put

public V put(K key1,
             K key2,
             K key3,
             V value)
For backwards compatibility, makes a call to the new varargs putMultiKey(V, K...)


put

public V put(K key1,
             K key2,
             K key3,
             K key4,
             V value)
For backwards compatibility, makes a call to the new varargs putMultiKey(V, K...)


put

public V put(K key1,
             K key2,
             K key3,
             K key4,
             K key5,
             V value)
For backwards compatibility, makes a call to the new varargs putMultiKey(V, K...)


putMultiKey

public V putMultiKey(V value,
                     K... keys)
Stores the value against the specified multi-key.

Parameters:
value - the value to store
keys - the keys
Returns:
the value previously mapped to this combined key, null if none

remove

public Object remove(K... keys)
Removes the specified multi-key from this map.

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

hash

protected int hash(K... keys)
Gets the hash code for the specified multi-key.

Parameters:
keys - the keys
Returns:
the hash code

isEqualKey

protected boolean isEqualKey(AbstractHashedMap.HashEntry<MultiKey<K>,V> entry,
                             K... keys)
Is the key equal to the combined key.

Parameters:
entry - the entry to compare to
keys - the keys
Returns:
true if the key matches

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

checkKey

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

Parameters:
key - the key to check

clone

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

Overrides:
clone in class Object
Returns:
a shallow clone

put

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

Specified by:
put in interface Map<MultiKey<K>,V>
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<? extends MultiKey<K>,? extends V> mapToCopy)
Puts all the keys and values into this map. Each key must be non-null and a MultiKey object.

Specified by:
putAll in interface Map<MultiKey<K>,V>
Parameters:
mapToCopy - the map to copy in.
Throws:
NullPointerException - if the mapToCopy or any key within is null
ClassCastException - if any key is not a MultiKey

mapIterator

public MapIterator mapIterator()
Description copied from interface: IterableMap
Obtains a MapIterator over the map.

A map iterator is an efficient way of iterating over maps. There is no need to access the entry set or cast to Map Entry objects.

 IterableMap map = new HashedMap();
 MapIterator it = map.mapIterator();
 while (it.hasNext()) {
   Object key = it.next();
   Object value = it.getValue();
   it.setValue("newValue");
 }
 

Specified by:
mapIterator in interface IterableMap<MultiKey<K>,V>
Returns:
a map iterator

size

public int size()
Specified by:
size in interface Map<MultiKey<K>,V>

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface Map<MultiKey<K>,V>

containsKey

public boolean containsKey(Object key)
Specified by:
containsKey in interface Map<MultiKey<K>,V>

containsValue

public boolean containsValue(Object value)
Specified by:
containsValue in interface Map<MultiKey<K>,V>

get

public V get(Object key)
Specified by:
get in interface Map<MultiKey<K>,V>

remove

public V remove(Object key)
Specified by:
remove in interface Map<MultiKey<K>,V>

clear

public void clear()
Specified by:
clear in interface Map<MultiKey<K>,V>

keySet

public Set keySet()
Specified by:
keySet in interface Map<MultiKey<K>,V>

values

public Collection values()
Specified by:
values in interface Map<MultiKey<K>,V>

entrySet

public Set entrySet()
Specified by:
entrySet in interface Map<MultiKey<K>,V>

equals

public boolean equals(Object obj)
Specified by:
equals in interface Map<MultiKey<K>,V>
Overrides:
equals in class Object

hashCode

public int hashCode()
Specified by:
hashCode in interface Map<MultiKey<K>,V>
Overrides:
hashCode in class Object

toString

public String toString()
Overrides:
toString in class Object


Copyright © 2005-2005 Apache Software Foundation, Matt Hall, John Watkinson. All Rights Reserved.