public class JsonFactory extends Object implements Versioned
JsonParser
)
and writer (aka generator, JsonGenerator
)
instances.
Factory instances are thread-safe and reusable after configuration (if any). Typically applications and services use only a single globally shared factory instance, unless they need differently configured factories. Factory reuse is important if efficiency matters; most recycling of expensive construct is done on per-factory basis.
Creation of a factory instance is a light-weight operation, and since there is no need for pluggable alternative implementations (as there is no "standard" JSON processor API to implement), the default constructor is used for constructing factory instances.
Modifier and Type | Field and Description |
---|---|
protected CharacterEscapes |
_characterEscapes
Definition of custom character escapes to use for generators created
by this factory, if any.
|
protected int |
_generatorFeatures
Currently enabled generator features.
|
protected InputDecorator |
_inputDecorator
Optional helper object that may decorate input sources, to do
additional processing on input during parsing.
|
protected ObjectCodec |
_objectCodec
Object that implements conversion functionality between
Java objects and JSON content.
|
protected OutputDecorator |
_outputDecorator
Optional helper object that may decorate output object, to do
additional processing on output during content generation.
|
protected int |
_parserFeatures
Currently enabled parser features.
|
protected static ThreadLocal<SoftReference<BufferRecycler>> |
_recyclerRef
This
ThreadLocal contains a SoftReference
to a BufferRecycler used to provide a low-cost
buffer recycling between reader and writer instances. |
protected BytesToNameCanonicalizer |
_rootByteSymbols
Alternative to the basic symbol table, some stream-based
parsers use different name canonicalization method.
|
protected CharsToNameCanonicalizer |
_rootCharSymbols
Each factory comes equipped with a shared root symbol table.
|
static String |
FORMAT_NAME_JSON
Name used to identify JSON format
(and returned by
getFormatName() |
Constructor and Description |
---|
JsonFactory()
Default constructor used to create factory instances.
|
JsonFactory(ObjectCodec oc) |
Modifier and Type | Method and Description |
---|---|
protected IOContext |
_createContext(Object srcRef,
boolean resourceManaged)
Overridable factory method that actually instantiates desired
context object.
|
protected JsonGenerator |
_createJsonGenerator(Writer out,
IOContext ctxt)
Overridable factory method that actually instantiates generator for
given
Writer and context object. |
protected JsonParser |
_createJsonParser(byte[] data,
int offset,
int len,
IOContext ctxt)
Overridable factory method that actually instantiates parser
using given
Reader object for reading content
passed as raw byte array. |
protected JsonParser |
_createJsonParser(InputStream in,
IOContext ctxt)
Overridable factory method that actually instantiates desired parser
given
InputStream and context object. |
protected JsonParser |
_createJsonParser(Reader r,
IOContext ctxt)
Overridable factory method that actually instantiates parser
using given
Reader object for reading content. |
protected JsonGenerator |
_createUTF8JsonGenerator(OutputStream out,
IOContext ctxt)
Overridable factory method that actually instantiates generator for
given
OutputStream and context object, using UTF-8 encoding. |
protected Writer |
_createWriter(OutputStream out,
JsonEncoding enc,
IOContext ctxt) |
BufferRecycler |
_getBufferRecycler()
Method used by factory to create buffer recycler instances
for parsers and generators.
|
protected InputStream |
_optimizedStreamFromURL(URL url)
Helper methods used for constructing an optimal stream for
parsers to use, when input is to be read from an URL.
|
JsonFactory |
configure(JsonGenerator.Feature f,
boolean state)
Method for enabling or disabling specified generator feature
(check
JsonGenerator.Feature for list of features) |
JsonFactory |
configure(JsonParser.Feature f,
boolean state)
Method for enabling or disabling specified parser feature
(check
JsonParser.Feature for list of features) |
JsonGenerator |
createJsonGenerator(File f,
JsonEncoding enc)
Method for constructing JSON generator for writing JSON content
to specified file, overwriting contents it might have (or creating
it if such file does not yet exist).
|
JsonGenerator |
createJsonGenerator(OutputStream out)
Convenience method for constructing generator that uses default
encoding of the format (UTF-8 for JSON and most other data formats).
|
JsonGenerator |
createJsonGenerator(OutputStream out,
JsonEncoding enc)
Method for constructing JSON generator for writing JSON content
using specified output stream.
|
JsonGenerator |
createJsonGenerator(Writer out)
Method for constructing JSON generator for writing JSON content
using specified Writer.
|
JsonParser |
createJsonParser(byte[] data)
Method for constructing parser for parsing
the contents of given byte array.
|
JsonParser |
createJsonParser(byte[] data,
int offset,
int len)
Method for constructing parser for parsing
the contents of given byte array.
|
JsonParser |
createJsonParser(File f)
Method for constructing JSON parser instance to parse
contents of specified file.
|
JsonParser |
createJsonParser(InputStream in)
Method for constructing JSON parser instance to parse
the contents accessed via specified input stream.
|
JsonParser |
createJsonParser(Reader r)
Method for constructing parser for parsing
the contents accessed via specified Reader.
|
JsonParser |
createJsonParser(String content)
Method for constructing parser for parsing
contens of given String.
|
JsonParser |
createJsonParser(URL url)
Method for constructing JSON parser instance to parse
contents of resource reference by given URL.
|
JsonFactory |
disable(JsonGenerator.Feature f)
Method for disabling specified generator feature
(check
JsonGenerator.Feature for list of features) |
JsonFactory |
disable(JsonParser.Feature f)
Method for disabling specified parser features
(check
JsonParser.Feature for list of features) |
void |
disableGeneratorFeature(JsonGenerator.Feature f)
Deprecated.
Use
disable(JsonGenerator.Feature) instead |
void |
disableParserFeature(JsonParser.Feature f)
Deprecated.
Use
disable(JsonParser.Feature) instead |
JsonFactory |
enable(JsonGenerator.Feature f)
Method for enabling specified generator features
(check
JsonGenerator.Feature for list of features) |
JsonFactory |
enable(JsonParser.Feature f)
Method for enabling specified parser feature
(check
JsonParser.Feature for list of features) |
void |
enableGeneratorFeature(JsonGenerator.Feature f)
Deprecated.
Use
enable(JsonGenerator.Feature) instead |
void |
enableParserFeature(JsonParser.Feature f)
Deprecated.
Use
enable(JsonParser.Feature) instead |
CharacterEscapes |
getCharacterEscapes()
Method for accessing custom escapes factory uses for
JsonGenerator s
it creates. |
ObjectCodec |
getCodec() |
String |
getFormatName()
Method that returns short textual id identifying format
this factory supports.
|
InputDecorator |
getInputDecorator()
Method for getting currently configured input decorator (if any;
there is no default decorator).
|
OutputDecorator |
getOutputDecorator()
Method for getting currently configured output decorator (if any;
there is no default decorator).
|
MatchStrength |
hasFormat(InputAccessor acc) |
protected MatchStrength |
hasJSONFormat(InputAccessor acc) |
boolean |
isEnabled(JsonGenerator.Feature f)
Check whether specified generator feature is enabled.
|
boolean |
isEnabled(JsonParser.Feature f)
Checked whether specified parser feature is enabled.
|
boolean |
isGeneratorFeatureEnabled(JsonGenerator.Feature f)
Deprecated.
Use
isEnabled(JsonGenerator.Feature) instead |
boolean |
isParserFeatureEnabled(JsonParser.Feature f)
Deprecated.
Use
isEnabled(JsonParser.Feature) instead |
JsonFactory |
setCharacterEscapes(CharacterEscapes esc)
Method for defining custom escapes factory uses for
JsonGenerator s
it creates. |
JsonFactory |
setCodec(ObjectCodec oc)
Method for associating a
ObjectCodec (typically
a ObjectMapper ) with
this factory (and more importantly, parsers and generators
it constructs). |
void |
setGeneratorFeature(JsonGenerator.Feature f,
boolean state)
Deprecated.
Use
configure(JsonGenerator.Feature, boolean) instead |
JsonFactory |
setInputDecorator(InputDecorator d)
Method for overriding currently configured input decorator
|
JsonFactory |
setOutputDecorator(OutputDecorator d)
Method for overriding currently configured output decorator
|
void |
setParserFeature(JsonParser.Feature f,
boolean state)
Deprecated.
Use
configure(JsonParser.Feature, boolean) instead |
Version |
version()
Method called to detect version of the component that implements this interface;
returned version should never be null, but may return specific "not available"
instance (see
Version for details). |
public static final String FORMAT_NAME_JSON
getFormatName()
protected static final ThreadLocal<SoftReference<BufferRecycler>> _recyclerRef
ThreadLocal
contains a SoftReference
to a BufferRecycler
used to provide a low-cost
buffer recycling between reader and writer instances.protected CharsToNameCanonicalizer _rootCharSymbols
protected BytesToNameCanonicalizer _rootByteSymbols
TODO: should clean up this; looks messy having 2 alternatives with not very clear differences.
protected ObjectCodec _objectCodec
protected int _parserFeatures
protected int _generatorFeatures
protected CharacterEscapes _characterEscapes
protected InputDecorator _inputDecorator
protected OutputDecorator _outputDecorator
public JsonFactory()
public JsonFactory(ObjectCodec oc)
public String getFormatName()
Note: sub-classes should override this method; default implementation will return null for all sub-classes
public MatchStrength hasFormat(InputAccessor acc) throws IOException
IOException
protected MatchStrength hasJSONFormat(InputAccessor acc) throws IOException
IOException
public Version version()
Versioned
Version
for details).public final JsonFactory configure(JsonParser.Feature f, boolean state)
JsonParser.Feature
for list of features)public JsonFactory enable(JsonParser.Feature f)
JsonParser.Feature
for list of features)public JsonFactory disable(JsonParser.Feature f)
JsonParser.Feature
for list of features)public final boolean isEnabled(JsonParser.Feature f)
public final void enableParserFeature(JsonParser.Feature f)
enable(JsonParser.Feature)
insteadpublic final void disableParserFeature(JsonParser.Feature f)
disable(JsonParser.Feature)
insteadpublic final void setParserFeature(JsonParser.Feature f, boolean state)
configure(JsonParser.Feature, boolean)
insteadpublic final boolean isParserFeatureEnabled(JsonParser.Feature f)
isEnabled(JsonParser.Feature)
insteadpublic InputDecorator getInputDecorator()
public JsonFactory setInputDecorator(InputDecorator d)
public final JsonFactory configure(JsonGenerator.Feature f, boolean state)
JsonGenerator.Feature
for list of features)public JsonFactory enable(JsonGenerator.Feature f)
JsonGenerator.Feature
for list of features)public JsonFactory disable(JsonGenerator.Feature f)
JsonGenerator.Feature
for list of features)public final boolean isEnabled(JsonGenerator.Feature f)
@Deprecated public final void enableGeneratorFeature(JsonGenerator.Feature f)
enable(JsonGenerator.Feature)
instead@Deprecated public final void disableGeneratorFeature(JsonGenerator.Feature f)
disable(JsonGenerator.Feature)
instead@Deprecated public final void setGeneratorFeature(JsonGenerator.Feature f, boolean state)
configure(JsonGenerator.Feature, boolean)
instead@Deprecated public final boolean isGeneratorFeatureEnabled(JsonGenerator.Feature f)
isEnabled(JsonGenerator.Feature)
insteadpublic CharacterEscapes getCharacterEscapes()
JsonGenerator
s
it creates.public JsonFactory setCharacterEscapes(CharacterEscapes esc)
JsonGenerator
s
it creates.public OutputDecorator getOutputDecorator()
public JsonFactory setOutputDecorator(OutputDecorator d)
public JsonFactory setCodec(ObjectCodec oc)
ObjectCodec
(typically
a ObjectMapper
) with
this factory (and more importantly, parsers and generators
it constructs). This is needed to use data-binding methods
of JsonParser
and JsonGenerator
instances.public ObjectCodec getCodec()
public JsonParser createJsonParser(File f) throws IOException, JsonParseException
Underlying input stream (needed for reading contents) will be owned (and managed, i.e. closed as need be) by the parser, since caller has no access to it.
f
- File that contains JSON content to parseIOException
JsonParseException
public JsonParser createJsonParser(URL url) throws IOException, JsonParseException
Underlying input stream (needed for reading contents) will be owned (and managed, i.e. closed as need be) by the parser, since caller has no access to it.
url
- URL pointing to resource that contains JSON content to parseIOException
JsonParseException
public JsonParser createJsonParser(InputStream in) throws IOException, JsonParseException
The input stream will not be owned by
the parser, it will still be managed (i.e. closed if
end-of-stream is reacher, or parser close method called)
if (and only if) JsonParser.Feature.AUTO_CLOSE_SOURCE
is enabled.
Note: no encoding argument is taken since it can always be auto-detected as suggested by Json RFC.
in
- InputStream to use for reading JSON content to parseIOException
JsonParseException
public JsonParser createJsonParser(Reader r) throws IOException, JsonParseException
The read stream will not be owned by
the parser, it will still be managed (i.e. closed if
end-of-stream is reacher, or parser close method called)
if (and only if) JsonParser.Feature.AUTO_CLOSE_SOURCE
is enabled.
r
- Reader to use for reading JSON content to parseIOException
JsonParseException
public JsonParser createJsonParser(byte[] data) throws IOException, JsonParseException
IOException
JsonParseException
public JsonParser createJsonParser(byte[] data, int offset, int len) throws IOException, JsonParseException
data
- Buffer that contains data to parseoffset
- Offset of the first data byte within bufferlen
- Length of contents to parse within bufferIOException
JsonParseException
public JsonParser createJsonParser(String content) throws IOException, JsonParseException
IOException
JsonParseException
public JsonGenerator createJsonGenerator(OutputStream out, JsonEncoding enc) throws IOException
Underlying stream is NOT owned by the generator constructed,
so that generator will NOT close the output stream when
JsonGenerator.close()
is called (unless auto-closing
feature,
JsonGenerator.Feature.AUTO_CLOSE_TARGET
is enabled).
Using application needs to close it explicitly if this is the case.
Note: there are formats that use fixed encoding (like most binary data formats) and that ignore passed in encoding.
out
- OutputStream to use for writing JSON contentenc
- Character encoding to useIOException
public JsonGenerator createJsonGenerator(Writer out) throws IOException
Underlying stream is NOT owned by the generator constructed,
so that generator will NOT close the Reader when
JsonGenerator.close()
is called (unless auto-closing
feature,
JsonGenerator.Feature.AUTO_CLOSE_TARGET
is enabled).
Using application needs to close it explicitly.
out
- Writer to use for writing JSON contentIOException
public JsonGenerator createJsonGenerator(OutputStream out) throws IOException
Note: there are formats that use fixed encoding (like most binary data formats).
IOException
public JsonGenerator createJsonGenerator(File f, JsonEncoding enc) throws IOException
Underlying stream is owned by the generator constructed,
i.e. generator will handle closing of file when
JsonGenerator.close()
is called.
f
- File to write contents toenc
- Character encoding to useIOException
protected JsonParser _createJsonParser(InputStream in, IOContext ctxt) throws IOException, JsonParseException
InputStream
and context object.
This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.
IOException
JsonParseException
protected JsonParser _createJsonParser(Reader r, IOContext ctxt) throws IOException, JsonParseException
Reader
object for reading content.
This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.
IOException
JsonParseException
protected JsonParser _createJsonParser(byte[] data, int offset, int len, IOContext ctxt) throws IOException, JsonParseException
Reader
object for reading content
passed as raw byte array.
This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.
IOException
JsonParseException
protected JsonGenerator _createJsonGenerator(Writer out, IOContext ctxt) throws IOException
Writer
and context object.
This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.
IOException
protected JsonGenerator _createUTF8JsonGenerator(OutputStream out, IOContext ctxt) throws IOException
OutputStream
and context object, using UTF-8 encoding.
This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.
IOException
protected Writer _createWriter(OutputStream out, JsonEncoding enc, IOContext ctxt) throws IOException
IOException
protected IOContext _createContext(Object srcRef, boolean resourceManaged)
public BufferRecycler _getBufferRecycler()
Note: only public to give access for ObjectMapper
protected InputStream _optimizedStreamFromURL(URL url) throws IOException
IOException