The Jakarta Commons Collections Package

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.
• 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.
• 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.
• 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.
• PriorityQueue - a PriorityQueue interface, with BinaryHeap and SynchronizedPriorityQueue implementations.
• ProxyMap - This Map wraps another Map implementation, using the wrapped instance for its default implementation. This class is used as a framework on which to build to extensions for its wrapped Map object which would be unavailable or inconvenient via sub-classing (but usable via composition).
• 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.
• StringStack - A stack for string objects.
• SynchronizedPriorityQueue - A thread-safe version of the priority queue.
• 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:

• 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.
• 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 - a java.util.Iterator wrapper for 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.
• 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 1.0

Planned Next Release: TBD

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.

• Michael A. Smith
• Morgan Delagrange
• Peter Donald
• Geir Magnusson Jr.
• Craig McClanahan
• James Strachan
• Rodney Waldhoff
• Jason van Zyl
• Henri Yandell
• Paul Jack
• Stephen Colebourne

5. ACTION ITEMS

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