net.rim.device.api.util
Class MultiMap

java.lang.Object
  net.rim.device.api.util.MultiMap

All Implemented Interfaces:

Persistable

public class MultiMap
extends Object
implements Persistable

Provides a one to many mapping between a key and some values.

Constructor Summary

MultiMap()
Constructs a new MultiMap instance.

MultiMap(int initialHashtableCapacity, int initialVectorCapacity)
Constructs a new MultiMap instance with the provided capacity.

Method Summary
boolean	add(Object key, Object value) Maps value to key.
void	clear() Removes all keys and values.
boolean	containsKey(Object key) Determines if key is mapped.
boolean	containsValue(Object key, Object value) Determines if value is mapped to key.
Enumeration	elements() Retrieves an enumeration of the values in this map.
Enumeration	elements(Object key) Retrieves an enumeration of values for a key.
boolean	isEmpty() Determines if this map is empty.
Enumeration	keys() Retrieves an enumeration of the keys in this map.
boolean	removeKey(Object key) Removes values by key.
boolean	removeValue(Object value) Removes value from map.
boolean	removeValue(Object key, Object value) Removes value by key from map.
int	size() Retrieves the number of values in this map.
int	size(Object key) Retrieves number of values associated with provided key.
String	toString() Retrieves string representation of this map.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MultiMap

public MultiMap(int initialHashtableCapacity,
                int initialVectorCapacity)

Constructs a new MultiMap instance with the provided capacity.

Parameters:

initialCapacity - Starting capacity for this map.

MultiMap

public MultiMap()

Constructs a new MultiMap instance.

This method creates a new multi map with a default capacity.

Method Detail

isEmpty

public boolean isEmpty()

Determines if this map is empty.

Returns:

True if this map has no entries.

clear

public void clear()

Removes all keys and values.

add

public boolean add(Object key,
                   Object value)

Maps value to key.

This method does not checking on the key or value parameters: for safety, you should neither seed this map with null keys, nor null values for keys.

Parameters:

key - Key to associate with value; if this key already exists in the map, the provided value is added to its association list. Must not be null.

value - Value to associate with key. Must not be null.

Returns:

True if the association succeeded; false, if the provided value already exists in the map.

removeKey

public boolean removeKey(Object key)

Removes values by key.

Parameters:

key - Key for value(s) to remove.

Returns:

True if key was removed; otherwise, false.

removeValue

public boolean removeValue(Object key,
                           Object value)

Removes value by key from map.

If the value to remove is the last one associated with the key, then this method removes the key as well. Otherwise, this method removes only the value from the map; the key and its associations with other values remains.

Parameters:

key - Key associated with value.

value - Value to remove.

Returns:

True if value was removed; otherwise, false.

removeValue

public boolean removeValue(Object value)

Removes value from map.

Invoke this method to remove a value from this map when you don't know its associated key. If you do know the key associated with this value, then you should invoke the more efficient MultiMap.removeValue(Object,Object).

If the value to remove is the last one associated with its key, then this method removes the key as well. Otherwise, this method removes only the value from the map; the key and its associations with other values remains.

containsKey

public boolean containsKey(Object key)

Determines if key is mapped.

Parameters:

key - Key to check.

Returns:

True if key has at least one associated value; otherwise, false.

containsValue

public boolean containsValue(Object key,
                             Object value)

Determines if value is mapped to key.

Parameters:

key - Key to check.

value - Value to check.

Returns:

True if value is mapped to key; otherwise, false.

keys

public Enumeration keys()

Retrieves an enumeration of the keys in this map.

Returns:

Enumeration of the keys in this map.

See Also:

Enumeration, MultiMap.elements()

elements

public Enumeration elements(Object key)

Retrieves an enumeration of values for a key.

Parameters:

key - Key associated with values.

Returns:

Enumeration of the values associated with provided key.

See Also:

Enumeration

elements

public Enumeration elements()

Retrieves an enumeration of the values in this map.

Returns:

Enumeration of the values in this map.

See Also:

Enumeration, MultiMap.keys()

size

public int size()

Retrieves the number of values in this map.

Note that this method provides the number of values associated with all keys in this map.

Returns:

Total number of values in this map.

size

public int size(Object key)

Retrieves number of values associated with provided key.

Parameters:

key - Key in question.

Returns:

Number of values associated with provided key.

toString

public String toString()

Retrieves string representation of this map.

Overrides:

toString in class Object

Returns:

String representation of this map.