<?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</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </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><a href='#Utilities'>Utilities</a> for the standard collections.</li>
    <li><a href='#Maps'>Maps</a>
      <ul>
         <li><a href='#Map%20Iteration'>Map Iteration</a></li>
         <li><a href='#Ordered%20Maps'>Ordered Maps</a></li>
         <li><a href='#Bidirectional%20Maps'>Bidirectional Maps</a></li>
      </ul>
    </li>
    <li><a href='#Queues%20and%20Buffers'>Queues and Buffers</a></li>
    <li><a href='#Bags'>Bags</a></li>
  </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</code> method on <code>Collections</code> 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</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='Maps'>
<subsection 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>

</subsection>

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

</subsection>

<subsection name="Bidirectional Maps">

<p>
A new interface hierarchy has been added to support bidirectional maps - <code>BidiMap.</code>
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.</code>
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.</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>
