Package org.jesterj.ingest.trie

Class PatriciaTrie<E>

  • All Implemented Interfaces:
    java.io.Serializable, java.util.Map<java.lang.CharSequence,​E>, java.util.SortedMap<java.lang.CharSequence,​E>, org.apache.commons.collections4.Get<java.lang.CharSequence,​E>, org.apache.commons.collections4.IterableGet<java.lang.CharSequence,​E>, org.apache.commons.collections4.IterableMap<java.lang.CharSequence,​E>, org.apache.commons.collections4.IterableSortedMap<java.lang.CharSequence,​E>, org.apache.commons.collections4.OrderedMap<java.lang.CharSequence,​E>, org.apache.commons.collections4.Put<java.lang.CharSequence,​E>, org.apache.commons.collections4.Trie<java.lang.CharSequence,​E>
    public class PatriciaTrie<E>
extends AbstractBitwiseTrie<K,​V>
    Implementation of a PATRICIA Trie (Practical Algorithm to Retrieve Information Coded in Alphanumeric).

    A PATRICIA Trie is a compressed Trie. Instead of storing all data at the edges of the Trie (and having empty internal nodes), PATRICIA stores data in every node. This allows for very efficient traversal, insert, delete, predecessor, successor, prefix, range, and select(Object) operations. All operations are performed at worst in O(K) time, where K is the number of bits in the largest item in the tree. In practice, operations actually take O(A(K)) time, where A(K) is the average number of bits of all items in the tree.

    Most importantly, PATRICIA requires very few comparisons to keys while doing any operation. While performing a lookup, each comparison (at most K of them, described above) will perform a single bit comparison against the given key, instead of comparing the entire key to another key.

    The Trie can return operations in lexicographical order using the 'prefixMap', 'submap', or 'iterator' methods. The Trie can also scan for items that are 'bitwise' (using an XOR metric) by the 'select' method. Bitwise closeness is determined by the KeyAnalyzer returning true or false for a bit being set or not in a given key.

    This PATRICIA Trie supports both variable length & fixed length keys. Some methods, such as Trie.prefixMap(Object) are suited only to variable length keys.

    Since:
    4.0
    See Also:
    Radix Tree, PATRICIA, Crit-Bit Tree, Serialized Form

    • Nested Class Summary

      • Nested classes/interfaces inherited from class java.util.AbstractMap

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>

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

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected int modCount
      The number of times this Trie has been modified.

    • Constructor Summary

      Constructors 
      Constructor Description
      PatriciaTrie()  
      PatriciaTrie​(java.util.Map<? extends java.lang.CharSequence,​? extends E> m)  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()  
      java.util.Comparator<? super K> comparator()  
      boolean containsKey​(java.lang.Object k)  
      java.util.Set<java.util.Map.Entry<K,​V>> entrySet()  
      K firstKey()  
      V get​(java.lang.Object k)  
      java.util.SortedMap<K,​V> headMap​(K toKey)  
      java.util.Set<K> keySet()  
      K lastKey()  
      org.apache.commons.collections4.OrderedMapIterator<K,​V> mapIterator()  
      K nextKey​(K key)  
      java.util.SortedMap<K,​V> prefixMap​(K key)  
      K previousKey​(K key)  
      V put​(K key, V value)  
      V remove​(java.lang.Object k)
      java.util.Map.Entry<K,​V> select​(K key)
      Returns the Map.Entry whose key is closest in a bitwise XOR metric to the given key.
      K selectKey​(K key)
      Returns the key that is closest in a bitwise XOR metric to the provided key.
      V selectValue​(K key)
      Returns the value whose key is closest in a bitwise XOR metric to the provided key.
      int size()  
      java.util.SortedMap<K,​V> subMap​(K fromKey, K toKey)  
      java.util.SortedMap<K,​V> tailMap​(K fromKey)  
      java.util.Collection<V> values()  

      • Methods inherited from class java.util.AbstractMap

        clone, containsValue, equals, hashCode, isEmpty, putAll

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface org.apache.commons.collections4.Get

        containsValue, isEmpty

      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, containsValue, equals, forEach, getOrDefault, hashCode, isEmpty, merge, putAll, putIfAbsent, remove, replace, replace, replaceAll

      • Methods inherited from interface org.apache.commons.collections4.Put

        putAll

    • Field Detail

      • modCount

        protected transient int modCount
        The number of times this Trie has been modified. It's used to detect concurrent modifications and fail-fast the Iterators.

    • Constructor Detail

      • PatriciaTrie

        public PatriciaTrie()

      • PatriciaTrie

        public PatriciaTrie​(java.util.Map<? extends java.lang.CharSequence,​? extends E> m)

    • Method Detail

      • clear

        public void clear()
        Specified by:
        clear in interface java.util.Map<K,​V>
        Specified by:
        clear in interface org.apache.commons.collections4.Put<K,​V>
        Overrides:
        clear in class java.util.AbstractMap<K,​V>

      • size

        public int size()
        Specified by:
        size in interface org.apache.commons.collections4.Get<K,​V>
        Specified by:
        size in interface java.util.Map<K,​V>
        Overrides:
        size in class java.util.AbstractMap<K,​V>

      • put

        public V put​(K key,
             V value)
        Specified by:
        put in interface java.util.Map<K,​V>
        Specified by:
        put in interface org.apache.commons.collections4.Put<K,​V>
        Overrides:
        put in class java.util.AbstractMap<K,​V>

      • get

        public V get​(java.lang.Object k)
        Specified by:
        get in interface org.apache.commons.collections4.Get<K,​V>
        Specified by:
        get in interface java.util.Map<K,​V>
        Overrides:
        get in class java.util.AbstractMap<K,​V>

      • select

        public java.util.Map.Entry<K,​V> select​(K key)
        Returns the Map.Entry whose key is closest in a bitwise XOR metric to the given key. This is NOT lexicographic closeness. For example, given the keys:
        1. D = 1000100
        2. H = 1001000
        3. 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.
        Parameters:
        key - the key to use in the search
        Returns:
        the Map.Entry whose key is closest in a bitwise XOR metric to the provided key

      • selectKey

        public K selectKey​(K key)
        Returns the key that is closest in a bitwise XOR metric to the provided key. This is NOT lexicographic closeness! For example, given the keys:
        1. D = 1000100
        2. H = 1001000
        3. 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.
        Parameters:
        key - the key to use in the search
        Returns:
        the key that is closest in a bitwise XOR metric to the provided key

      • selectValue

        public V selectValue​(K key)
        Returns the value whose key is closest in a bitwise XOR metric to the provided key. This is NOT lexicographic closeness! For example, given the keys:
        1. D = 1000100
        2. H = 1001000
        3. 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.
        Parameters:
        key - the key to use in the search
        Returns:
        the value whose key is closest in a bitwise XOR metric to the provided key

      • containsKey

        public boolean containsKey​(java.lang.Object k)
        Specified by:
        containsKey in interface org.apache.commons.collections4.Get<K,​V>
        Specified by:
        containsKey in interface java.util.Map<K,​V>
        Overrides:
        containsKey in class java.util.AbstractMap<K,​V>

      • entrySet

        public java.util.Set<java.util.Map.Entry<K,​V>> entrySet()
        Specified by:
        entrySet in interface org.apache.commons.collections4.Get<K,​V>
        Specified by:
        entrySet in interface java.util.Map<K,​V>
        Specified by:
        entrySet in interface java.util.SortedMap<K,​V>
        Specified by:
        entrySet in class java.util.AbstractMap<K,​V>

      • keySet

        public java.util.Set<K> keySet()
        Specified by:
        keySet in interface org.apache.commons.collections4.Get<K,​V>
        Specified by:
        keySet in interface java.util.Map<K,​V>
        Specified by:
        keySet in interface java.util.SortedMap<K,​V>
        Overrides:
        keySet in class java.util.AbstractMap<K,​V>

      • values

        public java.util.Collection<V> values()
        Specified by:
        values in interface org.apache.commons.collections4.Get<K,​V>
        Specified by:
        values in interface java.util.Map<K,​V>
        Specified by:
        values in interface java.util.SortedMap<K,​V>
        Overrides:
        values in class java.util.AbstractMap<K,​V>

      • remove

        public V remove​(java.lang.Object k)
        Specified by:
        remove in interface org.apache.commons.collections4.Get<K,​V>
        Specified by:
        remove in interface java.util.Map<K,​V>
        Overrides:
        remove in class java.util.AbstractMap<K,​V>
        Throws:
        java.lang.ClassCastException - if provided key is of an incompatible type

      • comparator

        public java.util.Comparator<? super K> comparator()

      • firstKey

        public K firstKey()

      • lastKey

        public K lastKey()

      • nextKey

        public K nextKey​(K key)

      • previousKey

        public K previousKey​(K key)

      • mapIterator

        public org.apache.commons.collections4.OrderedMapIterator<K,​V> mapIterator()

      • prefixMap

        public java.util.SortedMap<K,​V> prefixMap​(K key)

      • headMap

        public java.util.SortedMap<K,​V> headMap​(K toKey)

      • subMap

        public java.util.SortedMap<K,​V> subMap​(K fromKey,
                                             K toKey)

      • tailMap

        public java.util.SortedMap<K,​V> tailMap​(K fromKey)