Package jdsl.core.api

Package of interfaces and exceptions that compose the API for JDSL's core data structures: sequences, trees, priority queues, and dictionaries (a/k/a maps or associative arrays).

See:
Description

Interface Summary

Accessor	All JDSL core containers provide a way to access their internal structure; Accessor is the interface that embodies this concept.
BinaryTree	A modifiable tree in which each node has either zero or two children.
CircularSequence	A circular sequence stores elements in a ring, in other words it is a sequence without a head or a tail.
Comparator	Defines a total ordering for a set of objects.
Container	The common interface for all the mutable containers in JDSL.
Decorable	Decorability is the ability to attach extra pieces of information to an object.
Dictionary	A container that accepts (key,element) pairs and allows later lookup of the element associated with a particular key.
EqualityComparator	This interface defines an equality comparison on a set of objects.
HashComparator	This interface provides a way of mapping any object in a set to an integer, for purposes of implementing hash tables.
InspectableBinaryTree	Please refer to the documentation of the BinaryTree interface.
InspectableCircularSequence	Please refer to the documentation of CircularSequence.
InspectableContainer	A "read only" interface to a container; please see Container for more details.
InspectableDictionary	A read-only lookup structure; please refer to the documentation of Dictionary for more details.
InspectableKeyBasedContainer	Please refer to the documentation of KeyBasedContainer.
InspectableOrderedDictionary	A read-only lookup structure in which an ordering of the keys is maintained; please refer to the documentation of OrderedDictionary for more details.
InspectablePositionalContainer	Please refer to the documentation of PositionalContainer.
InspectableSequence	Please refer to the documentation of Sequence.
InspectableTree	Please refer to the documentation of Tree
KeyBasedContainer	Key-based containers are containers that store (key,element) pairs; each pair is represented by a Locator.
Locator	A locator is a coat-check, of sorts, for a (key,element) pair inside a KeyBasedContainer.
LocatorIterator	Iterator over a set of locators.
ObjectIterator	Iterator over a set of objects.
OrderedDictionary	A Dictionary in which the keys are totally ordered.
Position	An abstraction of the notion of a "place" in a container -- where an element is stored relative to other elements in the container.
PositionalContainer	Positional containers (for example, sequences, trees, and graphs) are containers in which elements are related to each other through adjacency information.
PositionIterator	Iterator over a set of positions.
PriorityQueue	A partially-ordered container that allows for removal of the element with highest priority.
Sequence	A positional container whose elements are linearly organized.
Tree	A positional container representing an ordered tree.

Class Summary

InspectableDictionary.InvalidLocator

A locator that is always invalid.

Exception Summary

BoundaryViolationException	Package jdsl.core.api class BoundaryViolationException
CoreException	This is the class from which all exceptions of the core package are descended.
EmptyContainerException	An EmptyContainerException indicates that the Container can't fulfill the requested operation because it is empty.
InvalidAccessorException	Used when an accessor (position or locator) is invalid, either internally invalid or invalid with respect to a particular container.
InvalidAttributeException	Used when the key for an attribute lookup is not supported by the implementation's lookup mechanism.
InvalidContainerException	Used to indicate that a container passed to a function is of the wrong type or otherwise invalid for that function call.
InvalidKeyException	Used when a key passed to a key-based container is not supported by the implementation's lookup mechanism.
InvalidMethodCallException	Package jdsl.core.api class InvalidMethodCallException
NonEmptyContainerException	A NonEmptyContainerException indicates that the Container can't fulfill the requested operation because it is not empty.

Package jdsl.core.api Description

Package of interfaces and exceptions that compose the API for JDSL's core data structures: sequences, trees, priority queues, and dictionaries (a/k/a maps or associative arrays).

Most of the interfaces in the package are for various kinds of containers, arranged in an inheritance hierarchy. A drawing of the hierarchy is available in the overview document included in the JDSL distribution. Two smaller hierarchies, for the accessors and iterators, are similar in structure to the container hierarchy.

Every JDSL container stores elements (Objects), and for each copy of an element stored in the container, there is one accessor. An accessor is an opaque reference to the internal structure of the container that is used to specify which copy of an element should be affected by an operation. It is sometimes useful to think of an accessor as a pointer to a node of the data structure.

The container interfaces can be classified by two independent criteria:

• Positional vs. Key-based Containers are classified by how the accessors are organized. In positional containers, the accessors have adjacency relationships: next and previous in a sequence, parent and children in a tree, or adjacent vertices in a graph. Typical operations add a new position in the container relative to existing positions, or iterate over adjacent positions of a given position.

  In key-based containers, each element is associated with a key, and the relationship among accessors is more abstract: in an ordered dictionary there is a total ordering among the accessors, but in a hash dictionary there is not. Typical operations look up an accessor that has a given key or the lowest key, or insert a new (key,element) pair into the container.

  In positional containers, the accessors are called positions, and in key-based containers, the accessors are called locators. Each position holds one element. Each locator holds one (key,element) pair. The accessor remains bound to its element or pair unless the user explicitly changes the binding. In addition to these accessors, JDSL provides a PositionIterator to process a set of positions, a LocatorIterator to process a set of locators, and various other iterators.

• Inspectable vs. Mutable An interface whose name begins with "Inspectable" has methods that do not change the state of the object (at least not in any way that the client can detect). For any interface InspectableXYZ there is another interface, XYZ, that extends the InspectableXYZ with methods that do change the state of the object -- i.e., XYZ is mutable. (Note: We typically do not document the Inspectable classes themselves. Please refer to the mutable version of the class for an overview. But we do document the individual methods of the Inspectable classes.)

This package also includes:

• decorations - for associating additional objects with accessors, for instance as labels.
• comparators - for defining an ordering on objects