: Interface Dictionary

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

jdsl
Interface Dictionary

All Known Subinterfaces:: OrderedDictionary

public abstract interface Dictionary
extends KeyBasedContainer

A KeyBasedContainer which provides element lookup based upon search keys.

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.Iterator`	`findAll(java.lang.Object key)` Returns an Iterator of Locators mapped to the search key.

Methods inherited from interface jdsl.KeyBasedContainer

insert, 
insert, 
keys, 
locators, 
makeLocator, 
remove, 
replaceElement, 
replaceKey

Methods inherited from interface jdsl.Container

elements, 
isEmpty, 
newContainer, 
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.Iterator findAll(java.lang.Object key)
                           throws InvalidKeyException

Returns an Iterator 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 Iterator 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 Iterator of Locators mapped to key. Note: the Iterator 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).