com.fasterxml.jackson.core.sym
Class BytesToNameCanonicalizer

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

public final class BytesToNameCanonicalizer
extends Object

This class is basically a caching symbol table implementation used for canonicalizing Names, constructed directly from a byte-based input source.

Author:

Tatu Saloranta

Field Summary

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 BytesToNameCanonicalizer	_parent
protected static int	DEFAULT_TABLE_SIZE
protected static int	MAX_TABLE_SIZE Let's not expand symbol tables past some maximum size; this should protected against OOMEs caused by large documents with unique (~= random) names.

Method Summary

Name	addName(String symbolStr, int[] quads, int qlen)
Name	addName(String symbolStr, int q1, int q2)
int	bucketCount()
int	calcHash(int firstQuad)
int	calcHash(int[] quads, int qlen)
int	calcHash(int firstQuad, int secondQuad)
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 hashSeed) Factory method that should only be called from unit tests, where seed value should remain the same.
Name	findName(int firstQuad) Finds and returns name matching the specified symbol, if such name already exists in the table.
Name	findName(int[] quads, 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 firstQuad, int secondQuad) 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)
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

DEFAULT_TABLE_SIZE

protected static final int DEFAULT_TABLE_SIZE

See Also:

Constant Field Values

MAX_TABLE_SIZE

protected static final int MAX_TABLE_SIZE

Let's not expand symbol tables past some maximum size; this should protected against OOMEs caused by large documents with unique (~= random) names.

See Also:

Constant Field Values

_parent

protected final BytesToNameCanonicalizer _parent

_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

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 hashSeed)

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

makeChild

public BytesToNameCanonicalizer makeChild(boolean canonicalize,
                                          boolean intern)

Parameters:

intern - Whether canonical symbol Strings should be interned or not

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 firstQuad)

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:

firstQuad - 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 firstQuad,
                     int secondQuad)

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:

firstQuad - int32 containing first 4 bytes of the name.

secondQuad - 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[] quads,
                     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:

quads - 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 symbolStr,
                    int q1,
                    int q2)

addName

public Name addName(String symbolStr,
                    int[] quads,
                    int qlen)

calcHash

public final int calcHash(int firstQuad)

calcHash

public final int calcHash(int firstQuad,
                          int secondQuad)

calcHash

public final int calcHash(int[] quads,
                          int qlen)

calcQuads

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

reportTooManyCollisions

protected void reportTooManyCollisions(int maxLen)

Since:

2.1