svn commit: r348292 - /jakarta/commons/proper/collections/trunk/xdocs/userguide.xml

[rd...@apache.org]

Author: rdonkin
Date: Tue Nov 22 15:37:40 2005
New Revision: 348292

URL: http://svn.apache.org/viewcvs?rev=348292&view=rev
Log:
Reorganized the user guide a little. Added a section on synchronization.

Modified:
    jakarta/commons/proper/collections/trunk/xdocs/userguide.xml

Modified: jakarta/commons/proper/collections/trunk/xdocs/userguide.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/collections/trunk/xdocs/userguide.xml?rev=348292&r1=348291&r2=348292&view=diff
==============================================================================
--- jakarta/commons/proper/collections/trunk/xdocs/userguide.xml (original)
+++ jakarta/commons/proper/collections/trunk/xdocs/userguide.xml Tue Nov 22 15:37:40 2005
@@ -30,10 +30,38 @@
 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="Utils classes">
+<section name="Utilities">
 
 <p>
 A Utility class is provided for each major collection interface.
@@ -50,7 +78,8 @@
 
 </section>
 
-<section name="Map iteration">
+<section name='Maps'>
+<subsection name="Map Iteration">
 
 <p>
 The JDK <code>Map</code> interface always suffered from being difficult to iterate over.
@@ -68,9 +97,9 @@
 }
 </source>
 
-</section>
+</subsection>
 
-<section name="Ordered maps">
+<subsection name="Ordered Maps">
 
 <p>
 A new interface is provided for maps that have an order but are not sorted - <code>OrderedMap.</code>
@@ -87,9 +116,9 @@
 map.nextKey("SIX");  // returns "SEVEN"
 </source>
 
-</section>
+</subsection>
 
-<section name="Bidirectional maps">
+<subsection name="Bidirectional Maps">
 
 <p>
 A new interface hierarchy has been added to support bidirectional maps - <code>BidiMap.</code>
@@ -108,9 +137,10 @@
 Implementations are provided for each bidirectional map type.
 </p>
 
+</subsection>
 </section>
 
-<section name="Queues and buffers">
+<section name="Queues and Buffers">
 
 <p>
 A new interface hierarchy has been added to support queues and buffers - <code>Buffer.</code>



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org