Improve maven documentation for release 3.0
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131529 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne
parent
2ebe287c9b
commit
37777fa7df
|
|
@ -12,51 +12,59 @@
|
|||
<section name="The Collections Component">
|
||||
|
||||
<p>
|
||||
The introduction of the <a href="http://java.sun.com/products/j2se/1.3/docs/guide/collections/">Collections API</a> by Sun in JDK 1.2 has been a
|
||||
boon to quick and effective Java programming. Ready access to
|
||||
powerful data structures has accelerated development by reducing the
|
||||
need for custom container classes around each core object. Most Java2
|
||||
APIs are significantly easier to use because of the Collections API.
|
||||
The <a href="http://java.sun.com/products/j2se/1.4/docs/guide/collections/">Java Collections Framework</a>
|
||||
was a major addition in JDK 1.2.
|
||||
It added many powerful data structures that accelerate development of most significant Java applications.
|
||||
Since that time it has become the regognised standard for collection handling in the Java language.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
However, there are certain holes left unfilled by Sun's
|
||||
implementations, and the <a href="http://jakarta.apache.org/commons/">Jakarta-Commons</a> Collections Component strives
|
||||
to fulfill them. Among the features of this package are:
|
||||
Commons-Collections seek to build upon the JDK classes by providing new interfaces, implementations and utilities.
|
||||
There are many features, including:
|
||||
<ul>
|
||||
<li>Special-purpose implementations of Lists and Maps for fast
|
||||
access</li>
|
||||
<li>Adapter classes from Java1-style containers (arrays, enumerations)
|
||||
to Java2-style collections.</li>
|
||||
<li>Methods to test or create typical set-theory properties of
|
||||
collections such as union, intersection, and closure.</li>
|
||||
<li>Bag interface for collections that have a number of copies of each object</li>
|
||||
<li>Buffer interface for collections that have a well defined removal order, like FIFOs</li>
|
||||
<li>BidiMap interface for maps that can be looked up from value to key as well and key to value</li>
|
||||
<li>MapIterator interface to provide simple and quick iteration over maps</li>
|
||||
<li>Type checking decorators to ensure that only instances of a certain type can be added</li>
|
||||
<li>Transforming decorators that alter each object as it is added to the collection</li>
|
||||
<li>Composite collections that make multiple collections look like one</li>
|
||||
<li>Ordered maps and sets that retain the order elements are added in, including an LRU based map</li>
|
||||
<li>Identity map that compares objects based on their identity (==) instead of the equals method</li>
|
||||
<li>Reference map that allows keys and/or values to be garbage collected under close control</li>
|
||||
<li>Many comparator implementations</li>
|
||||
<li>Many iterator implementations</li>
|
||||
<li>Adapter classes from array and enumerations to collections</li>
|
||||
<li>Utilities to test or create typical set-theory properties of collections such as union, intersection, and closure</li>
|
||||
</ul>
|
||||
</p>
|
||||
</section>
|
||||
|
||||
|
||||
<section name="Documentation">
|
||||
<p>
|
||||
An alphabetical list of the package can be found in the <a href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-commons/collections/STATUS.html?rev=1.19">collections
|
||||
status document</a>.
|
||||
A getting started <a href="userguide.html">User's Guide</a> is available.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The <a href="api/index.html">JavaDoc API documents</a> are available online.
|
||||
The JavaDoc API documents are available online for the
|
||||
<a href="api-30/index.html">current release 3.0</a>, the
|
||||
<a href="api-21/index.html">previous version 2.1</a>, and the
|
||||
<a href="apidocs/index.html">latest CVS</a>.
|
||||
</p>
|
||||
<p>
|
||||
The <a href="http://cvs.apache.org/viewcvs/jakarta-commons/collections/">CVS repository</a> can be browsed.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
|
||||
<section name="Releases">
|
||||
<ul>
|
||||
<li><a
|
||||
href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-collections/v2.1/">Version
|
||||
2.1</a></li>
|
||||
<li><a
|
||||
href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-collections/v2.0/">Version
|
||||
2.0</a></li>
|
||||
<li><a
|
||||
href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-collections/v1.0/">Version
|
||||
1.0</a></li>
|
||||
</ul>
|
||||
<p>
|
||||
Version 3.0 -
|
||||
<a href="http://jakarta.apache.org/site/binindex.cgi">Binary</a> -
|
||||
<a href="http://jakarta.apache.org/site/sourceindex.cgi">Source</a>
|
||||
</p>
|
||||
<p>
|
||||
For previous releases, see the <a href="http://archive.apache.org/dist/jakarta/commons/collections/">Apache Archive</a>
|
||||
</p>
|
||||
</section>
|
||||
|
||||
</body>
|
||||
|
|
|
|||
|
|
@ -13,9 +13,15 @@
|
|||
|
||||
<body>
|
||||
<menu name="Commons Collections">
|
||||
<item name="Overview"
|
||||
href="/index.html"/>
|
||||
|
||||
<item name="Overview" href="/index.html"/>
|
||||
<item name="Users guide" href="/userguide.html"/>
|
||||
<item name="Javadoc (3.0 release)" href="api-30/index.html"/>
|
||||
<item name="Mailing lists" href="/mail-lists.html"/>
|
||||
<item name="Team" href="/team-list.html"/>
|
||||
<item name="Tasks" href="/tasks.html"/>
|
||||
<item name="CVS" href="http://cvs.apache.org/viewcvs/jakarta-commons/collections/"/>
|
||||
<item name="Javadoc (CVS latest)" href="apidocs/index.html"/>
|
||||
<item name="Javadoc (2.1 old)" href="api-21/index.html"/>
|
||||
</menu>
|
||||
|
||||
&commons-nav;
|
||||
|
|
|
|||
|
|
@ -0,0 +1,40 @@
|
|||
<?xml version="1.0"?>
|
||||
|
||||
<document>
|
||||
|
||||
<properties>
|
||||
<title>Commons Collections - Tasks outstanding</title>
|
||||
<author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
|
||||
</properties>
|
||||
|
||||
<body>
|
||||
|
||||
<section name="Tasks outstanding">
|
||||
|
||||
<p>
|
||||
The following tasks are on the TODO list:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>Synchronized Map decorators</li>
|
||||
<li>Synchronized BidiMap decorators</li>
|
||||
<li>Serializable decorators</li>
|
||||
<li>MultiMap subpackage implementing a revised interface</li>
|
||||
<li>IdentitySet</li>
|
||||
<li>BidiMapUtils</li>
|
||||
<li>LoopingListIterator</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Would you like to <a href="mail-lists.html">Volunteer</a>?
|
||||
</p>
|
||||
</section>
|
||||
|
||||
</body>
|
||||
</document>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,137 @@
|
|||
<?xml version="1.0" encoding="ISO-8859-1"?>
|
||||
|
||||
<document>
|
||||
|
||||
<properties>
|
||||
<title>Commons Collections - Users guide</title>
|
||||
<author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
|
||||
</properties>
|
||||
|
||||
<body>
|
||||
|
||||
<section name="Introduction">
|
||||
|
||||
<p>
|
||||
Commons-Collections provides a large number of classes to aid day to day programming.
|
||||
This document highlights some key features to get you started.
|
||||
</p>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Utils classes">
|
||||
|
||||
<p>
|
||||
A Utility class is provided for each major collection interface.
|
||||
Thus, the <code>Set</code> and <code>SortedSet</code> interfaces are provided for by <code>SetUtils</code>.
|
||||
These classes provide useful methods for working with that collection type.
|
||||
</p>
|
||||
<p>
|
||||
The most methods are found on the two 'root' collection utility classes -
|
||||
<code>CollectionUtils</code> and <code>MapUtils</code>.
|
||||
As all other collection interfaces extend <code>Collection</code> or <code>Map</code> these utilities can be used widely.
|
||||
They include intersection, counting, iteration, functor and typecasting operations amongst others.
|
||||
The utility classes also provide access to collection decorator classes in a way similar to the JDK <code>Collections</code> class.
|
||||
</p>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Map iteration">
|
||||
|
||||
<p>
|
||||
The JDK <code>Map</code> interface always suffered from being difficult to iterate over.
|
||||
API users are forced to either iterate over an EntrySet or over the KeySet.
|
||||
Commons-Collections now provides a new interface - <code>MapIterator</code> that allows simple iteration over maps.
|
||||
</p>
|
||||
<source>
|
||||
IterableMap map = new HashedMap();
|
||||
MapIterator it = map.mapIterator();
|
||||
while (it.hasNext()) {
|
||||
Object key = it.next();
|
||||
Object value = it.getValue();
|
||||
|
||||
it.setValue(newValue);
|
||||
}
|
||||
</source>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Ordered maps">
|
||||
|
||||
<p>
|
||||
A new interface is provided for maps that have an order but are not sorted - <code>OrderedMap</code>.
|
||||
Two implementations are provided - <code>LinkedMap</code> and <code>ListOrderedMap</code> (a decorator).
|
||||
This interface supports the map iterator, and also allows iteration both forwards and backwards through the map.
|
||||
</p>
|
||||
<source>
|
||||
OrderedMap map = new LinkedMap();
|
||||
map.put("FIVE", "5");
|
||||
map.put("SIX", "6");
|
||||
map.put("SEVEN", "7");
|
||||
map.firstKey(); // returns "FIVE"
|
||||
map.nextKey("FIVE"); // returns "SIX"
|
||||
map.nextKey("SIX"); // returns "SEVEN"
|
||||
</source>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Bidirectional maps">
|
||||
|
||||
<p>
|
||||
A new interface hierarchy has been added to support bidirectional maps - <code>BidiMap</code>.
|
||||
These represent maps where the the key can lookup the value and the value can lookup the key with equal ease.
|
||||
</p>
|
||||
<source>
|
||||
BidiMap bidi = new TreeBidiMap();
|
||||
bidi.put("SIX", "6");
|
||||
bidi.get("SIX"); // returns "six"
|
||||
bidi.getKey("6"); // returns "SIX"
|
||||
bidi.removeValue("6"); // removes the mapping
|
||||
BidiMap inverse = bidi.inverseBidiMap(); // returns a map with keys and values swapped
|
||||
</source>
|
||||
<p>
|
||||
Additional interfaces are provided for ordered and sorted bidirectional maps.
|
||||
Implementations are provided for each bidirectional map type.
|
||||
</p>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Queues and buffers">
|
||||
|
||||
<p>
|
||||
A new interface hierarchy has been added to support queues and buffers - <code>Buffer</code>.
|
||||
These represent collections that have a well defined removal order.
|
||||
</p>
|
||||
<source>
|
||||
Buffer buffer = new UnboundedFifoBuffer();
|
||||
bidi.add("ONE");
|
||||
bidi.add("TWO");
|
||||
bidi.add("THREE");
|
||||
bidi.remove(); // removes and returns the next in order, "ONE" as this is a FIFO
|
||||
bidi.remove(); // removes and returns the next in order, "TWO" as this is a FIFO
|
||||
</source>
|
||||
<p>
|
||||
Implementations are provided for FIFO (queue), LIFO (stack) and Priority (removal in comparator order).
|
||||
</p>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Bags">
|
||||
|
||||
<p>
|
||||
A new interface hierarchy has been added to support bags - <code>Bag</code>.
|
||||
These represent collections where a certain number of copies of each element is held.
|
||||
</p>
|
||||
<source>
|
||||
Bag bag = new HashBag();
|
||||
bag.add("ONE", 6); // add 6 copies of "ONE"
|
||||
bag.remove("ONE", 2); // removes 2 copies of "ONE"
|
||||
bag.getCount("ONE"); // returns 4, the number of copies in the bag (6 - 2)
|
||||
</source>
|
||||
<p>
|
||||
Implementations are provided for both unsorted and sorted Bags.
|
||||
</p>
|
||||
|
||||
</section>
|
||||
|
||||
</body>
|
||||
</document>
|
||||
Loading…
Reference in New Issue