com.fasterxml.jackson.core.sym

## Class BytesToNameCanonicalizer

- java.lang.Object
- - com.fasterxml.jackson.core.sym.BytesToNameCanonicalizer

-     public final class BytesToNameCanonicalizer
      extends Object

  A caching symbol table implementation used for canonicalizing JSON field names (as `Name`s which are constructed directly from a byte-based input source). Complications arise from trying to do efficient reuse and merging of symbol tables, to be able to make use of usually shared vocabulary of subsequent parsing runs.
  Author:
    Tatu Saloranta

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `_collCount` Total number of Names in collision buckets (included in `_count` along with primary entries)
    `protected int` | `_collEnd` Index of the first unused collision bucket entry (== size of the used portion of collision list): less than or equal to 0xFF (255), since max number of entries is 255 (8-bit, minus 0 used as 'empty' marker)
    `protected com.fasterxml.jackson.core.sym.BytesToNameCanonicalizer.Bucket[]` | `_collList` Array of heads of collision bucket chains; size dynamically
    `protected int` | `_count` Total number of Names in the symbol table; only used for child tables.
    `protected boolean` | `_failOnDoS` Flag that indicates whether we should throw an exception if enough hash collisions are detected (true); or just worked around (false).
    `protected int[]` | `_hash` Array of 2^N size, which contains combination of 24-bits of hash (0 to indicate 'empty' slot), and 8-bit collision bucket index (0 to indicate empty collision bucket chain; otherwise subtract one from index)
    `protected int` | `_hashMask` Mask used to truncate 32-bit hash value to current hash array size; essentially, hash array size - 1 (since hash array sizes are 2^N).
    `protected boolean` | `_intern` Whether canonical symbol Strings are to be intern()ed before added to the table or not.
    `protected int` | `_longestCollisionList` We need to keep track of the longest collision list; this is needed both to indicate problems with attacks and to allow flushing for other cases.
    `protected Name[]` | `_mainNames` Array that contains `Name` instances matching entries in `_mainHash`.
    `protected BitSet` | `_overflows` Lazily constructed structure that is used to keep track of collision buckets that have overflowed once: this is used to detect likely attempts at denial-of-service attacks that uses hash collisions.
    `protected BytesToNameCanonicalizer` | `_parent` Reference to the root symbol table, for child tables, so that they can merge table information back as necessary.
    `protected AtomicReference<com.fasterxml.jackson.core.sym.BytesToNameCanonicalizer.TableInfo>` | `_tableInfo` Member that is only used by the root table instance: root passes immutable state into child instances, and children may return new state if they add entries to the table.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Name` | `addName(String name, int[] q, int qlen)`
    `Name` | `addName(String name, int q1, int q2)`
    `int` | `bucketCount()`
    `int` | `calcHash(int q1)`
    `int` | `calcHash(int[] q, int qlen)`
    `int` | `calcHash(int q1, int q2)`
    `protected static int[]` | `calcQuads(byte[] wordBytes)`
    `int` | `collisionCount()` Method mostly needed by unit tests; calculates number of entries that are in collision list.
    `static BytesToNameCanonicalizer` | `createRoot()` Factory method to call to create a symbol table instance with a randomized seed value.
    `protected static BytesToNameCanonicalizer` | `createRoot(int seed)` Factory method that should only be called from unit tests, where seed value should remain the same.
    `Name` | `findName(int q1)` Finds and returns name matching the specified symbol, if such name already exists in the table.
    `Name` | `findName(int[] q, int qlen)` Finds and returns name matching the specified symbol, if such name already exists in the table; or if not, creates name object, adds to the table, and returns it.
    `Name` | `findName(int q1, int q2)` Finds and returns name matching the specified symbol, if such name already exists in the table.
    `static Name` | `getEmptyName()`
    `int` | `hashSeed()`
    `BytesToNameCanonicalizer` | `makeChild(boolean canonicalize, boolean intern)` Deprecated.
    `BytesToNameCanonicalizer` | `makeChild(int flags)` Factory method used to create actual symbol table instance to use for parsing.
    `int` | `maxCollisionLength()` Method mostly needed by unit tests; calculates length of the longest collision chain.
    `boolean` | `maybeDirty()` Method called to check to quickly see if a child symbol table may have gotten additional entries.
    `void` | `release()` Method called by the using code to indicate it is done with this instance.
    `protected void` | `reportTooManyCollisions(int maxLen)`
    `int` | `size()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### _parent

          protected final BytesToNameCanonicalizer _parent

      Reference to the root symbol table, for child tables, so that they can merge table information back as necessary.

    - #### _tableInfo

          protected final AtomicReference<com.fasterxml.jackson.core.sym.BytesToNameCanonicalizer.TableInfo> _tableInfo

      Member that is only used by the root table instance: root passes immutable state into child instances, and children may return new state if they add entries to the table. Child tables do NOT use the reference.

    - #### _intern

          protected boolean _intern

      Whether canonical symbol Strings are to be intern()ed before added to the table or not.

      NOTE: non-final to allow disabling intern()ing in case of excessive collisions.

    - #### _failOnDoS

          protected final boolean _failOnDoS

      Flag that indicates whether we should throw an exception if enough hash collisions are detected (true); or just worked around (false).
      Since:
        2.4

    - #### _count

          protected int _count

      Total number of Names in the symbol table; only used for child tables.

    - #### _longestCollisionList

          protected int _longestCollisionList

      We need to keep track of the longest collision list; this is needed both to indicate problems with attacks and to allow flushing for other cases.
      Since:
        2.1

    - #### _hashMask

          protected int _hashMask

      Mask used to truncate 32-bit hash value to current hash array size; essentially, hash array size - 1 (since hash array sizes are 2^N).

    - #### _hash

          protected int[] _hash

      Array of 2^N size, which contains combination of 24-bits of hash (0 to indicate 'empty' slot), and 8-bit collision bucket index (0 to indicate empty collision bucket chain; otherwise subtract one from index)

    - #### _mainNames

          protected Name[] _mainNames

      Array that contains `Name` instances matching entries in `_mainHash`. Contains nulls for unused entries.

    - #### _collList

          protected com.fasterxml.jackson.core.sym.BytesToNameCanonicalizer.Bucket[] _collList

      Array of heads of collision bucket chains; size dynamically

    - #### _collCount

          protected int _collCount

      Total number of Names in collision buckets (included in `_count` along with primary entries)

    - #### _collEnd

          protected int _collEnd

      Index of the first unused collision bucket entry (== size of the used portion of collision list): less than or equal to 0xFF (255), since max number of entries is 255 (8-bit, minus 0 used as 'empty' marker)

    - #### _overflows

          protected BitSet _overflows

      Lazily constructed structure that is used to keep track of collision buckets that have overflowed once: this is used to detect likely attempts at denial-of-service attacks that uses hash collisions.
      Since:
        2.4

  - ### Method Detail

    - #### createRoot

          public static BytesToNameCanonicalizer createRoot()

      Factory method to call to create a symbol table instance with a randomized seed value.

    - #### createRoot

          protected static BytesToNameCanonicalizer createRoot(int seed)

      Factory method that should only be called from unit tests, where seed value should remain the same.

    - #### makeChild

          public BytesToNameCanonicalizer makeChild(int flags)

      Factory method used to create actual symbol table instance to use for parsing.

    - #### makeChild

          @Deprecated
          public BytesToNameCanonicalizer makeChild(boolean canonicalize,
                                                      boolean intern)

      Deprecated.

    - #### release

          public void release()

      Method called by the using code to indicate it is done with this instance. This lets instance merge accumulated changes into parent (if need be), safely and efficiently, and without calling code having to know about parent information

    - #### size

          public int size()

    - #### bucketCount

          public int bucketCount()

      Since:
        2.1

    - #### maybeDirty

          public boolean maybeDirty()

      Method called to check to quickly see if a child symbol table may have gotten additional entries. Used for checking to see if a child table should be merged into shared table.

    - #### hashSeed

          public int hashSeed()

      Since:
        2.1

    - #### collisionCount

          public int collisionCount()

      Method mostly needed by unit tests; calculates number of entries that are in collision list. Value can be at most (`size()` - 1), but should usually be much lower, ideally 0.
      Since:
        2.1

    - #### maxCollisionLength

          public int maxCollisionLength()

      Method mostly needed by unit tests; calculates length of the longest collision chain. This should typically be a low number, but may be up to `size()` - 1 in the pathological case
      Since:
        2.1

    - #### getEmptyName

          public static Name getEmptyName()

    - #### findName

          public Name findName(int q1)

      Finds and returns name matching the specified symbol, if such name already exists in the table. If not, will return null.

      Note: separate methods to optimize common case of short element/attribute names (4 or less ascii characters)

      Parameters:
        `q1` - int32 containing first 4 bytes of the name; if the whole name less than 4 bytes, padded with zero bytes in front (zero MSBs, ie. right aligned)
      Returns:
        Name matching the symbol passed (or constructed for it)

    - #### findName

          public Name findName(int q1,
                      int q2)

      Finds and returns name matching the specified symbol, if such name already exists in the table. If not, will return null.

      Note: separate methods to optimize common case of relatively short element/attribute names (8 or less ascii characters)

      Parameters:
        `q1` - int32 containing first 4 bytes of the name.
        `q2` - int32 containing bytes 5 through 8 of the name; if less than 8 bytes, padded with up to 3 zero bytes in front (zero MSBs, ie. right aligned)
      Returns:
        Name matching the symbol passed (or constructed for it)

    - #### findName

          public Name findName(int[] q,
                      int qlen)

      Finds and returns name matching the specified symbol, if such name already exists in the table; or if not, creates name object, adds to the table, and returns it.

      Note: this is the general purpose method that can be called for names of any length. However, if name is less than 9 bytes long, it is preferable to call the version optimized for short names.

      Parameters:
        `q` - Array of int32s, each of which contain 4 bytes of encoded name
        `qlen` - Number of int32s, starting from index 0, in quads parameter
      Returns:
        Name matching the symbol passed (or constructed for it)

    - #### addName

          public Name addName(String name,
                     int q1,
                     int q2)

    - #### addName

          public Name addName(String name,
                     int[] q,
                     int qlen)

    - #### calcHash

          public int calcHash(int q1)

    - #### calcHash

          public int calcHash(int q1,
                     int q2)

    - #### calcHash

          public int calcHash(int[] q,
                     int qlen)

    - #### calcQuads

          protected static int[] calcQuads(byte[] wordBytes)

    - #### reportTooManyCollisions

          protected void reportTooManyCollisions(int maxLen)

      Since:
        2.1

Copyright © 2014-2015 FasterXML. All Rights Reserved.