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:

• ArrayEnumeration - a java.util.Enumeration wrapper for arrays.
• ArrayIterator - a java.util.Iterator wrapper for arrays.
• 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.
• 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.
• CollectionUtils - a variety of helper methods for working with collections.
• 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.
• 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.
• 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.
• HashBag - An implementation of Bag that is backed by a HashMap.
• 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).
• ReverseComparator - Reverses the order of another comparator.
• SequencedHashMap - A map of objects whose mapping entries are sequenced based on the order in which they were added.
• SingletonIterator - An Iterator over a single object instance.
• SortedBag - A type of Bag that maintains order among its unique representative members
• TreeBag - An implementation of Bag that is backed by a TreeMap. Order will be maintained among the unique representative members.

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.