From 37777fa7df38175745175d8a05faab26b1c4a8c9 Mon Sep 17 00:00:00 2001 From: Stephen Colebourne Date: Tue, 6 Jan 2004 00:44:20 +0000 Subject: [PATCH] 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 --- xdocs/index.xml | 68 +++++++++++---------- xdocs/navigation.xml | 12 +++- xdocs/tasks.xml | 40 +++++++++++++ xdocs/userguide.xml | 137 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 224 insertions(+), 33 deletions(-) create mode 100644 xdocs/tasks.xml create mode 100644 xdocs/userguide.xml diff --git a/xdocs/index.xml b/xdocs/index.xml index 75ac9a987..4280b885b 100644 --- a/xdocs/index.xml +++ b/xdocs/index.xml @@ -12,51 +12,59 @@

-The introduction of the Collections API 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 Java Collections Framework +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.

-

-However, there are certain holes left unfilled by Sun's -implementations, and the Jakarta-Commons 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:

+

-An alphabetical list of the package can be found in the collections -status document. +A getting started User's Guide is available.

-

-The JavaDoc API documents are available online. +The JavaDoc API documents are available online for the +current release 3.0, the +previous version 2.1, and the +latest CVS. +

+

+The CVS repository can be browsed.

+
- +

+Version 3.0 - + Binary - + Source +

+

+ For previous releases, see the Apache Archive +

diff --git a/xdocs/navigation.xml b/xdocs/navigation.xml index 37d316777..e134570df 100644 --- a/xdocs/navigation.xml +++ b/xdocs/navigation.xml @@ -13,9 +13,15 @@ - - + + + + + + + + + &commons-nav; diff --git a/xdocs/tasks.xml b/xdocs/tasks.xml new file mode 100644 index 000000000..ac99ae965 --- /dev/null +++ b/xdocs/tasks.xml @@ -0,0 +1,40 @@ + + + + + + Commons Collections - Tasks outstanding + Commons Documentation Team + + + + +
+ +

+The following tasks are on the TODO list: +

+ +
    +
  • Synchronized Map decorators
    • +
  • Synchronized BidiMap decorators
    • +
  • Serializable decorators
    • +
  • MultiMap subpackage implementing a revised interface
    • +
  • IdentitySet
    • +
  • BidiMapUtils
    • +
  • LoopingListIterator
    • +
+ +

+Would you like to Volunteer? +

+
+ + + + + + + + + diff --git a/xdocs/userguide.xml b/xdocs/userguide.xml new file mode 100644 index 000000000..31a902546 --- /dev/null +++ b/xdocs/userguide.xml @@ -0,0 +1,137 @@ + + + + + + Commons Collections - Users guide + Commons Documentation Team + + + + +
+ +

+Commons-Collections provides a large number of classes to aid day to day programming. +This document highlights some key features to get you started. +

+ +
+ +
+ +

+A Utility class is provided for each major collection interface. +Thus, the Set and SortedSet interfaces are provided for by SetUtils. +These classes provide useful methods for working with that collection type. +

+

+The most methods are found on the two 'root' collection utility classes - +CollectionUtils and MapUtils. +As all other collection interfaces extend Collection or Map 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 Collections class. +

+ +
+ +
+ +

+The JDK Map 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 - MapIterator that allows simple iteration over maps. +

+ +IterableMap map = new HashedMap(); +MapIterator it = map.mapIterator(); +while (it.hasNext()) { + Object key = it.next(); + Object value = it.getValue(); + + it.setValue(newValue); +} + + +
+ +
+ +

+A new interface is provided for maps that have an order but are not sorted - OrderedMap. +Two implementations are provided - LinkedMap and ListOrderedMap (a decorator). +This interface supports the map iterator, and also allows iteration both forwards and backwards through the map. +

+ +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" + + +
+ +
+ +

+A new interface hierarchy has been added to support bidirectional maps - BidiMap. +These represent maps where the the key can lookup the value and the value can lookup the key with equal ease. +

+ +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 + +

+Additional interfaces are provided for ordered and sorted bidirectional maps. +Implementations are provided for each bidirectional map type. +

+ +
+ +
+ +

+A new interface hierarchy has been added to support queues and buffers - Buffer. +These represent collections that have a well defined removal order. +

+ +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 + +

+Implementations are provided for FIFO (queue), LIFO (stack) and Priority (removal in comparator order). +

+ +
+ +
+ +

+A new interface hierarchy has been added to support bags - Bag. +These represent collections where a certain number of copies of each element is held. +

+ +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) + +

+Implementations are provided for both unsorted and sorted Bags. +

+ +
+ + +