Package org.jutil.java.collections

Provides for operations on collections.

See:
Description

Interface Summary

CollectionOperator	CollectionOperator is the toplevel interface for collection operators.
Fifo	Interface for first-in first-out like datastructures.
MapOperator	MapOperator is the toplevel interface for map operators.
PriorityQueue	A PriorityQueue is a container of objects with an associated priority/ordering, that allows the retrieval of the element with the smallest value.

Class Summary

Accumulator	A class of objects that accumulate over a collection.
AndFilter	The effect of this filter is the same as of a filter with the conjunction of the criteria of the filters it was build with.
ArrayCursor	A class of objects that point to a certain index in a multi-dimensional array.
Arrays	A class with static methods for arrays
BinomialHeap	A BinomialHeap is a Heap that consists of a forest of Binomial Trees.
BlockingFifoList	Synchronized fifo list that will block the request to pop the first object until a first object is present.
BooleanAccumulator	A boolean accumulator for collections.
Collections	A utility class for perform operations on collections similar to java.util.Collections.
ComparableComparator	Trivial Comparator that uses the Comparable interface of objects to compare.
Counter	An IntegerAccumulator that counts the number of items in a collection that satisfies some criterion.
Exists	A boolean exists operator.
ExtendedComparator	A Comparator with more convenient methods than java.util.Comparator.
FifoList	FifoList is a class of objects that represent simple first-in first-out lists .
Filter	A filter for collections.
ForAll	A boolean for-all operator.
IntegerAccumulator	An integer accumulator for collections.
InverseComparator	An ExtendedComparator that inverts another Comparator.
Mapping	A mapping of collections.
MapVisitor	A visitor of maps.
ObjectArrayIterator	A class of iterators for multi-dimensional arrays of objects.
RobustMapVisitor	A robust visitor of maps.
RobustVisitor	A robust visitor of collections.
Singleton
SkipList	A collections which is actually a sorted list.
SkipListPQ	A SkipList based priority queue
SynchronizedFifoList	Synchronized version of a FifoList.
TransitiveClosure	An operator that calculates the transitive closure of a graph of objects.
TypeFilter	A class of filters that use the type of an object as criterion.
Visitor	A class of collection operators that can perform a certain action on all element of a collection.

Exception Summary

ZeroDimensionException

A class of exceptions indicating the attempt to use a class in this package with an object array that has at least one dimension equal to zero.

Package org.jutil.java.collections Description

Provides for operations on collections. These operations can be seen as software theorems. Instead of writing the same error-prone iterations over and over again, the classes of this package can be used. Using these classes will make iterations much easier to read and a lot easier to prove.

A manual for each of the classes follows below.

CollectionOperator

CollectionOperator is the toplevel interface for operations on collections. It only contains a model method (a specification-only method) isValidElement(Object element). This method is needed in order to prove the correctness of subclasses.

Set operations are the one and only reason for the creation an the success of for example SQL. You can perform very complex operations with a very easy syntax. In traditional object-oriented programs, they are still the most complex constructions because they require loops to be written, which are difficult to write (how many times did you write a loop correct from the first time ?). Another drawback is that these loops, for example to check whether all elements of a collection satisfy some criterion, have to be written over and over again because they are always implemented with low-level constructions (for, while) which are not reusable.

With the classes in this package, the same functionality can be added to object-oriented programs. Using internal iterators, they provide set operations which can easily be adapted to perform specific things by subclassing them. The documentation of the classes explains how to do that.

As a result of the use of internal iterators, complex nested iterations can be replaced by a declarative implementation that is both very easy to read and write.

Visitors

Visitors are object that can perform a certain action on all element of an object structure.

Class Diagram

Visitor

The Visitor class is a replacement for the java.util.Iterator class that allows a programmer to perform a certain action on all elements of a collection.

MapVisitor

The MapVisitor class is similar to the Visitor class, but it operates on maps instead of collections. The only difference between the two classes is an additional argument in the visit method.

RobustVisitor

Of course, sometimes exceptions can be thrown during a visit. The default behaviour when an exception occurs, is to undo all changes that were made and throw an exception to the caller of the method. This means that the actions that were performed on elements visited before the element that caused the exception, have to be undone. The RobustVisitor class adds support for handling exceptions to the Visitor class.

RobustMapVisitor

As with the normal visitor, an additional class RobustMapVisitor is made for visiting maps when exceptions can occur.

Accumulators

An accumulator acts like a visitor, but passes an argument from each visit to the next. Because we cannot write code that works for both Object types and primitive types, we have separate accumulators for Object, and each primitive type (currently only int and boolean). Wrapping primitive values in their wrapper class is annoying to work with, and causes an unnecessary performance penalty.

Class Diagram

Accumulator

The base class of objects that use an Object as accumulator.

Boolean Accumulators

Class Diagram

BooleanAccumulator

The BooleanAccumulator class is almost identical to Accumulator. The return types have been changed to boolean, and the accumulate has been renamed to in.

ForAll

The boolean accumulator ForAll checks whether some boolean criterion is satisfied by all elements in a collection.

Exists

The boolean accumulator Exists checks whether some boolean criterion is satisfied by at least one element in a collection.

Integer Accumulators

Class Diagram

Counter

A Counter is an integer accumulator that counts how many object in a given collection satisfy some criterion.

Filters

Filters are collection operators that filter certain objects out of a collection. Given a criterion, a filter can discard or retain the objects satisfying that criterion.

Class Diagram

Filter

Filter is the top class of the filters that operate on collections. It implements the retain and discard methods. The criterion must be defined by subclasses.

TypeFilter

TypeFilter is a special filter that uses the type of the object in the collection as criterion.

AndFilter

AndFilter is a special filter that acts like a filter with a criterion that is the "and" of the criteria of the filters it is composed of.

Fifo queues

Fifo queues are first-in-first-out queues.

Class Diagram

Fifo

Fifo is the top interface of all Fifo queues.

FifoList

FifoList is an implementation of the Fifo interface.

SynchronizedFifoList

FifoList is a synchronized subclass of FifoList.

BlockingFifoList

FifoList is a subclass of FifoList that is synchronized, and blocks pop() requests when it is empty until an item is available.