net.rim.device.api.util
Class MultiMap

java.lang.Object
  extended by net.rim.device.api.util.MultiMap
All Implemented Interfaces:
Persistable, 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.





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.