jdsl.core.api
Interface InspectableDictionary

All Superinterfaces:
InspectableContainer, InspectableKeyBasedContainer
All Known Subinterfaces:
Dictionary, InspectableOrderedDictionary, OrderedDictionary

public interface InspectableDictionary
extends InspectableKeyBasedContainer

A read-only lookup structure; please refer to the documentation of Dictionary for more details.

Version:
$Id: InspectableDictionary.java,v 1.6 2000/02/14 11:10:30 lv Exp $
Author:
Mark Handy, Andrew Schwerin, Luca Vismara
See Also:
Dictionary, InspectableKeyBasedContainer

Inner Class Summary
static class InspectableDictionary.InvalidLocator
          A locator that is always invalid.
 
Field Summary
static Locator NO_SUCH_KEY
          This Locator is returned when a method that should return a locator with a given key can find no such key within the data structure
 
Method Summary
 Locator find(java.lang.Object key)
          Finds an object that is mapped to a particular key.
 LocatorIterator findAll(java.lang.Object key)
          Finds all elements mapped to a particular key.
 
Methods inherited from interface jdsl.core.api.InspectableKeyBasedContainer
keys, locators
 
Methods inherited from interface jdsl.core.api.InspectableContainer
contains, elements, isEmpty, size
 

Field Detail

NO_SUCH_KEY

public static final Locator NO_SUCH_KEY
This Locator is returned when a method that should return a locator with a given key can find no such key within the data structure
Method Detail

find

public Locator find(java.lang.Object key)
             throws InvalidKeyException
Finds an object that is mapped to a particular key.
Parameters:
key - The key mapped to search for.
Returns:
The Locator referring to the key-element pair that was found, or NO_SUCH_KEY if it could not be found.
Throws:
InvalidKeyException - if the specified key is not a valid key in this container.
See Also:
NO_SUCH_KEY

findAll

public LocatorIterator findAll(java.lang.Object key)
                        throws InvalidKeyException
Finds all elements mapped to a particular key. The iterator returned is a snapshot -- that is, it holds all locators with the specified key at the moment findAll(.) is called, regardless of any modifications to the container that might occur after the call to findAll(.) and before the iterator is discarded.
Parameters:
key - The key to search for.
Returns:
A LocatorIterator over the set of (key, element) pairs whose keys match the parameter key
Throws:
InvalidKeyException - if the specified key is not valid in this container