improved javadoc

jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java

@@ -25,7 +25,8 @@ import java.util.Set;
 
 
 /* ------------------------------------------------------------ */
-/** A Ternary Trie String lookup data structure.
+/** 
+ * <p>A Ternary Trie String lookup data structure.</p>
  * This Trie is of a fixed size and cannot grow (which can be a good thing with regards to DOS when used as a cache).
  * <p>
  * The Trie is stored in 3 arrays:<dl>
@@ -36,10 +37,21 @@ import java.util.Set;
  * indicates that the _tree row is a complete key rather than an intermediate character of a longer key.</dd>
  * <dt>V[] _value</dt><dd>An array of values corresponding to the _key array</dd>
  * </dl>
+ * </p>
  * <p>The lookup of a value will iterate through the _tree array matching characters. If the equal tree branch is followed,
  * then the _key array is looked up to see if this is a complete match.  If a match is found then the _value array is looked up
  * to return the matching value.
  * </p>
+ * <p>
+ * This Trie may be instantiated either as case sensitive or insensitive.
+ * </p>
+ * <p>This Trie is not Threadsafe and contains no mutual exclusion 
+ * or deliberate memory barriers.  It is intended for an ArrayTrie to be
+ * built by a single thread and then used concurrently by multiple threads
+ * and not mutated during that access.  If concurrent mutations of the
+ * Trie is required external locks need to be applied.
+ * </p>
+ * 
  * @param <V>
  */
 public class ArrayTernaryTrie<V> extends AbstractTrie<V>
@@ -78,27 +90,53 @@ public class ArrayTernaryTrie<V> extends AbstractTrie<V>
      */
     private char _rows;
 
+    /* ------------------------------------------------------------ */
+    /** Create a case insensitive Trie of default capacity.
+     */
     public ArrayTernaryTrie()
     {
         this(128);
     }
     
+    /* ------------------------------------------------------------ */
+    /** Create a Trie of default capacity
+     * @param insensitive true if the Trie is insensitive to the case of the key.
+     */
     public ArrayTernaryTrie(boolean insensitive)
     {
         this(insensitive,128);
     }
 
-    public ArrayTernaryTrie(int capacityInNodes)
+    /* ------------------------------------------------------------ */
+    /** Create a case insensitive Trie
+     * @param capacity  The capacity of the Trie, which is in the worst case
+     * is the total number of characters of all keys stored in the Trie.
+     * The capacity needed is dependent of the shared prefixes of the keys.
+     * For example, a capacity of 6 nodes is required to store keys "foo" 
+     * and "bar", but a capacity of only 4 is required to
+     * store "bar" and "bat".
+     */
+    public ArrayTernaryTrie(int capacity)
     {
-        this(true,capacityInNodes);
+        this(true,capacity);
     }
     
-    public ArrayTernaryTrie(boolean insensitive, int capacityInNodes)
+    /* ------------------------------------------------------------ */
+    /** Create a Trie
+     * @param insensitive true if the Trie is insensitive to the case of the key.
+     * @param capacity The capacity of the Trie, which is in the worst case
+     * is the total number of characters of all keys stored in the Trie.
+     * The capacity needed is dependent of the shared prefixes of the keys.
+     * For example, a capacity of 6 nodes is required to store keys "foo" 
+     * and "bar", but a capacity of only 4 is required to
+     * store "bar" and "bat".
+     */
+    public ArrayTernaryTrie(boolean insensitive, int capacity)
     {
         super(insensitive);
-        _value=(V[])new Object[capacityInNodes];
+        _value=(V[])new Object[capacity];
-        _tree=new char[capacityInNodes*ROW_SIZE];
+        _tree=new char[capacity*ROW_SIZE];
-        _key=new String[capacityInNodes];
+        _key=new String[capacity];
     }
 
     /* ------------------------------------------------------------ */

jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java

@@ -24,9 +24,25 @@ import java.util.HashSet;
 import java.util.Set;
 
 /* ------------------------------------------------------------ */
-/** A Trie String lookup data structure using a fixed size array.
+/** 
+ * <p>A Trie String lookup data structure using a fixed size array.</p>
  * <p>This implementation is always case insensitive and is optimal for
- * a small number of fixed strings with few special characters.
+ * a small number of fixed strings with few special characters.  The
+ * Trie is stored in an array of lookup tables, each indexed by the 
+ * next character of the key.   Frequently used characters are directly
+ * indexed in each lookup table, whilst infrequently used characters
+ * must use a big character table.
+ * </p>
+ * <p>This Trie is very space efficient if the key characters are 
+ * from ' ', '+', '-', ':', ';', '.', 'A' to 'Z' or 'a' to 'z'. 
+ * Other ISO-8859-1 characters can be used by the key, but less space
+ * efficiently.
+ * </p>
+ * <p>This Trie is not Threadsafe and contains no mutual exclusion 
+ * or deliberate memory barriers.  It is intended for an ArrayTrie to be
+ * built by a single thread and then used concurrently by multiple threads
+ * and not mutated during that access.  If concurrent mutations of the
+ * Trie is required external locks need to be applied.
  * </p>
  * @param <V>
  */
@@ -47,8 +63,8 @@ public class ArrayTrie<V> extends AbstractTrie<V>
     private static final int[] __lookup = 
     { // 0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
    /*0*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 
-   /*1*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 30, 
+   /*1*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 
-   /*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, -1, -1,
+   /*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, 30, -1,
    /*3*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 28, 29, -1, -1, -1, -1,
    /*4*/-1,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14,
    /*5*/15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, -1, -1, -1, -1, -1,
@@ -99,13 +115,22 @@ public class ArrayTrie<V> extends AbstractTrie<V>
         this(128);
     }
     
+    /* ------------------------------------------------------------ */
+    /**
+     * @param capacity  The capacity of the trie, which at the worst case
+     * is the total number of characters of all keys stored in the Trie.
+     * The capacity needed is dependent of the shared prefixes of the keys.
+     * For example, a capacity of 6 nodes is required to store keys "foo" 
+     * and "bar", but a capacity of only 4 is required to
+     * store "bar" and "bat".
+     */
     @SuppressWarnings("unchecked")
-    public ArrayTrie(int capacityInNodes)
+    public ArrayTrie(int capacity)
     {
         super(true);
-        _value=(V[])new Object[capacityInNodes];
+        _value=(V[])new Object[capacity];
-        _rowIndex=new char[capacityInNodes*32];
+        _rowIndex=new char[capacity*32];
-        _key=new String[capacityInNodes];
+        _key=new String[capacity];
     }
     
     

jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java

@@ -31,6 +31,15 @@ import java.util.Set;
  * <p>This implementation is always case insensitive and is optimal for
  * a variable number of fixed strings with few special characters.
  * </p>
+ * <p>This Trie is stored in a Tree and is unlimited in capacity</p>
+ * 
+ * <p>This Trie is not Threadsafe and contains no mutual exclusion 
+ * or deliberate memory barriers.  It is intended for an ArrayTrie to be
+ * built by a single thread and then used concurrently by multiple threads
+ * and not mutated during that access.  If concurrent mutations of the
+ * Trie is required external locks need to be applied.
+ * </p>
+ * 
  * @param <V>
  */
 public class TreeTrie<V> extends AbstractTrie<V>
@@ -38,8 +47,8 @@ public class TreeTrie<V> extends AbstractTrie<V>
     private static final int[] __lookup = 
     { // 0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
    /*0*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 
-   /*1*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 30, 
+   /*1*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 
-   /*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, -1, -1,
+   /*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, 30, -1,
    /*3*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 28, 29, -1, -1, -1, -1,
    /*4*/-1,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14,
    /*5*/15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, -1, -1, -1, -1, -1,