Update for version 3.0

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131481 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne 2003-12-29 18:04:36 +00:00
parent 5215e27ed6
commit b8fef8dfe7
2 changed files with 80 additions and 273 deletions

View File

@ -2,30 +2,33 @@
<center><h2>RELEASE NOTES: COLLECTIONS 3.0</h2></center>
<p><i>Collections 3.0</i> includes a lot of new functionality, including new interfaces
<p>
Originally, Collections was a general place for placing useful collection classes.
With version 3.0, this changes. Collections now has a design and package structure of its own.
As a result, several well-used classes have been deprecated and moved to new packages.
<p>
This release also includes a lot of new functionality, including new interfaces
and new implementations in addition to various bug fixes and refactoring changes.
The major additions are:
</p>
All previously deprecated classes have been removed.
<p>
The major changes are:
<ul>
<li><strong>New package structure</strong> -
One package now exists for each major interface</li>
<li><strong>Bidirectional maps</strong> -
New interface and implementations for maps that need bidirectional lookup.</li>
New interface and implementations for maps that need bidirectional lookup</li>
<li><strong>Map iterator</strong> -
New interface to enable iteration over map keys and values in one easy step.</li>
<li><strong>Observable collections</strong> -
New collection decorators that allow changes to collections to be observed via listeners.</li>
<li><strong>Decorators</strong> -
An entire package of classes that decorate existing collections/maps to add functionality.
This includes fixed size, lazy loading, validating, unmodifiable, synchronized, bounded,
transforming and ordered.</li>
New interface to enable iteration over map keys and values in one easy step</li>
<li><strong>Resettable iterator</strong> -
Interfaces that defines a reset() method to reset the iterator back to the start</li>
<li><strong>Functors</strong> -
A default set of functor implementations is now provided for Predicate, Transformer,
Closure and Factory.</li>
<li><strong>Pairs</strong> -
A new package full of key-value pairs and map entry implementations.</li>
Closure and Factory</li>
<li><strong>KeyValue</strong> -
A new package full of key-value pairs and map entry implementations</li>
<li><strong>Abstract Hash-based Map</strong> -
Highly extensible hash-based, and hash-link-based map abstract classes</li>
</ul>
<p>
All previously deprecated classes have been removed.
</p>
<hr />
@ -36,117 +39,83 @@ NEW PACKAGES
<p>These packages are new to <i>Collections 3.0</i>:</p>
<ul>
<li><strong>decorators</strong> -
Package of classes that decorate other collections/maps. Some of these classes
were previously inner classes, others are new.</li>
<li><strong>observed</strong> -
Package of classes that enable changes to collections/maps to be observed.</li>
<li><strong>pairs</strong> -
Package of key-value pairs and map entries.</li>
<li><strong>collection</strong> - Package of Collection implementations</li>
<li><strong>list</strong> - Package of List implementations</li>
<li><strong>set</strong> - Package of Set implementations</li>
<li><strong>bag</strong> - Package of Bag implementations</li>
<li><strong>buffer</strong> - Package of Buffer implementations</li>
<li><strong>map</strong> - Package of Map implementations</li>
<li><strong>bidimap</strong> - Package of BidiMap implementations</li>
<li><strong>keyvalue</strong> - Package of key-value pair implementations</li>
</ul>
<center><h3>
NEW CLASSES
</h3></center>
<p>These collections are new to <i>Collections 3.0</i>:</p>
<p>These implementations are new to <i>Collections 3.0</i>:</p>
<ul>
<li><strong>CompositeCollection/Set/Map</strong> - Merges multiple collections into a single view</li>
<li><strong>NodeCachingLinkedList</strong> - A list that caches nodes, performing well if long-lived</li>
<li><strong>HashedMap</strong> - An alternative to HashMap that supports a MapIterator</li>
<li><strong>LinkedMap</strong> - A map that retains the order of its entries</li>
<li><strong>Flat3Map</strong> - A map optimised for size 3 or less</li>
<li><strong>IdentityMap</strong> - A map that uses == not equals()</li>
<li><strong>ListOrderedSet/Map</strong> - A set/map that behaves like a List</li>
<li><strong>SetUniqueList</strong> - A list that behaves like a Set</li>
<li><strong>CircularFifoBuffer</strong> - A buffer that eliminates the oldest entry when full</li>
<li><strong>DualHashBidiMap</strong> - BidiMap implementation</li>
<li><strong>DualTreeBidiMap</strong> - SortedBidiMap implementation</li>
<li><strong>TreeBidiMap</strong> - OrderedBidiMap implementation</li>
<li><strong>FixedOrderComparator</strong> - A comparator in a fixed pre-determined order</li>
<li><strong>BooleanComparator</strong> - A comparator over Boolean instances</li>
<li><strong>ArrayListIterator</strong> - A ListIterator over an array of any type (including primitive arrays)</li>
<li><strong>LoopingIterator</strong> - An Iterator that loops repeatedly over the collection</li>
<li><strong>ObjectArray*Iterator</strong> - Iterators over an Object array</li>
<li><strong>EntrySetMapIterator</strong> - A MapIterator implemented using an entry set</li>
</ul>
<p>These comparators are new to <i>Collections 3.0</i>:</p>
<ul>
<li><strong>BooleanIterator</strong> -
Provides a comparator over Boolean instances.</li>
<li><strong>FixedOrderIterator</strong> -
Provides an iterator in a fixed pre-determined order.</li>
</ul>
<p>These iterators are new to <i>Collections 3.0</i>:</p>
<ul>
<li><strong>MapIterator</strong> -
Interface that defines a simple and powerful way to iterate over a Map.</li>
<li><strong>Resetable*Iterator</strong> -
Interfaces that defines a reset() method to reset the iterator back to the start.</li>
<li><strong>ArrayListIterator</strong> -
Provides a ListIterator over an array of any type (including primitive arrays).</li>
<li><strong>LoopingIterator</strong> -
Provides an Iterator that loops repeatedly over the collection.</li>
<li><strong>ObjectArray*Iterator</strong> -
Provides iterators over an Object array.</li>
<li><strong>Abstract*IteratorDecorator</strong> -
Provides abstract decorators that can be used to build extra functionality.</li>
<li><strong>Unmodifiable*Iterator</strong> -
Provides decorators for iterators that are unmodifiable.</li>
</ul>
<p>These are the new utility classes:</p>
<ul>
</ul>
<hr />
<center><h3>CHANGED CLASSES</h3></center>
<p>These collections have changed since <i>Collections 3.0</i>:</p>
<ul>
<li><strong>BinaryHeap</strong> - Deprecated, moved to buffer subpackage</li>
<li><strong>BoundedFifoBuffer</strong> - Deprecated, moved to buffer subpackage</li>
<li><strong>UnboundedFifoBuffer</strong> - Deprecated, moved to buffer subpackage</li>
<li><strong>SequencedHashMap</strong> - Deprecated, rewritten as LinkedMap in map subpackage</li>
<li><strong>DefaultMapBag</strong> - Deprecated, rewritten as AbstractMapBag in bag subpackage</li>
<li><strong>HashBag</strong> - Deprecated, moved and rewritten in bag subpackage</li>
<li><strong>TreeBag</strong> - Deprecated, moved and rewritten in bag subpackage</li>
<li><strong>DefaultMapEntry</strong> - Deprecated, moved to keyvalue subpackage</li>
<li><strong>DoubleOrderedMap</strong> - Deprecated, replaced by bidimap interface and implementations</li>
<li><strong>LRUMap</strong> - Deprecated, moved and rewritten in map subpackage</li>
<li><strong>ReferenceMap</strong> - Deprecated, moved to map subpackage</li>
<li><strong>StaticBucketMap</strong> - Deprecated, moved to map subpackage</li>
<li><strong>ProxyMap</strong> - Deprecated, moved as AbstractMapDecorator in map subpackage</li>
<li><strong>ExtendedProperties</strong> - Bug fixes. Please consider using Commons-Configuration <code>PropertiesConfiguration</code></li>
</ul>
<p>These comparators have changed since <i>Collections 3.0</i>:</p>
<ul>
<li><strong>ComparableComparator</strong> -
Simpler implementation that respects interface better.</li>
<li><strong>ComparatorChain</strong> -
Equals and HashCode added.</li>
<li><strong>ReverseComparator</strong> -
Equals and HashCode added.</li>
<li><strong>ComparableComparator</strong> - Simpler implementation that respects interface better.</li>
<li><strong>ComparatorChain</strong> - Equals and HashCode added.</li>
<li><strong>ReverseComparator</strong> - Equals and HashCode added.</li>
</ul>
<p>These iterators have changed since <i>Collections 3.0</i>:</p>
<ul>
<li><strong>ArrayIterator</strong> -
This now implements the ResetableIterator interface. It also supports a start index to iterate from.</li>
<li><strong>CollatingIterator</strong> -
The remove() method now throws IllegalStateException not NoSuchElementException.</li>
<li><strong>FilterIterator</strong> -
The remove() method is now supported, with some limitations.</li>
<li><strong>IteratorChain</strong> -
Bug fix for when remove() called before hasNext()/next().</li>
<li><strong>Singleton*Iterator</strong> -
These now implement the ResetableIterator interface.</li>
<li><strong>Proxy*Iterator</strong> -
Now deprecated in favour of AbstractIteratorDecorator/AbstractListIteratorDecorator.</li>
<li><strong>Filter*Iterator/TransformIterator</strong> -
No longer extend ProxyIterator.</li>
<li><strong>ArrayIterator</strong> - This now implements the ResetableIterator interface. It also supports a start index to iterate from.</li>
<li><strong>CollatingIterator</strong> - The remove() method now throws IllegalStateException not NoSuchElementException.</li>
<li><strong>FilterIterator</strong> - The remove() method is now supported, with some limitations.</li>
<li><strong>IteratorChain</strong> - Now supports a chain of zero iterators. Bug fix for when remove() called before hasNext()/next().</li>
<li><strong>Singleton*Iterator</strong> - These now implement the ResetableIterator interface.</li>
<li><strong>Proxy*Iterator</strong> - Now deprecated in favour of AbstractIteratorDecorator/AbstractListIteratorDecorator.</li>
<li><strong>Filter*Iterator/TransformIterator</strong> - No longer extend ProxyIterator.</li>
</ul>
<hr />
<center><h3>REFACTORING</h3></center>
<p><u>Documentation</u></p>
<p>Every class released in 3.0 has been changed in some way.
This might be simply the update to the Apache license, or it could be improved Javadoc.</p>

View File

@ -7,7 +7,7 @@
<div align="center">
<h1>The Jakarta Commons <em>Collections</em> Package</h1>
$Id: STATUS.html,v 1.29 2003/12/11 00:56:47 amamment Exp $<br>
$Id: STATUS.html,v 1.30 2003/12/29 18:04:36 scolebourne Exp $<br>
<a href="#Introduction">[Introduction]</a>
<a href="#Dependencies">[Dependencies]</a>
<a href="#Release Info">[Release Info]</a>
@ -21,166 +21,10 @@ $Id: STATUS.html,v 1.29 2003/12/11 00:56:47 amamment Exp $<br>
<h3>1. INTRODUCTION</h3>
<p>The <em>Collections</em> package contains a set of Java classes that
extend or augment the Java Collections Framework.
The following classes are included:</p>
<ul>
<li><strong>ArrayStack</strong> - 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.</li>
<li><strong>Bag</strong> - A Collection that keeps a count of its members of the same
type, using <code>hashCode</code> to check for equality. Suppose
you have a Bag that contains <code>{a, a, b, c}</code>. Calling
getCount on <code>a</code> would return 2, while calling
uniqueSet would return <code>{a, b, c}</code>. <i>Note: this is an
interface with several implementations.</i></li>
<li><strong>BagUtils</strong> - Provides utility methods and decorators
for Bag and SortedBag instances.</li>
<li><strong>BeanMap</strong> - 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.</li>
<li><strong>BinaryHeap</strong> - Binary heap implementation
of PriorityQueue and Buffer.</li>
<li><strong>BoundedCollection</strong> - an interface used by collections that can
have a variable number of elements up to a fixed bound.</li>
<li><strong>BoundedFifoBuffer</strong> - a very efficient implementation of
Buffer that does not alter the size of the buffer at runtime.</li>
<li><strong>Buffer</strong> - a collection that allows objects to be removed
in some well-defined order.</li>
<li><strong>BufferUtils</strong> - Contains static utility methods for
buffers.</li>
<li><strong>CircularFifoBuffer</strong> - a Buffer implementation that is fixed in
size and overwrites its oldest entry when full.</li>
<li><strong>CollectionUtils</strong> - a variety of helper methods
for working with collections.</li>
<li><strong>ComparatorUtils</strong> - Contains static utility methods for
comparators.</li>
<li><strong>CursorableLinkedList</strong> - an implementation of the java.util.List
interface supporting a java.util.ListIterator that allows concurrent
modifications to the underlying list.</li>
<li><strong>DoubleOrderedMap</strong> - 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.</li>
<li><strong>ExtendedProperties</strong> - extends normal Java properties by adding
the possibility to use the same key many times, concatenating the value strings
instead of overwriting them.</li>
<li><strong>FastArrayList</strong> - 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.</li>
<li><strong>FastHashMap</strong> - 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.</li>
<li><strong>FastTreeMap</strong> - 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.</li>
<li><strong>HashBag</strong> - An implementation of <strong>Bag</strong> that is backed by a
HashMap.</li>
<li><strong>IteratorUtils</strong> - Contains static utility methods for
iterators.</li>
<li><strong>ListUtils</strong> - miscelaneous utilities to manipulate Lists.</li>
<li><strong>LRUMap</strong> - a least recently used Map implementation.</li>
<li><strong>MultiMap</strong> - 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 <strong>MultiHashMap</strong>.</li>
<li><strong>NodeCachingLinkedList</strong> - a LinkedList implementation that has better
performance.</li>
<li><strong>PriorityQueue</strong> - a PriorityQueue interface, with
<strong>BinaryHeap</strong> as an implementation.</li>
<li><strong>PriorityQueueUtils</strong> - miscelaneous utilities to manipulate PriorityQueues.</li>
<li><strong>ReferenceMap</strong> - Hashtable-based Map implementation that
allows mappings to be removed by the garbage collector.</li>
<li><strong>SequencedHashMap</strong> - A map of objects whose mapping entries are
sequenced based on the order in
which they were added.</li>
<li><strong>SortedBag</strong> - A type of <strong>Bag</strong> that maintains order among its unique
representative members</li>
<li><strong>StaticBucketMap</strong> - An efficient, thread-safe
implementation of java.util.Map that performs well in in a highly
thread-contentious environment.</li>
<li><strong>TreeBag</strong> - An implementation of <strong>Bag</strong> that is backed by a
TreeMap. Order will be maintained among the unique representative
members.</li>
<li><strong>UnboundedFifoBuffer</strong> - Efficient implementation of Buffer
that alters the size of the buffer at runtime.</li>
</ul>
extend or augment the Java Collections Framework. This includes new interfaces
and new implementations together with supporting utility classes.
<p><b>comparators subpackage:</b></p>
<ul>
<li><strong>BooleanComparator</strong> - A Comparator that compares Boolean objects.</li>
<li><strong>ComparableComparator</strong> - A Comparator that compares Comparable objects.
This Comparator is useful, for example,
for enforcing the natural order in custom implementations
of SortedSet and SortedMap.</li>
<li><strong>ComparatorChain</strong> - 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.</li>
<li><strong>FixedOrderComparator</strong> - A comparator that will compare in an order
specified at construction time.</li>
<li><strong>NullComparator</strong> - A comparator that will compare nulls
to be either higher or lower than other objects.</li>
<li><strong>ReverseComparator</strong> - Reverses the order of another
comparator.</li>
<li><strong>TransformingComparator</strong> - Decorates another comparator
with transformation behavior.</li>
</ul>
<p><b>iterators subpackage:</b></p>
<ul>
<li><strong>ArrayIterator</strong> - an Iterator wrapper for arrays, including primitive arrays.</li>
<li><strong>ArrayListIterator</strong> - a ListIterator wrapper for arrays, including primitive arrays.</li>
<li><strong>CollectinIterator</strong> - Provides an ordered iterator over
the elements contained in a collection of ordered iterators.</li>
<li><strong>EnumerationIterator</strong> - Adapter to make Enumeration
instances appear to be Iterator instances.</li>
<li><strong>FilterIterator</strong> - A Proxy <code>Iterator</code> which takes a
<code>Predicate</code>
instance to filter out objects from an underlying <code>Iterator</code> instance.
Only objects for which the
specified <code>Predicate</code> evaluates to <code>true</code> are
returned.</li>
<li><strong>FilterListIterator</strong> - A proxy <code>ListIterator</code> which
takes a <code>Predicate</code> instance to filter
out objects from an underlying <code>ListIterator</code>
instance. Only objects for which the specified
<code>Predicate</code> evaluates to <code>true</code> are
returned by the iterator.</li>
<li><strong>IteratorChain</strong> - An iterator that wraps one or more
iterators.</li>
<li><strong>IteratorEnumeration</strong> - Adapter to make Iterator instances
appear to be Enumeration instances.</li>
<li><strong>ListIteratorWrapper</strong> - As the wrapped Iterator is
traversed, ListIteratorWrapper builds a LinkedList of its values,
permitting all required operations of ListIterator.</li>
<li><strong>LoopingIterator</strong> - Loops continuously around a collection.</li>
<li><strong>ObjectArrayIterator</strong> - an Iterator wrapper for Object arrays.</li>
<li><strong>ObjectArrayListIterator</strong> - a ListIterator wrapper for Object arrays.</li>
<li><strong>ProxyIterator</strong> - Delegates its methods to a proxy
instance.</li>
<li><strong>ProxyListIterator</strong> - Delegates its methods to a proxy
instance.</li>
<li><strong>SingletonIterator</strong> - An Iterator over a single
object instance.</li>
<li><strong>SingletonListIterator</strong> - A ListIterator over a single
object instance.</li>
<li><strong>TransformIterator</strong> - Uses a Transformer instance to
transform the contents of the Iterator into some other form.</li>
<li><strong>UniqueFilterIterator</strong> - A FilterIterator which only
returns "unique" Objects.</li>
</ul>
<p>In addition to the main commons-collections jar, a testframework jar file is also produced.
<a name="Dependencies"></a>
<h3>2. DEPENDENCIES</h3>
@ -246,12 +90,6 @@ component to ensure that it continues to meet a variety of needs.</p>
<td align="center">&nbsp;</td>
</tr>
<tr>
<td><strong>Primitive subpackage</strong>. Complete implementations of
a collections system based on primitives.</td>
<td align="center">&nbsp;</td>
</tr>
<tr>
<td><strong>MultiMap ideas</strong>. Updates to MultiMap, maybe based on
<a href="http://www.innig.org/util/innig-util/build/javadoc">this library</a>.</td>