|
|
The Commons Collections userguide.xml source code
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<document>
<properties>
<title>User guide
<author email="dev@commons.apache.org">Commons Documentation Team
</properties>
<body>
<section name="User guide">
<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>
<ul>
<li>Utilities for the standard collections.
<li>Maps
<ul>
<li>Map Iteration
<li>Ordered Maps
<li>Bidirectional Maps
</ul>
</li>
<li>Queues and Buffers
<li>Bags
</ul>
<subsection name='Note On Synchronization'>
<p>
Commons-collections uses a design approach to synchronization similar
to the standard Java collections. The majority of the various implementations
of collections, maps and bags are not thread safe without additional
synchronization. The appropriate <code>synchronizeXXX method on Collections is one way that these implementations can be synchronized for use in a
multithreaded application.
</p>
<p>
The class level javadocs should indicate whether a particular
implementation is safe for multithreaded access without additional
synchronization. Where there is no expicit indication that the implementation
is thread safe then it should be assumed that synchronization is required.
Please report the missing documentation to the commons development team.
</p>
</subsection>
</section>
<section name="Utilities">
<p>
A Utility class is provided for each major collection interface.
Thus, the <code>Set and SortedSet interfaces are provided for by SetUtils.
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 and MapUtils.
As all other collection interfaces extend <code>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 <code>Collections class.
</p>
</section>
<section name='Maps'>
<subsection name="Map Iteration">
<p>
The JDK <code>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 - <code>MapIterator 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>
</subsection>
<subsection name="Ordered Maps">
<p>
A new interface is provided for maps that have an order but are not sorted - <code>OrderedMap.
Two implementations are provided - <code>LinkedMap and ListOrderedMap (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>
</subsection>
<subsection name="Bidirectional Maps">
<p>
A new interface hierarchy has been added to support bidirectional maps - <code>BidiMap.
These represent maps where 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 "6"
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>
</subsection>
</section>
<section name="Queues and Buffers">
<p>
A new interface hierarchy has been added to support queues and buffers - <code>Buffer.
These represent collections that have a well defined removal order.
</p>
<source>
Buffer buffer = new UnboundedFifoBuffer();
buffer.add("ONE");
buffer.add("TWO");
buffer.add("THREE");
buffer.remove(); // removes and returns the next in order, "ONE" as this is a FIFO
buffer.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.
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>
Other Commons Collections examples (source code examples)
Here is a short list of links related to this Commons Collections userguide.xml source code file:
|
The search page
Other Commons Collections source code examples at this package level
Click here to learn more about this project
