nz.ac.waikato.jdsl.core.api
Interface InspectableDictionary

All Superinterfaces:

InspectableContainer, InspectableKeyBasedContainer

All Known Subinterfaces:

Dictionary, InspectableOrderedDictionary, OrderedDictionary

All Known Implementing Classes:

HashtableDictionary, RedBlackTree

public interface InspectableDictionary
extends InspectableKeyBasedContainer

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

Version:

JDSL 2.1.1

Author:

Mark Handy, Andrew Schwerin, Luca Vismara

See Also:

Dictionary, InspectableKeyBasedContainer

Nested 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 nz.ac.waikato.jdsl.core.api.InspectableKeyBasedContainer

keys, locators

Methods inherited from interface nz.ac.waikato.jdsl.core.api.InspectableContainer

contains, elements, isEmpty, size

Field Detail

NO_SUCH_KEY

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

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

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