diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java index 2cd345ae6de..0c5427e499e 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java +++ b/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. +/** + *

A Ternary Trie String lookup data structure.

* 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). *

* The Trie is stored in 3 arrays:

@@ -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. *
V[] _value
An array of values corresponding to the _key array
*
+ *

*

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. *

+ *

+ * This Trie may be instantiated either as case sensitive or insensitive. + *

+ *

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. + *

+ * * @param */ public class ArrayTernaryTrie extends AbstractTrie @@ -78,27 +90,53 @@ public class ArrayTernaryTrie extends AbstractTrie */ 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]; - _tree=new char[capacityInNodes*ROW_SIZE]; - _key=new String[capacityInNodes]; + _value=(V[])new Object[capacity]; + _tree=new char[capacity*ROW_SIZE]; + _key=new String[capacity]; } /* ------------------------------------------------------------ */ diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java index c65cb57e08e..a2ed3b577dd 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java +++ b/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. +/** + *

A Trie String lookup data structure using a fixed size array.

*

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. + *

+ *

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. + *

+ *

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. *

* @param */ @@ -47,8 +63,8 @@ public class ArrayTrie extends AbstractTrie 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, - /*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, -1, -1, + /*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, 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 extends AbstractTrie 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]; - _rowIndex=new char[capacityInNodes*32]; - _key=new String[capacityInNodes]; + _value=(V[])new Object[capacity]; + _rowIndex=new char[capacity*32]; + _key=new String[capacity]; } diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java b/jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java index 42f3bdccadd..862ce517fff 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java @@ -31,6 +31,15 @@ import java.util.Set; *

This implementation is always case insensitive and is optimal for * a variable number of fixed strings with few special characters. *

+ *

This Trie is stored in a Tree and is unlimited in capacity

+ * + *

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. + *

+ * * @param */ public class TreeTrie extends AbstractTrie @@ -38,8 +47,8 @@ public class TreeTrie extends AbstractTrie 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, - /*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, -1, -1, + /*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, 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,