2004-01-05 19:44:20 -05:00
|
|
|
<?xml version="1.0" encoding="ISO-8859-1"?>
|
2004-02-17 20:00:08 -05:00
|
|
|
<!--
|
|
|
|
|
Copyright 2003-2004 The Apache Software Foundation
|
|
|
|
|
|
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
|
|
|
you may not use this file except in compliance with the License.
|
|
|
|
|
You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
|
limitations under the License.
|
|
|
|
|
-->
|
2004-01-05 19:44:20 -05:00
|
|
|
|
|
|
|
|
<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.
|
2004-01-11 15:54:44 -05:00
|
|
|
Thus, the <code>Set</code> and <code>SortedSet</code> interfaces are provided for by <code>SetUtils.</code>
|
2004-01-05 19:44:20 -05:00
|
|
|
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 -
|
2004-01-11 15:54:44 -05:00
|
|
|
<code>CollectionUtils</code> and <code>MapUtils.</code>
|
2004-01-05 19:44:20 -05:00
|
|
|
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>
|
2004-01-11 15:54:44 -05:00
|
|
|
A new interface is provided for maps that have an order but are not sorted - <code>OrderedMap.</code>
|
2004-01-05 19:44:20 -05:00
|
|
|
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>
|
2004-01-11 15:54:44 -05:00
|
|
|
A new interface hierarchy has been added to support bidirectional maps - <code>BidiMap.</code>
|
2004-01-05 19:44:20 -05:00
|
|
|
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");
|
2004-01-06 17:19:14 -05:00
|
|
|
bidi.get("SIX"); // returns "6"
|
2004-01-05 19:44:20 -05:00
|
|
|
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>
|
2004-01-11 15:54:44 -05:00
|
|
|
A new interface hierarchy has been added to support queues and buffers - <code>Buffer.</code>
|
2004-01-05 19:44:20 -05:00
|
|
|
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>
|
2004-01-11 15:54:44 -05:00
|
|
|
A new interface hierarchy has been added to support bags - <code>Bag.</code>
|
2004-01-05 19:44:20 -05:00
|
|
|
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>
|
