net.sf.eos.trie
Interface Trie<K,V>

All Superinterfaces:

Map<K,V>, SortedMap<K,V>

All Known Implementing Classes:

PatriciaTrie

public interface Trie<K,V>
extends SortedMap<K,V>

Defines the interface for a prefix tree, an ordered tree data structure. For more information, see Tries.

Note: Taken from Limewire sourcecode and repackaged by Sascha Kohlmann.

Author:

Roger Kapsi, Sam Berlin

Nested Class Summary

static interface

Trie.Cursor<K,V> An interface used by a Trie.

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

SortedMap<K,V>	getPrefixedBy(K key) Returns a view of this Trie of all elements that are prefixed by the given key.
SortedMap<K,V>	getPrefixedBy(K key, int length) Returns a view of this Trie of all elements that are prefixed by the length of the key.
SortedMap<K,V>	getPrefixedBy(K key, int offset, int length) Returns a view of this Trie of all elements that are prefixed by the key, starting at the given offset and for the given length.
SortedMap<K,V>	getPrefixedByBits(K key, int bitLength) Returns a view of this Trie of all elements that are prefixed by the number of bits in the given Key.
V	select(K key) Returns the value for the entry whose key is closest in a bitwise XOR metric to the given key.
Map.Entry<K,V>	select(K key, Trie.Cursor<? super K,? super V> cursor) Iterates through the Trie, starting with the entry whose bitwise value is closest in an XOR metric to the given key.
Map.Entry<K,V>	traverse(Trie.Cursor<? super K,? super V> cursor) Traverses the Trie in lexicographical order.

Methods inherited from interface java.util.SortedMap

comparator, firstKey, headMap, lastKey, subMap, tailMap

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

getPrefixedBy

SortedMap<K,V> getPrefixedBy(K key)

Returns a view of this Trie of all elements that are prefixed by the given key.

In a fixed-keysize Trie, this is essentially a 'get' operation.

For example, if the Trie contains 'Lime', 'LimeWire', 'LimeRadio', 'Lax', 'Later', 'Lake', and 'Lovely', then a lookup of 'Lime' would return 'Lime', 'LimeRadio', and 'LimeWire'.

getPrefixedBy

SortedMap<K,V> getPrefixedBy(K key,
                             int length)

Returns a view of this Trie of all elements that are prefixed by the length of the key.

Fixed-keysize Tries will not support this operation (because all keys will be the same length).

For example, if the Trie contains 'Lime', 'LimeWire', 'LimeRadio', 'Lax', 'Later', 'Lake', and 'Lovely', then a lookup of 'LimePlastics' with a length of 4 would return 'Lime', 'LimeRadio', and 'LimeWire'.

getPrefixedBy

SortedMap<K,V> getPrefixedBy(K key,
                             int offset,
                             int length)

Returns a view of this Trie of all elements that are prefixed by the key, starting at the given offset and for the given length.

Fixed-keysize Tries will not support this operation (because all keys are the same length).

For example, if the Trie contains 'Lime', 'LimeWire', 'LimeRadio', 'Lax', 'Later', 'Lake', and 'Lovely', then a lookup of 'The Lime Plastics' with an offset of 4 and a length of 4 would return 'Lime', 'LimeRadio', and 'LimeWire'.

getPrefixedByBits

SortedMap<K,V> getPrefixedByBits(K key,
                                 int bitLength)

Returns a view of this Trie of all elements that are prefixed by the number of bits in the given Key.

Fixed-keysize Tries can support this operation as a way to do lookups of partial keys. That is, if the Trie is storing IP addresses, you can lookup all addresses that begin with '192.168' by providing the key '192.168.X.X' and a length of 16 would return all addresses that begin with '192.168'.

select

V select(K key)

Returns the value for the entry whose key is closest in a bitwise XOR metric to the given key. This is NOT lexicographic closeness. For example, given the keys:
D = 1000100
H = 1001000
L = 1001100

If the Trie contained 'H' and 'L', a lookup of 'D' would return 'L', because the XOR distance between D & L is smaller than the XOR distance between D & H.

select

Map.Entry<K,V> select(K key,
                      Trie.Cursor<? super K,? super V> cursor)

Iterates through the Trie, starting with the entry whose bitwise value is closest in an XOR metric to the given key. After the closest entry is found, the Trie will call select on that entry and continue calling select for each entry (traversing in order of XOR closeness, NOT lexicographically) until the cursor returns Cursor.SelectStatus.EXIT.
The cursor can return Cursor.SelectStatus.CONTINUE to continue traversing.
Cursor.SelectStatus.REMOVE_AND_EXIT is used to remove the current element and stop traversing.

Note: The Trie.Cursor.SelectStatus.REMOVE operation is not supported.

Returns:

The entry the cursor returned EXIT on, or null if it continued till the end.

traverse

Map.Entry<K,V> traverse(Trie.Cursor<? super K,? super V> cursor)

Traverses the Trie in lexicographical order. Cursor.select will be called on each entry.

The traversal will stop when the cursor returns Cursor.SelectStatus.EXIT.
Cursor.SelectStatus.CONTINUE is used to continue traversing.
Cursor.SelectStatus.REMOVE is used to remove the element that was selected and continue traversing.
Cursor.SelectStatus.REMOVE_AND_EXIT is used to remove the current element and stop traversing.

Returns:

The entry the cursor returned EXIT on, or null if it continued till the end.