|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.fasterxml.jackson.core.sym.CharsToNameCanonicalizer
public final class CharsToNameCanonicalizer
This class is a kind of specialized type-safe Map, from char array to String value. Specialization means that in addition to type-safety and specific access patterns (key char array, Value optionally interned String; values added on access if necessary), and that instances are meant to be used concurrently, but by using well-defined mechanisms to obtain such concurrently usable instances. Main use for the class is to store symbol table information for things like compilers and parsers; especially when number of symbols (keywords) is limited.
For optimal performance, usage pattern should be one where matches
should be very common (esp. after "warm-up"), and as with most hash-based
maps/sets, that hash codes are uniformly distributed. Also, collisions
are slightly more expensive than with HashMap or HashSet, since hash codes
are not used in resolving collisions; that is, equals() comparison is
done with all symbols in same bucket index.
Finally, rehashing is also more expensive, as hash codes are not
stored; rehashing requires all entries' hash codes to be recalculated.
Reason for not storing hash codes is reduced memory usage, hoping
for better memory locality.
Usual usage pattern is to create a single "master" instance, and either use that instance in sequential fashion, or to create derived "child" instances, which after use, are asked to return possible symbol additions to master instance. In either case benefit is that symbol table gets initialized so that further uses are more efficient, as eventually all symbols needed will already be in symbol table. At that point no more Symbol String allocations are needed, nor changes to symbol table itself.
Note that while individual SymbolTable instances are NOT thread-safe (much like generic collection classes), concurrently used "child" instances can be freely used without synchronization. However, using master table concurrently with child instances can only be done if access to master instance is read-only (ie. no modifications done).
Field Summary | |
---|---|
protected com.fasterxml.jackson.core.sym.CharsToNameCanonicalizer.Bucket[] |
_buckets
Overflow buckets; if primary doesn't match, lookup is done from here. |
protected boolean |
_canonicalize
Whether any canonicalization should be attempted (whether using intern or not) |
protected boolean |
_dirty
Flag that indicates if any changes have been made to the data; used to both determine if bucket array needs to be copied when (first) change is made, and potentially if updated bucket list is to be resync'ed back to master instance. |
protected int |
_indexMask
Mask used to get index from hash values; equal to _buckets.length - 1 , when _buckets.length is
a power of two. |
protected boolean |
_intern
Whether canonical symbol Strings are to be intern()ed before added to the table or not |
protected CharsToNameCanonicalizer |
_parent
Sharing of learnt symbols is done by optional linking of symbol table instances with their parents. |
protected int |
_size
Current size (number of entries); needed to know if and when rehash. |
protected int |
_sizeThreshold
Limit that indicates maximum size this instance can hold before it needs to be expanded and rehashed. |
protected String[] |
_symbols
Primary matching symbols; it's expected most match occur from here. |
protected static int |
DEFAULT_TABLE_SIZE
Default initial 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 uniquer (~= random) names. |
Method Summary | |
---|---|
static int |
calcHash(char[] buffer,
int start,
int len)
Implementation of a hashing method for variable length Strings. |
static int |
calcHash(String key)
|
static CharsToNameCanonicalizer |
createRoot()
Method called to create root canonicalizer for a JsonFactory
instance. |
String |
findSymbol(char[] buffer,
int start,
int len,
int hash)
|
CharsToNameCanonicalizer |
makeChild(boolean canonicalize,
boolean intern)
"Factory" method; will create a new child instance of this symbol table. |
boolean |
maybeDirty()
|
void |
release()
|
int |
size()
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected static final int DEFAULT_TABLE_SIZE
protected static final int MAX_TABLE_SIZE
protected CharsToNameCanonicalizer _parent
release
),
parent's shared tables may be updated from the child instance.
protected final boolean _intern
protected final boolean _canonicalize
protected String[] _symbols
protected com.fasterxml.jackson.core.sym.CharsToNameCanonicalizer.Bucket[] _buckets
Note: Number of buckets is half of number of symbol entries, on assumption there's less need for buckets.
protected int _size
protected int _sizeThreshold
protected int _indexMask
_buckets.length - 1
, when _buckets.length is
a power of two.
protected boolean _dirty
Method Detail |
---|
public static CharsToNameCanonicalizer createRoot()
JsonFactory
instance. Root instance is never used directly; its main use is for
storing and sharing underlying symbol arrays as needed.
public CharsToNameCanonicalizer makeChild(boolean canonicalize, boolean intern)
Note: while this method is synchronized, it is generally not safe to both use makeChild/mergeChild, AND to use instance actively. Instead, a separate 'root' instance should be used on which only makeChild/mergeChild are called, but instance itself is not used as a symbol table.
public void release()
public int size()
public boolean maybeDirty()
public String findSymbol(char[] buffer, int start, int len, int hash)
public static int calcHash(char[] buffer, int start, int len)
len
- Length of String; has to be at least 1 (caller guarantees
this pre-condition)public static int calcHash(String key)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |