jdsl.core.api
Interface Dictionary

All Known Subinterfaces:
OrderedDictionary

public abstract interface Dictionary
extends KeyBasedContainer

A KeyBasedContainer which provides element lookup based upon search keys.

Author:
John Kloss, Mark Handy

Field Summary
static Locator NO_SUCH_KEY
          Locator returned by find(.) when the key requested is not present in the Dictionary.
 
Method Summary
 Locator find(java.lang.Object key)
          Returns a Locator mapped to the search key.
 java.util.Enumeration findAll(java.lang.Object key)
          Returns an Enumeration of Locators mapped to the search key.
 
Methods inherited from interface jdsl.core.api.KeyBasedContainer
insert, insert, keys, locators, makeLocator, remove, replaceElement, replaceKey
 
Methods inherited from interface jdsl.core.api.Container
elements, newContainer
 
Methods inherited from interface jdsl.simple.api.SimpleContainer
isEmpty, size
 

Field Detail

NO_SUCH_KEY

public static final Locator NO_SUCH_KEY
Locator returned by find(.) when the key requested is not present in the Dictionary. Note that dictionaries have special values returned from lookup methods, rather than exceptions, when the lookup fails.
Method Detail

find

public Locator find(java.lang.Object key)
             throws InvalidKeyException
Returns a Locator mapped to the search key. There is no guarantee that the mapping of this Locator to key is unique-- there may be many Locators mapped to the same key depending on the particular implementation of this Dictionary. Furthermore, there may be no such element mapped to key in which case the Locator returned will be NO_SUCH_KEY, which is invalid. That is, it does not reference an element in any Container and cannot be used.
Parameters:
key - The key used to search for an element in this Container.
Returns:
A Locator mapped to key. Note: this Locator will be NO_SUCH_KEY, an invalid locator, if the key is not found.
Throws:
InvalidKeyException - If key is not of a type accepted by this Container (For example: The key is not comparable by this Container).

findAll

public java.util.Enumeration findAll(java.lang.Object key)
                              throws InvalidKeyException
Returns an Enumeration of Locators mapped to the search key. This method is guaranteed to return all elements associated with key. If there are no such elements then the Enumeration is empty. There is no guaranteed of order of these Locators.
Parameters:
key - The key used to search for an element within this Container.
Returns:
An Enumeration of Locators mapped to key . Note: the Enumeration will be empty if no such elements exist in the container.
Throws:
InvalidKeyException - If key is not of a type accepted by this Container (For example: The key is not comparable by this Container).