jdsl.simple.api
Interface SimpleDictionary

All Known Subinterfaces:
Dictionary

public abstract interface SimpleDictionary
extends Container

Interface for a dictionary in the "simple" package.

A dictionary is a container that stores a collection of items (each a key-element pair) that can be inserted, removed, and accessed (searched for) by specifying a key.

A dictionary may store multiple items with the same key.

A dictionary should store arbitrary objects by may restrict the type of keys that can be stored, and thus reject unacceptable keys throwing an InvalidKeyException. For example, an ordered dictionary accepts only keys from the set on which a given total order relation is defined.

Author:
Michael T. Goodrich, Mark Handy, Roberto Tamassia
See Also:
EmptyContainerException, InvalidKeyException, Comparator, Dictionary

Field Summary
static java.lang.Object NO_SUCH_KEY
          Special element returned by the search and removal methods when no item with the specified key is stored in the dictionary.
 
Method Summary
 java.util.Enumeration elements()
          Report the elements of all the items stored in the dictionary.
 java.util.Enumeration findAllElements(java.lang.Object key)
          Search for all the items with the specified key and return their elements.
 java.lang.Object findElement(java.lang.Object key)
          Search for an item with the specified key.
 void insertItem(java.lang.Object key, java.lang.Object element)
          Insert an item.
 java.util.Enumeration keys()
          Report the keys of all the items stored in the dictionary.
 java.lang.Object remove(java.lang.Object key)
          Remove an item with the specified key.
 java.util.Enumeration removeAll(java.lang.Object key)
          Remove all the items with the specified key.
 
Methods inherited from interface jdsl.simple.api.SimpleContainer
isEmpty, size
 

Field Detail

NO_SUCH_KEY

public static final java.lang.Object NO_SUCH_KEY
Special element returned by the search and removal methods when no item with the specified key is stored in the dictionary.
Method Detail

findElement

public java.lang.Object findElement(java.lang.Object key)
                             throws InvalidKeyException
Search for an item with the specified key. If such an item is found, return its element, else return the special element NO_SUCH_KEY.
Parameters:
key - search key.
Returns:
element of an item retrieved by the search, or NO_SUCH_KEY if no item with the specified key was found.
Throws:
InvalidKeyException - is thrown if the key is not acceptable to the dictionary.

findAllElements

public java.util.Enumeration findAllElements(java.lang.Object key)
                                      throws InvalidKeyException
Search for all the items with the specified key and return their elements.
Parameters:
key - An object comparable or indexable under whatever scheme the implementation uses for performing lookups
key - search key.
Returns:
Enumeration (possibly empty) of the elements of the items retrieved by the search.
Throws:
InvalidKeyException - is thrown if the key is not acceptable to the dictionary.

insertItem

public void insertItem(java.lang.Object key,
                       java.lang.Object element)
                throws InvalidKeyException
Insert an item.
Parameters:
key - object.
element - arbitrary object.
Throws:
InvalidKeyException - is thrown if the key is not acceptable to the dictionary.

remove

public java.lang.Object remove(java.lang.Object key)
                        throws InvalidKeyException
Remove an item with the specified key. If such an item is found, return its element, else return the special element NO_SUCH_KEY.
Parameters:
key - search key.
Returns:
element (not key) of the removed item, or NO_SUCH_KEY if no item with the specified key was found.
Throws:
InvalidKeyException - is thrown if the key is not acceptable to the dictionary.

removeAll

public java.util.Enumeration removeAll(java.lang.Object key)
                                throws InvalidKeyException
Remove all the items with the specified key.
Parameters:
key - search key.
Returns:
Enumeration (possibly empty) of all elements of the removed items
Throws:
InvalidKeyException - is thrown if the key is not acceptable to the dictionary.

keys

public java.util.Enumeration keys()
Report the keys of all the items stored in the dictionary. If the dictionary is ordered, the keys will come out of the Enumeration in order.
Returns:
Enumeration of the keys of all the items stored in the dictionary

elements

public java.util.Enumeration elements()
Report the elements of all the items stored in the dictionary. If the dictionary is ordered, the elements will come out of the Enumeration ordered by their keys.
Returns:
Enumeration of the elements of all the items stored in the dictionary