jdsl.core.api
Interface KeyBasedContainer

All Superinterfaces:

Container, InspectableContainer, InspectableKeyBasedContainer

All Known Subinterfaces:

Dictionary, OrderedDictionary, PriorityQueue

All Known Implementing Classes:

ArrayHeap, HashtableDictionary, RedBlackTree

public interface KeyBasedContainer

extends InspectableKeyBasedContainer, Container

Key-based containers are containers that store (key,element) pairs; each pair is represented by a Locator. The keys might or might not be ordered. The elements are entirely arbitrary, as far as the container is concerned. Attaching a key to every element allows the container to perform key-based retrievals of elements later.

Key-based containers allow duplicate keys, elements, or pairs, but there is a unique locator associated with each insertion of a pair. Users can implement no-duplicates semantics on top of key-based containers if required.

Version:

JDSL 2.1.1

Author:

Mark Handy, Andrew Schwerin, Luca Vismara

See Also:

InspectableKeyBasedContainer, Container, Locator

Method Summary

Locator	insert(Object key, Object element) Inserts a (key,element) pair into this container.
void	remove(Locator loc) Removes a (key,element) pair from the container.
Object	replaceKey(Locator loc, Object key) Replaces the key in the given (key,element) pair, adjusting the container as necessary.

Methods inherited from interface jdsl.core.api.InspectableKeyBasedContainer

keys, locators

Methods inherited from interface jdsl.core.api.InspectableContainer

contains, elements, isEmpty, size

Methods inherited from interface jdsl.core.api.Container

newContainer, replaceElement

Method Detail

insert

public Locator insert(Object key,
                      Object element)
               throws InvalidKeyException

Inserts a (key,element) pair into this container.

Parameters:

key - the key associated with the specified element.

element - the element to insert into the container.

Returns:

a locator associated with the inserted pair.

Throws:

InvalidKeyException - if key cannot be used by this container

remove

public void remove(Locator loc)
            throws InvalidAccessorException

Removes a (key,element) pair from the container.

Parameters:

loc - a locator in the container to remove

Throws:

InvalidAccessorException - if the locator is not valid or is not contained by this container

replaceKey

public Object replaceKey(Locator loc,
                         Object key)
                  throws InvalidAccessorException,
                         InvalidKeyException

Replaces the key in the given (key,element) pair, adjusting the container as necessary.

Parameters:

loc - the locator in the container whose key should be replaced

key - the new key to associate with loc.

Returns:

The old key

Throws:

InvalidAccessorException - If the locator is not valid or is not contained by this container

InvalidKeyException - If key cannot be used by this container