All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface jdsl.simple.api.SimpleDictionary

public interface SimpleDictionary

extends Container

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.

See Also:

EmptyContainerException, InvalidKeyException, Comparator, Dictionary

NO_SUCH_KEY

Special element returned by the search and removal methods when no item with the specified key is stored in the dictionary.

elements()

Report the elements of all the items stored in the dictionary.

findAllElements(Object)

Search for all the items with the specified key and return their elements.

findElement(Object)

Search for an item with the specified key.

insertItem(Object, Object)

Insert an item.

keys()

Report the keys of all the items stored in the dictionary.

remove(Object)

Remove an item with the specified key.

removeAll(Object)

Remove all the items with the specified 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.

 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.

 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.

 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.

 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.

 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.

 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

 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