All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface jdsl.core.api.KeyBasedContainer

public interface KeyBasedContainer
extends Container
A Container in which each element in its structure is associated with a key. This association is known as a mapping. A KeyBasedContainer does not explicitly use an element to determine its internal position. Instead the key to which the element is mapped determines this position (this key may be the element itself, however).

KeyBasedContainers may be viewed abstractly as storing pairs of the type, p(k,e) where

In the above example, k is known as an explicit key. That is k is some object other than e. In this case k is used to determine e's position in the container. KeyBasedContainers also allow the use of an implicit key ­ where the element itself is used as a key. The difference between the two forms is seen in the methods which use them. For example 
     Locator insert(Object key, Object element);
is an explicit key method call, whereas 
     Locator insert(Object element);
is an implicit key call.

Version:
1.0 Tue Aug 12 12:28:15 EDT 1997
Author:
John Kloss

Method Index

o insert(Locator)
Inserts a Locator into this Container.
o insert(Object, Object)
Inserts a <key, element> pair into this Container.
o keys()
Returns an enumeration of all of the keys of all the locators in the Container.
o locators()
Returns an Enumeration of all the Locators within this Container.
o makeLocator(Object, Object)
For when you need a locator that can be inserted into this KeyBasedContainer but don't want to insert it quite yet.
o remove(Locator)
Removes an element from this Container.
o replaceElement(Locator, Object)
Takes constant time -- even in key-based containers, since the element can be changed independently of the key.
o replaceKey(Locator, Object)
Changes the mapping of a Locator's element to a new key.

Methods

o insert 
 public abstract void insert(Locator locator) throws InvalidKeyException, InvalidLocatorException, ContainedLocatorException
Inserts a Locator into this Container.

Parameters:
locator - The Locator whose key and element are inserted into this Container.
Throws: InvalidKeyException
If the key referenced by locator is not a type accepted by this Container. (For instance, if the container's Comparator can't compare the element, or if the container should have a comparator but doesn't.)
Throws: InvalidLocatorException
If locator cannot be inserted into this container.
o insert 
 public abstract Locator insert(Object key,
                                Object element) throws InvalidKeyException
Inserts a <key, element> pair into this Container. Here, key is an explicit key. That is, it is mapped to element and used to position element within this Container.

Parameters:
key - The key used to position the element within this Container.
element - The element to be inserted into this Container.
Returns:
A Locator which points to element within this Container.
Throws: InvalidKeyException
If key is not a type accepted by this Container. (For instance, if the container's Comparator can't compare the element, or if the container should have a comparator but doesn't.)
o remove 
 public abstract void remove(Locator locator) throws InvalidLocatorException, UncontainedLocatorException
Removes an element from this Container. This method provides the only guaranteed way of removing a particular element from a KeyBasedContainer. The Container may make no guarantee about the uniqueness of its keys or stored elements. Many elements may be mapped to the same key and vice versa depending upon the particular implementaion.

Parameters:
locator - The Locator which points to a particular element within this Container.
Throws: InvalidLocatorException
If locator is invalid.
Throws: UncontainedLocatorException
If locator is not in a container.
o replaceKey 
 public abstract Object replaceKey(Locator locator,
                                   Object key) throws InvalidLocatorException, InvalidKeyException
Changes the mapping of a Locator's element to a new key. That is, within this Container locator's element will now be mapped to key. The original key this element was mapped to is returned Note: this method does not necessarily remove the old key (other elements within this Container may be mapped to it).

Parameters:
locator - The Locator which points to a particular element within this Container.
key - The new key to which locator's element should be mapped.
Returns:
The old key to which locator's element was mapped.
Throws: InvalidLocatorException
If locator is invalid (For example: It does not actually reference an element in this Container).
Throws: InvalidKeyException
If key is not a type accepted by this Container (e.g. If this Container is unable to use key as a key).
o replaceElement 
 public abstract Object replaceElement(Locator loc,
                                       Object newElement) throws InvalidLocatorException
Takes constant time -- even in key-based containers, since the element can be changed independently of the key.

Parameters:
loc - Locator at which replacement should occur
newElement - Element now to be stored at Locator loc
Returns:
Old element, previously stored at Locator loc
o locators 
 public abstract Enumeration locators()
Returns an Enumeration of all the Locators within this Container. If this Container is empty then an empty Enumeration is returned.

Returns:
An Enumeration of all the Locators stored in the container. Note: this Enumeration may be empty.
o keys 
 public abstract Enumeration keys()
Returns an enumeration of all of the keys of all the locators in the Container.

Returns:
An Enumeration of all the keys in this container. Note: this Enumeration may be empty.
o makeLocator 
 public abstract Locator makeLocator(Object key,
                                     Object element) throws InvalidKeyException
For when you need a locator that can be inserted into this KeyBasedContainer but don't want to insert it quite yet. 

All Packages  Class Hierarchy  This Package  Previous  Next  Index