The Jakarta Commons Collections Package

$Id: STATUS.html,v 1.29 2003/12/11 00:56:47 amamment Exp $
[Introduction] [Dependencies] [Release Info] [Committers] [Action Items]

1. INTRODUCTION

The Collections package contains a set of Java classes that extend or augment the Java Collections Framework. The following classes are included:

ArrayStack - An implementation of the java.util.Stack API that is based on an ArrayList instead of a Vector, so it is not synchronized to protect against multi-threaded access.
Bag - A Collection that keeps a count of its members of the same type, using hashCode to check for equality. Suppose you have a Bag that contains {a, a, b, c}. Calling getCount on a would return 2, while calling uniqueSet would return {a, b, c}. Note: this is an interface with several implementations.
BagUtils - Provides utility methods and decorators for Bag and SortedBag instances.
BeanMap - An implementation of the java.util.Map API that is based on a JavaBean using introspection. The property names are the keys of the map and the property values are the values of the map.
BinaryHeap - Binary heap implementation of PriorityQueue and Buffer.
BoundedCollection - an interface used by collections that can have a variable number of elements up to a fixed bound.
BoundedFifoBuffer - a very efficient implementation of Buffer that does not alter the size of the buffer at runtime.
Buffer - a collection that allows objects to be removed in some well-defined order.
BufferUtils - Contains static utility methods for buffers.
CircularFifoBuffer - a Buffer implementation that is fixed in size and overwrites its oldest entry when full.
CollectionUtils - a variety of helper methods for working with collections.
ComparatorUtils - Contains static utility methods for comparators.
CursorableLinkedList - an implementation of the java.util.List interface supporting a java.util.ListIterator that allows concurrent modifications to the underlying list.
DoubleOrderedMap - Red-Black tree-based implementation of Map. This class guarantees that the map will be in both ascending key order and ascending value order, sorted according to the natural order for the key's and value's classes.
ExtendedProperties - extends normal Java properties by adding the possibility to use the same key many times, concatenating the value strings instead of overwriting them.
FastArrayList - a custom implementation of java.util.ArrayList designed to operate in a multithreaded environment where the large majority of method calls are read-only, instead of structural changes.
FastHashMap - a custom implementation of java.util.HashMap designed to operate in a multithreaded environment where the large majority of method calls are read-only, instead of structural changes.
FastTreeMap - a custom implementation of java.util.TreeMap designed to operate in a multithreaded environment where the large majority of method calls are read-only, instead of structural changes.
HashBag - An implementation of Bag that is backed by a HashMap.
IteratorUtils - Contains static utility methods for iterators.
ListUtils - miscelaneous utilities to manipulate Lists.
LRUMap - a least recently used Map implementation.
MultiMap - This is simply a Map with slightly different semantics. Instead of returning an Object, it returns a Collection. So for example, you can put( key, new Integer(1) ); and then a Object get( key ); will return you a Collection instead of an Integer. This is an interface implemented by MultiHashMap.
NodeCachingLinkedList - a LinkedList implementation that has better performance.
PriorityQueue - a PriorityQueue interface, with BinaryHeap as an implementation.
PriorityQueueUtils - miscelaneous utilities to manipulate PriorityQueues.
ReferenceMap - Hashtable-based Map implementation that allows mappings to be removed by the garbage collector.
SequencedHashMap - A map of objects whose mapping entries are sequenced based on the order in which they were added.
SortedBag - A type of Bag that maintains order among its unique representative members
StaticBucketMap - An efficient, thread-safe implementation of java.util.Map that performs well in in a highly thread-contentious environment.
TreeBag - An implementation of Bag that is backed by a TreeMap. Order will be maintained among the unique representative members.
UnboundedFifoBuffer - Efficient implementation of Buffer that alters the size of the buffer at runtime.

comparators subpackage:

BooleanComparator - A Comparator that compares Boolean objects.
ComparableComparator - A Comparator that compares Comparable objects. This Comparator is useful, for example, for enforcing the natural order in custom implementations of SortedSet and SortedMap.
ComparatorChain - ComparatorChain is a Comparator that wraps one or more Comparators in sequence. The ComparatorChain calls each Comparator in sequence until either 1) any single Comparator returns a non-zero result (and that result is then returned), or 2) the ComparatorChain is exhausted (and zero is returned). This type of sorting is very similar to multi-column sorting in SQL, and this class allows Java classes to emulate that kind of behaviour when sorting a List.
FixedOrderComparator - A comparator that will compare in an order specified at construction time.
NullComparator - A comparator that will compare nulls to be either higher or lower than other objects.
ReverseComparator - Reverses the order of another comparator.
TransformingComparator - Decorates another comparator with transformation behavior.

iterators subpackage:

ArrayIterator - an Iterator wrapper for arrays, including primitive arrays.
ArrayListIterator - a ListIterator wrapper for arrays, including primitive arrays.
CollectinIterator - Provides an ordered iterator over the elements contained in a collection of ordered iterators.
EnumerationIterator - Adapter to make Enumeration instances appear to be Iterator instances.
FilterIterator - A Proxy Iterator which takes a Predicate instance to filter out objects from an underlying Iterator instance. Only objects for which the specified Predicate evaluates to true are returned.
FilterListIterator - A proxy ListIterator which takes a Predicate instance to filter out objects from an underlying ListIterator instance. Only objects for which the specified Predicate evaluates to true are returned by the iterator.
IteratorChain - An iterator that wraps one or more iterators.
IteratorEnumeration - Adapter to make Iterator instances appear to be Enumeration instances.
ListIteratorWrapper - As the wrapped Iterator is traversed, ListIteratorWrapper builds a LinkedList of its values, permitting all required operations of ListIterator.
LoopingIterator - Loops continuously around a collection.
ObjectArrayIterator - an Iterator wrapper for Object arrays.
ObjectArrayListIterator - a ListIterator wrapper for Object arrays.
ProxyIterator - Delegates its methods to a proxy instance.
ProxyListIterator - Delegates its methods to a proxy instance.
SingletonIterator - An Iterator over a single object instance.
SingletonListIterator - A ListIterator over a single object instance.
TransformIterator - Uses a Transformer instance to transform the contents of the Iterator into some other form.
UniqueFilterIterator - A FilterIterator which only returns "unique" Objects.

2. DEPENDENCIES

The Collections package is dependent upon the following external components for development and use:

Java Development Kit (Version 1.2 or later)
JUnit Testing Framework (Version 3.7 or later) - for unit tests only, not required for deployment

3. RELEASE INFO

Current Release: Version 2.1

Planned Next Release: ?

4. COMMITTERS

The following individuals are the primary developers and maintainers of this component. Developers who plan to use Collections in their own projects are encouraged to collaborate on the future development of this component to ensure that it continues to meet a variety of needs.

5. ACTION ITEMS

Want to help? Here's some "to do" items the team has identified.

Action Item	Volunteer
Additional Contributions. Other collection or collection-related classes or decorators.
Primitive subpackage. Complete implementations of a collections system based on primitives.
MultiMap ideas. Updates to MultiMap, maybe based on this library.
Additional Documentation. Create simple User's Guide, examples, or other documentation for this package.
Serializable Collections. All of the concrete Collection and Map implementations should be properly Serializable across all versions of the JDK. Also, decorators should be Serializable if the underlying instance is.
Fail-Fast Iterators. All concrete Collection and Map implementations that can have fail-fast iterators should have them. Some classes, like StaticBucketMap, cannot possibly have fail-fast iterators, but otherwise everything else should.
LoopingListIterator. A ListIterator similar to LoopingIterator
Standard Constructors. All concrete Collection and Map implementations should have the standard copy and no-argument constructors.
Additional Unit Tests. Create generic unit tests for SortedSet and SortedMap.