All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface jdsl.simple.api.SimpleDictionary

public 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.

Version:
$Revision: 1.2 $, $Date: 1998/07/02 21:24:47 $
Author:
Michael T. Goodrich, Mark Handy, Roberto Tamassia
See Also:
EmptyContainerException, InvalidKeyException, Comparator, Dictionary

Variable Index

o 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 Index

o elements()
Report the elements of all the items stored in the dictionary.
o findAllElements(Object)
Search for all the items with the specified key and return their elements.
o findElement(Object)
Search for an item with the specified key.
o insertItem(Object, Object)
Insert an item.
o keys()
Report the keys of all the items stored in the dictionary.
o remove(Object)
Remove an item with the specified key.
o removeAll(Object)
Remove all the items with the specified key.

Variables

o NO_SUCH_KEY 
 public static final 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.

Methods

o findElement 
 public abstract Object findElement(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.
o findAllElements 
 public abstract Enumeration findAllElements(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.
o insertItem 
 public abstract void insertItem(Object key,
                                 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.
o remove 
 public abstract Object remove(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.
o removeAll 
 public abstract Enumeration removeAll(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.
o keys 
 public abstract 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
o elements 
 public abstract 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 
All Packages  Class Hierarchy  This Package  Previous  Next  Index