Start the process of writing 3.0 release notes - iterator package
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131207 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne
parent
28f121b39b
commit
36e0dc40a1
|
|
@ -1,219 +0,0 @@
|
||||||
<title>RELEASE NOTES: COLLECTIONS 2.0</title>
|
|
||||||
|
|
||||||
<center><h2>RELEASE NOTES: COLLECTIONS 2.0</h2></center>
|
|
||||||
|
|
||||||
|
|
||||||
<center><h3>NEW COLLECTIONS AND COMPARATORS</h3></center>
|
|
||||||
|
|
||||||
<p><i>Collections 2.0</i> includes a significant number of new collections, in addition to several
|
|
||||||
useful Comparator classes. Descriptions of the new collections and comparators follow.
|
|
||||||
(For descriptions of all classes in <i>Collections</i>, see the <i>STATUS.html</i> file.)</p>
|
|
||||||
|
|
||||||
<p>These collections are new to <i>Collections 2.0</i>:</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
|
|
||||||
<li><strong>Bag</strong> - A Collection that counts the number of times an
|
|
||||||
object appears in the collection. 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>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>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>HashBag</strong> - An implementation of <strong>Bag</strong> that is backed by a
|
|
||||||
HashMap.</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>ProxyMap</strong> - This <code>Map</code> wraps another <code>Map</code>
|
|
||||||
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 <code>Map</code> object which
|
|
||||||
would be unavailable or inconvenient via sub-classing (but usable
|
|
||||||
via composition).</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>TreeBag</strong> - An implementation of <strong>Bag</strong> that is backed by a
|
|
||||||
TreeMap. Order will be maintained among the unique representative
|
|
||||||
members.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p>These are the new Comparator classes:</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<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>ReverseComparator</strong> - Reverses the order of another comparator.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<center><h3>CHANGED COLLECTIONS</h3></center>
|
|
||||||
|
|
||||||
These classes have changed since <i>Collections 1.0</i>:
|
|
||||||
|
|
||||||
<p><u>ArrayEnumeration</u></p>
|
|
||||||
|
|
||||||
<p>ArrayEnumeration has been <b>deprecated</b>. This class has significant overlap with
|
|
||||||
ArrayIterator, and Collections focuses mainly on Java2-style
|
|
||||||
collections. If you need to enumerate an array,
|
|
||||||
create an ArrayIterator and wrap it with an
|
|
||||||
IteratorEnumeration instead.</p>
|
|
||||||
|
|
||||||
<p><u>ArrayIterator</u></p>
|
|
||||||
|
|
||||||
<p><i>Bugs fixed:</i></p>
|
|
||||||
<ul>
|
|
||||||
<li>ArrayIterator can now iterate over arrays of primatives.</li>
|
|
||||||
<li>ArrayIterator.setArray(Object) will no longer throw an
|
|
||||||
ArrayIndexOutOfBounds exception.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p><u>LRUMap</u></p>
|
|
||||||
|
|
||||||
<p>LRUMap has been reimplemented as a subclass of
|
|
||||||
SynchronizedHashMap. The new implementation of
|
|
||||||
LRUMap should be faster, and it also offers true LRU
|
|
||||||
capabilities; now any get(Object) or
|
|
||||||
put(Object,Object) from this collection
|
|
||||||
promotes the key to the Most Recently Used position.</p>
|
|
||||||
|
|
||||||
<p><i>LRUMap 2.0 compatibility changes:</i></p>
|
|
||||||
<ul>
|
|
||||||
<li>LRUMap can no longer be cast to a HashMap.</li>
|
|
||||||
<li>The removeLRU() method now has a different
|
|
||||||
signature, and is no longer public. Instead, use
|
|
||||||
remove(getFirstKey()).</li>
|
|
||||||
<li>"Externalized" LRUMap 1.0 Objects cannot be
|
|
||||||
read by LRUMap 2.0.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p><i>New features:</i></p>
|
|
||||||
<ul>
|
|
||||||
<li>True LRU algorithm.</li>
|
|
||||||
<li>New methods from SequencedHashMap superclass.</li>
|
|
||||||
<li>processRemovedLRU(Object key, Object value) method
|
|
||||||
allows subclasses to perform custom actions on
|
|
||||||
keys and values that are expunged from the Map.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p><i>Bugs fixed:</i></p>
|
|
||||||
<ul>
|
|
||||||
<li>calling setMaximumSize(int) will remove excess LRUs
|
|
||||||
when the current size of the Map exceeds the new
|
|
||||||
maximum size</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<p><u>BeanMap</u></p>
|
|
||||||
|
|
||||||
<p>BeanMap's entrySet() now properly returns a set containing Map.Entry
|
|
||||||
objects. Previously, entrySet() was equivalent to keySet() (returns a set of
|
|
||||||
the readable properties) and there was no mechanism to retrieve all of the
|
|
||||||
readable properties along with their values. Additionally, the BeanMap clone
|
|
||||||
method has been revamped to work better for subclasses. </p>
|
|
||||||
|
|
||||||
<p><i>BeanMap 2.0 compatibility changes:</i></p>
|
|
||||||
<ul>
|
|
||||||
|
|
||||||
<li>BeanMap's clone() method now declares it throws
|
|
||||||
CloneNotSupportedException. This allows subclasses of BeanMap to not require
|
|
||||||
being Cloneable and facilitates subclasses that wish to be cloneable (allows
|
|
||||||
the subclass to call super.clone() and have it return an instance of the
|
|
||||||
child rather than the parent).</li>
|
|
||||||
|
|
||||||
<li>If a BeanMap is not cloneable because a new instance of the underlying
|
|
||||||
bean cannot be constructed, a CloneNotSupportedException is thrown rather
|
|
||||||
than an UnsupportedOperationException or other RuntimeException.</li>
|
|
||||||
|
|
||||||
<li>BeanMap's entrySet() method now returns a set of Map.Entry objects rather
|
|
||||||
than the set of readable properties. To retrieve a set of readable
|
|
||||||
properties, use keySet() instead.</li>
|
|
||||||
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p><i>Bugs fixed:</i></p>
|
|
||||||
<ul>
|
|
||||||
|
|
||||||
<li>If no bean is set in the BeanMap, or setBean(Object) was called with a
|
|
||||||
null argument, many BeanMap methods threw NullPointerExceptions. These have
|
|
||||||
been fixed to properly handle the case where there is no bean established in
|
|
||||||
the map.</li>
|
|
||||||
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<p><u>PriorityQueue</u></p>
|
|
||||||
|
|
||||||
<p>Changed to allow priority queue implementations that support determining
|
|
||||||
priorities using means other than the object's natural ordering (i.e. a
|
|
||||||
priority queue that does not depend on the object implementing the Comparable
|
|
||||||
interface).</p>
|
|
||||||
|
|
||||||
<p><i>PriorityQueue 2.0 compatibility changes:</i></p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
|
|
||||||
<li>The pop() and peek() methods were changed to return a generic Object
|
|
||||||
rather than a comparable.</li>
|
|
||||||
|
|
||||||
<li>The insert(Comparable) method was changed to take an Object argument
|
|
||||||
rather than a comparable.</li>
|
|
||||||
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<p><u>BinaryHeap</u></p>
|
|
||||||
|
|
||||||
<p>Changed to allow the specification of a Comparator that should be used to
|
|
||||||
compare objects to determine "priority" of the objects. If no comparator is
|
|
||||||
specified, the object's natural ordering is used.</p>
|
|
||||||
|
|
||||||
<p><i>BinaryHeap 2.0 compatibility changes:</i></p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
|
|
||||||
<li>The pop() and peek() methods were changed to return a generic Object
|
|
||||||
rather than a comparable.</li>
|
|
||||||
|
|
||||||
<li>The insert(Comparable) method was changed to take an Object argument
|
|
||||||
rather than a comparable.</li>
|
|
||||||
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p><i>New features:</i></p>
|
|
||||||
<ul>
|
|
||||||
|
|
||||||
<li>The BinaryHeap supports objects that do not implement Comparable. To use
|
|
||||||
such objects in the binary heap, a suitable Comparator must be provided in
|
|
||||||
the constructor so that the binary heap is capable of ordering elements in
|
|
||||||
their relative priorities.</li>
|
|
||||||
|
|
||||||
</ul>
|
|
||||||
|
|
@ -1,264 +0,0 @@
|
||||||
<title>RELEASE NOTES: COLLECTIONS 2.1</title>
|
|
||||||
|
|
||||||
<center><h2>RELEASE NOTES: COLLECTIONS 2.1</h2></center>
|
|
||||||
|
|
||||||
<p><i>Collections 2.1</i> includes a significant number of new collections
|
|
||||||
in addition to various bug fixes and refactoring changes. The major additions
|
|
||||||
are:
|
|
||||||
</p>
|
|
||||||
<ul>
|
|
||||||
<li><strong>Buffers</strong> - A new collection interface for queues and
|
|
||||||
queue-like things.</li>
|
|
||||||
<li><strong>Decorators</strong> - A group of static utility classes that provide
|
|
||||||
decorators for other collections</li>
|
|
||||||
</ul>
|
|
||||||
<p>
|
|
||||||
The decorators are found on classes named <code>XxxUtils</code> where Xxx is the
|
|
||||||
collection type. The decorators are:
|
|
||||||
</p>
|
|
||||||
<ul>
|
|
||||||
<li><strong>Synchronized</strong> - Synchronized decorators where not provided
|
|
||||||
by <code>Collections</code>.</li>
|
|
||||||
<li><strong>Unmodifiable</strong> - Unmodifiable decorators where not provided
|
|
||||||
by <code>Collections</code>.</li>
|
|
||||||
<li><strong>Predicated</strong> - Decorators that only allow the addition of an
|
|
||||||
element to the collection if it matches a <code>Predicate</code>.</li>
|
|
||||||
<li><strong>FixedSize</strong> - Decorators that ensure that the list/map
|
|
||||||
cannot change size.</li>
|
|
||||||
<li><strong>Lazy</strong> - Decorators that create objects on demand using a
|
|
||||||
<code>Factory</code>.</li>
|
|
||||||
</ul>
|
|
||||||
<p>
|
|
||||||
Access to Iterators and Comparators has also been brought in line, by the provision
|
|
||||||
of <code>IteratorUtils</code> and <code>ComparatorUtils</code>.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<hr />
|
|
||||||
|
|
||||||
<center><h3>
|
|
||||||
NEW COLLECTIONS, COMPARATORS, ITERATORS AND UTILITY CLASSES
|
|
||||||
</h3></center>
|
|
||||||
|
|
||||||
<p>These collections are new to <i>Collections 2.1</i>:</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><strong>Buffer</strong> - A collection that allows elements to be removed
|
|
||||||
in some well-defined order. Can describe queues, stacks, priority queues,
|
|
||||||
LRU caches or any other structure that allows elements to be removed in a
|
|
||||||
well-defined order. <I>Note: this is an interface with several
|
|
||||||
implementations.</I></li>
|
|
||||||
<li><strong>BoundedFifoBuffer</strong> - A very efficient FIFO queue
|
|
||||||
implementation of Buffer. Places an upper limit on the number of elements
|
|
||||||
that can be added.</li>
|
|
||||||
<li><strong>ReferenceMap</strong> - Hash-based Map implementation that allows
|
|
||||||
mappings to be removed by the garbage collector.</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>UnboundedFifoBuffer</strong> - A very efficient buffer
|
|
||||||
implementation. It places no upper limit on the number of elements.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p>These comparators are new to <i>Collections 2.1</i>:</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><strong>NullComparator</strong> - A Comparator that will compare nulls
|
|
||||||
to be either lower or higher than other objects.</li>
|
|
||||||
<li><strong>TransformingComparator</strong> - Decorates another Comparator
|
|
||||||
with transformation behavior.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p>These iterators are new to <i>Collections 2.1</i>:</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><strong>CollatingIterator</strong> - Provides an ordered iteration over
|
|
||||||
the elements contained in a collection of ordered Iterators.</li>
|
|
||||||
<li><strong>IteratorChain</strong> - An Iterator that wraps one or more
|
|
||||||
Iterators.</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>UniqueFilterIterator</strong> - A FilterIterator which only
|
|
||||||
returns unique objects.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p>These are the new utility classes:</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><strong>BagUtils</strong> - Contains static utility methods for dealing
|
|
||||||
with bags.</li>
|
|
||||||
<li><strong>BufferUtils</strong> - Contains static utility methods for
|
|
||||||
dealing with buffers.</li>
|
|
||||||
<li><strong>ComparatorUtils</strong> - Contains static utility methods for
|
|
||||||
dealing with comparators. Note that the functionality can also be achieved
|
|
||||||
by using the individual classes in the comparators subpackage.</li>
|
|
||||||
<li><strong>IteratorUtils</strong> - Contains static utility methods for
|
|
||||||
dealing with iterators. Note that the functionality can also be achieved
|
|
||||||
by using the individual classes in the iterators subpackage.</li>
|
|
||||||
<li><strong>SetUtils</strong> - Contains static utility methods for dealing
|
|
||||||
with sets.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<hr />
|
|
||||||
|
|
||||||
<center><h3>CHANGED CLASSES</h3></center>
|
|
||||||
|
|
||||||
These classes have changed since <i>Collections 2.0</i>:
|
|
||||||
|
|
||||||
<p><u>ArrayStack</u></p>
|
|
||||||
|
|
||||||
<p>Now implements the Buffer interface. The Buffer.get() and Buffer.remove()
|
|
||||||
methods are implemented in terms of peek() and pop(). The class has also
|
|
||||||
been altered to allow null elements inline with ArrayList.</p>
|
|
||||||
|
|
||||||
<p><u>BeanMap</u></p>
|
|
||||||
|
|
||||||
<p>A new method was added to allow a bulk putAll(Map) operation only for
|
|
||||||
bean properties that are actually writeable. The new method, named
|
|
||||||
putAllWriteable(Map), can be used to set one bean's state to another's
|
|
||||||
by using two BeanMaps.</p>
|
|
||||||
|
|
||||||
<p><u>BinaryHeap</u></p>
|
|
||||||
|
|
||||||
<p>Now implements the Buffer interface. Since Buffer is a subinterface of
|
|
||||||
Collection, BinaryHeap is also a Collection. This makes it much more
|
|
||||||
interoperable with existing APIs. The Buffer.get() and Buffer.remove()
|
|
||||||
methods are implemented in terms of peek() and pop().</p>
|
|
||||||
|
|
||||||
<p><u>CollectionUtils</u></p>
|
|
||||||
|
|
||||||
<p>Modified the index(Object,Object) method to work for arbitrary collections.
|
|
||||||
Previously the method only worked for Lists. Added the
|
|
||||||
predicatedCollection(Collection, Predicate) method.</p>
|
|
||||||
|
|
||||||
<p><u>CursorableLinkedList</u></p>
|
|
||||||
|
|
||||||
<p>Fixed NullPointerExceptions that were raised by contains(Object),
|
|
||||||
indexOf(Object), lastIndexOf(Object) and remove(Object) if the given
|
|
||||||
Object was null.</p>
|
|
||||||
|
|
||||||
<p><u>DefaultMapBag</u></p>
|
|
||||||
|
|
||||||
<p>A basic toString() method was added to aid in debugging.</p>
|
|
||||||
|
|
||||||
<p><u>FastArrayList</u></p>
|
|
||||||
|
|
||||||
<p>Added severe warning about possible unexpected failures of this class on
|
|
||||||
some architectures. Fixed the subList(int,int) method so that changes to the
|
|
||||||
sublist are reflected in the original list, even in fast mode.</p>
|
|
||||||
|
|
||||||
<p><u>FastHashMap</u></p>
|
|
||||||
|
|
||||||
<p>Added severe warning about possible unexpected failures of this class on
|
|
||||||
some architectures. Fixed the collection views so changes to the
|
|
||||||
map are reflected in the collection views and vice-versa, even in fast
|
|
||||||
mode.</p>
|
|
||||||
|
|
||||||
<p><u>FastTreeMap</u></p>
|
|
||||||
|
|
||||||
<p>Added severe warning about possible unexpected failures of this class on
|
|
||||||
some architectures. Fixed the collection views so changes to the
|
|
||||||
map are reflected in the collection views and vice-versa, even in fast
|
|
||||||
mode.</p>
|
|
||||||
|
|
||||||
<p><u>LRUMap</u></p>
|
|
||||||
|
|
||||||
<p>The get(Object) method was fixed to ensure that if containsKey(foo)
|
|
||||||
returns false, then get(foo) will not change that. (Before, invoking
|
|
||||||
get(Object) on a nonexistent key could cause that key to incorrectly map
|
|
||||||
to a null value). Also, the changes to SequencedHashMap were inherited
|
|
||||||
by LRUMap.</p>
|
|
||||||
|
|
||||||
<p><u>ListUtils</u></p>
|
|
||||||
|
|
||||||
<p>The previous version of this class was deprecated; it has been
|
|
||||||
un-deprecated. Decorators were added to allow predicated, lazy and
|
|
||||||
fixed-size lists.</p>
|
|
||||||
|
|
||||||
<p><u>MapUtils</u></p>
|
|
||||||
|
|
||||||
<p>Added decorators to allow predicated, lazy and fixed-size maps and
|
|
||||||
sorted maps.</p>
|
|
||||||
|
|
||||||
<p><u>ProxyMap</u></p>
|
|
||||||
|
|
||||||
<p>Fixed a bug in the equals(Object) method. Before the equals(Object)
|
|
||||||
method infinitely recursively called itself until a StackOverflowError
|
|
||||||
was raised. This version of the method properly delegates the method
|
|
||||||
call to the underlying map.</p>
|
|
||||||
|
|
||||||
<p><u>SequencedHashMap</u></p>
|
|
||||||
|
|
||||||
<p>The iterators on collection views now raise a ConcurrentModificationException
|
|
||||||
if the map is modified through something other than the iterator. The
|
|
||||||
equals(Object) and hashCode() methods were fixed to correctly implement
|
|
||||||
the Map specification. The remove(Object) methods in the keySet() and
|
|
||||||
entrySet() were fixed so that they correctly return false after removing
|
|
||||||
a null key.</p>
|
|
||||||
|
|
||||||
<p><u>SoftRefHashMap</u></p>
|
|
||||||
|
|
||||||
<p>SoftRefHashMap has been <b>deprecated</b> because it was all kinds of
|
|
||||||
wonky. Its semantics were never well-defined, many of its operations had
|
|
||||||
unintuitive side-effects, it violated the java.util.Map contract in several
|
|
||||||
places and its internal algorithms were inefficient. A new class,
|
|
||||||
ReferenceMap, is a more general solution that can be used in place of
|
|
||||||
SoftRefHashMap.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p><u>StringStack</u></p>
|
|
||||||
|
|
||||||
<p>StringStack has been <b>deprecated</b> because it was unsuitable for
|
|
||||||
inclusion in collections. It enabled a delimited String to be built up.
|
|
||||||
This functionality is better placed in StringUtils in the lang project.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<hr />
|
|
||||||
|
|
||||||
|
|
||||||
<center><h3>REFACTORING</h3></center>
|
|
||||||
|
|
||||||
<p><u>Documentation</u></p>
|
|
||||||
|
|
||||||
<p>Almost every class released in 2.0 was touched to improve on, or in
|
|
||||||
some cases complete, the JavaDoc. Those documentation changes are not
|
|
||||||
described in detail below; but the goal was simply to have the public
|
|
||||||
and protected Collections API completely documentated. If a class released
|
|
||||||
in 2.0 had missing public or protected JavaDoc, then the class was modified
|
|
||||||
to add it.</p>
|
|
||||||
|
|
||||||
<p><u>New Testing Suite</u></p>
|
|
||||||
|
|
||||||
<p>The unit testing framework used to test collections and maps underwent
|
|
||||||
a major overhaul between 2.0 and 2.1. The new tests check for stricter
|
|
||||||
Collection and Map contract conformance. Many bugs were found and addressed
|
|
||||||
with the new tests; bug fixes are described below. The testing suite is
|
|
||||||
not considered part of the binary release and may undergo further changes.</p>
|
|
||||||
|
|
||||||
<p><u>New iterators Subpackage</u></p>
|
|
||||||
|
|
||||||
<p>All of the iterator classes released in <i>Collections 2.0</i> have been
|
|
||||||
moved to an iterators subpackage in <i>Collections 2.1</i>. Versions of
|
|
||||||
the iterators still exist in the main package, but have been deprecated.
|
|
||||||
This was a simple organizational move that will hopefully make the packages
|
|
||||||
easier to navigate and absorb.</p>
|
|
||||||
|
|
||||||
<p>The affected classes from 2.0 are:</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li>ArrayIterator</li>
|
|
||||||
<li>EnumerationIterator</li>
|
|
||||||
<li>FilterIterator</li>
|
|
||||||
<li>FilterListIterator</li>
|
|
||||||
<li>IteratorEnumeration</li>
|
|
||||||
<li>ProxyIterator</li>
|
|
||||||
<li>ProxyListIterator</li>
|
|
||||||
<li>SingletonIterator</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p>In addition, new iterators were added to the subpackage; these are
|
|
||||||
described below.</p>
|
|
||||||
|
|
||||||
<p>Note that other than being in a new package, no other changes were made
|
|
||||||
to the iterator implementations.</p>
|
|
||||||
|
|
@ -0,0 +1,107 @@
|
||||||
|
<title>RELEASE NOTES: COLLECTIONS 3.0</title>
|
||||||
|
|
||||||
|
<center><h2>RELEASE NOTES: COLLECTIONS 3.0</h2></center>
|
||||||
|
|
||||||
|
<p><i>Collections 3.0</i> includes a significant number of new collections
|
||||||
|
in addition to various bug fixes and refactoring changes. The major additions
|
||||||
|
are:
|
||||||
|
</p>
|
||||||
|
<ul>
|
||||||
|
<li><strong>Buffers</strong> - A new collection interface for queues and
|
||||||
|
queue-like things.</li>
|
||||||
|
<li><strong>Decorators</strong> - A group of static utility classes that provide
|
||||||
|
decorators for other collections</li>
|
||||||
|
</ul>
|
||||||
|
<p>
|
||||||
|
The decorators are found on classes named <code>XxxUtils</code> where Xxx is the
|
||||||
|
collection type. The decorators are:
|
||||||
|
</p>
|
||||||
|
<ul>
|
||||||
|
<li><strong>Synchronized</strong> - Synchronized decorators where not provided
|
||||||
|
by <code>Collections</code>.</li>
|
||||||
|
<li><strong>Unmodifiable</strong> - Unmodifiable decorators where not provided
|
||||||
|
by <code>Collections</code>.</li>
|
||||||
|
<li><strong>Predicated</strong> - Decorators that only allow the addition of an
|
||||||
|
element to the collection if it matches a <code>Predicate</code>.</li>
|
||||||
|
<li><strong>FixedSize</strong> - Decorators that ensure that the list/map
|
||||||
|
cannot change size.</li>
|
||||||
|
<li><strong>Lazy</strong> - Decorators that create objects on demand using a
|
||||||
|
<code>Factory</code>.</li>
|
||||||
|
</ul>
|
||||||
|
<p>
|
||||||
|
Access to Iterators and Comparators has also been brought in line, by the provision
|
||||||
|
of <code>IteratorUtils</code> and <code>ComparatorUtils</code>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr />
|
||||||
|
|
||||||
|
<center><h3>
|
||||||
|
NEW COLLECTIONS, COMPARATORS, ITERATORS AND UTILITY CLASSES
|
||||||
|
</h3></center>
|
||||||
|
|
||||||
|
<p>These collections are new to <i>Collections 3.0</i>:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>These comparators are new to <i>Collections 2.1</i>:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>These iterators are new to <i>Collections 2.1</i>:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<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>ObjectArrayIterator/ListIterator</strong> -
|
||||||
|
Provides iterators over an Object array.</li>
|
||||||
|
|
||||||
|
<li><strong>ResetableIterator/ListIterator</strong> -
|
||||||
|
Interface that defines a reset() method to reset the iterator back to the start.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>These are the new utility classes:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
|
||||||
|
<hr />
|
||||||
|
|
||||||
|
<center><h3>CHANGED CLASSES</h3></center>
|
||||||
|
|
||||||
|
<p>These iterators have changed since <i>Collections 2.1</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>SingletonIterator/ListIterator</strong> -
|
||||||
|
These now implement the ResetableIterator interface.</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>
|
||||||
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
<!-- $Id: build.xml,v 1.40 2003/09/27 10:54:06 scolebourne Exp $ -->
|
<!-- $Id: build.xml,v 1.41 2003/09/29 22:46:15 scolebourne Exp $ -->
|
||||||
<project name="commons-collections" default="test" basedir=".">
|
<project name="commons-collections" default="test" basedir=".">
|
||||||
|
|
||||||
<!-- patternset describing files to be copied from the doc directory -->
|
<!-- patternset describing files to be copied from the doc directory -->
|
||||||
|
|
@ -52,7 +52,7 @@
|
||||||
|
|
||||||
<!-- The current version number of this component -->
|
<!-- The current version number of this component -->
|
||||||
<property name="component.version" value="2.1"/>
|
<property name="component.version" value="2.1"/>
|
||||||
<property name="doc.release.notes" value="RELEASE-NOTES-${component.version}.html"/>
|
<property name="doc.release.notes" value="RELEASE-NOTES.html"/>
|
||||||
<property name="doc.status" value="STATUS.html"/>
|
<property name="doc.status" value="STATUS.html"/>
|
||||||
|
|
||||||
<property name="test.entry" value="org.apache.commons.collections.TestAll"/>
|
<property name="test.entry" value="org.apache.commons.collections.TestAll"/>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue