Class JsonFactory
- All Implemented Interfaces:
Versioned
- Direct Known Subclasses:
MappingJsonFactory
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.
- Author:
- Tatu Saloranta
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected CharacterEscapes
Definition of custom character escapes to use for generators created by this factory, if any.protected int
Currently enabled generator features.protected InputDecorator
Optional helper object that may decorate input sources, to do additional processing on input during parsing.protected ObjectCodec
Object that implements conversion functionality between Java objects and JSON content.protected OutputDecorator
Optional helper object that may decorate output object, to do additional processing on output during content generation.protected int
Currently enabled parser features.protected static final ThreadLocal<SoftReference<BufferRecycler>>
ThisThreadLocal
contains aSoftReference
to aBufferRecycler
used to provide a low-cost buffer recycling between reader and writer instances.protected BytesToNameCanonicalizer
Alternative to the basic symbol table, some stream-based parsers use different name canonicalization method.protected CharsToNameCanonicalizer
Each factory comes equipped with a shared root symbol table.static final String
Name used to identify JSON format (and returned bygetFormatName()
-
Constructor Summary
ConstructorsConstructorDescriptionDefault constructor used to create factory instances. -
Method Summary
Modifier and TypeMethodDescriptionprotected 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 givenWriter
and context object.protected JsonParser
_createJsonParser
(byte[] data, int offset, int len, IOContext ctxt) Overridable factory method that actually instantiates parser using givenReader
object for reading content passed as raw byte array.protected JsonParser
_createJsonParser
(InputStream in, IOContext ctxt) Overridable factory method that actually instantiates desired parser givenInputStream
and context object.protected JsonParser
_createJsonParser
(Reader r, IOContext ctxt) Overridable factory method that actually instantiates parser using givenReader
object for reading content.protected JsonGenerator
_createUTF8JsonGenerator
(OutputStream out, IOContext ctxt) Overridable factory method that actually instantiates generator for givenOutputStream
and context object, using UTF-8 encoding.protected Writer
_createWriter
(OutputStream out, JsonEncoding enc, IOContext ctxt) Method used by factory to create buffer recycler instances for parsers and generators.protected InputStream
Helper methods used for constructing an optimal stream for parsers to use, when input is to be read from an URL.final JsonFactory
configure
(JsonGenerator.Feature f, boolean state) Method for enabling or disabling specified generator feature (checkJsonGenerator.Feature
for list of features)final JsonFactory
configure
(JsonParser.Feature f, boolean state) Method for enabling or disabling specified parser feature (checkJsonParser.Feature
for list of features)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).Convenience method for constructing generator that uses default encoding of the format (UTF-8 for JSON and most other data formats).createJsonGenerator
(OutputStream out, JsonEncoding enc) Method for constructing JSON generator for writing JSON content using specified output stream.Method for constructing JSON generator for writing JSON content using specified Writer.createJsonParser
(byte[] data) Method for constructing parser for parsing the contents of given byte array.createJsonParser
(byte[] data, int offset, int len) Method for constructing parser for parsing the contents of given byte array.Method for constructing JSON parser instance to parse contents of specified file.Method for constructing JSON parser instance to parse the contents accessed via specified input stream.Method for constructing parser for parsing the contents accessed via specified Reader.createJsonParser
(String content) Method for constructing parser for parsing contens of given String.createJsonParser
(URL url) Method for constructing JSON parser instance to parse contents of resource reference by given URL.Method for disabling specified generator feature (checkJsonGenerator.Feature
for list of features)Method for disabling specified parser features (checkJsonParser.Feature
for list of features)final void
Deprecated.final void
Deprecated.Usedisable(JsonParser.Feature)
insteadMethod for enabling specified generator features (checkJsonGenerator.Feature
for list of features)Method for enabling specified parser feature (checkJsonParser.Feature
for list of features)final void
Deprecated.Useenable(JsonGenerator.Feature)
insteadfinal void
Deprecated.Useenable(JsonParser.Feature)
insteadMethod for accessing custom escapes factory uses forJsonGenerator
s it creates.getCodec()
Method that returns short textual id identifying format this factory supports.Method for getting currently configured input decorator (if any; there is no default decorator).Method for getting currently configured output decorator (if any; there is no default decorator).hasFormat
(InputAccessor acc) protected MatchStrength
final boolean
Check whether specified generator feature is enabled.final boolean
Checked whether specified parser feature is enabled.final boolean
Deprecated.UseisEnabled(JsonGenerator.Feature)
insteadfinal boolean
Deprecated.UseisEnabled(JsonParser.Feature)
insteadMethod for defining custom escapes factory uses forJsonGenerator
s it creates.setCodec
(ObjectCodec oc) Method for associating aObjectCodec
(typically aObjectMapper
) with this factory (and more importantly, parsers and generators it constructs).final void
setGeneratorFeature
(JsonGenerator.Feature f, boolean state) Deprecated.Useconfigure(JsonGenerator.Feature, boolean)
insteadMethod for overriding currently configured input decoratorMethod for overriding currently configured output decoratorfinal void
setParserFeature
(JsonParser.Feature f, boolean state) Deprecated.Useconfigure(JsonParser.Feature, boolean)
insteadversion()
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 (seeVersion
for details).
-
Field Details
-
FORMAT_NAME_JSON
Name used to identify JSON format (and returned bygetFormatName()
- See Also:
-
_recyclerRef
ThisThreadLocal
contains aSoftReference
to aBufferRecycler
used to provide a low-cost buffer recycling between reader and writer instances. -
_rootCharSymbols
Each factory comes equipped with a shared root symbol table. It should not be linked back to the original blueprint, to avoid contents from leaking between factories. -
_rootByteSymbols
Alternative to the basic symbol table, some stream-based parsers use different name canonicalization method.TODO: should clean up this; looks messy having 2 alternatives with not very clear differences.
-
_objectCodec
Object that implements conversion functionality between Java objects and JSON content. For base JsonFactory implementation usually not set by default, but can be explicitly set. Sub-classes (like @link org.codehaus.jackson.map.MappingJsonFactory} usually provide an implementation. -
_parserFeatures
protected int _parserFeaturesCurrently enabled parser features. -
_generatorFeatures
protected int _generatorFeaturesCurrently enabled generator features. -
_characterEscapes
Definition of custom character escapes to use for generators created by this factory, if any. If null, standard data format specific escapes are used.- Since:
- 1.8
-
_inputDecorator
Optional helper object that may decorate input sources, to do additional processing on input during parsing.- Since:
- 1.8
-
_outputDecorator
Optional helper object that may decorate output object, to do additional processing on output during content generation.- Since:
- 1.8
-
-
Constructor Details
-
JsonFactory
public JsonFactory()Default constructor used to create factory instances. Creation of a factory instance is a light-weight operation, but it is still a good idea to reuse limited number of factory instances (and quite often just a single instance): factories are used as context for storing some reused processing objects (such as symbol tables parsers use) and this reuse only works within context of a single factory instance. -
JsonFactory
-
-
Method Details
-
getFormatName
Method that returns short textual id identifying format this factory supports.Note: sub-classes should override this method; default implementation will return null for all sub-classes
- Since:
- 1.8
-
hasFormat
- Throws:
IOException
-
hasJSONFormat
- Throws:
IOException
-
version
Description copied from interface:Versioned
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 (seeVersion
for details). -
configure
Method for enabling or disabling specified parser feature (checkJsonParser.Feature
for list of features)- Since:
- 1.2
-
enable
Method for enabling specified parser feature (checkJsonParser.Feature
for list of features)- Since:
- 1.2
-
disable
Method for disabling specified parser features (checkJsonParser.Feature
for list of features)- Since:
- 1.2
-
isEnabled
Checked whether specified parser feature is enabled.- Since:
- 1.2
-
enableParserFeature
Deprecated.Useenable(JsonParser.Feature)
instead -
disableParserFeature
Deprecated.Usedisable(JsonParser.Feature)
instead -
setParserFeature
Deprecated.Useconfigure(JsonParser.Feature, boolean)
instead -
isParserFeatureEnabled
Deprecated.UseisEnabled(JsonParser.Feature)
instead -
getInputDecorator
Method for getting currently configured input decorator (if any; there is no default decorator).- Since:
- 1.8
-
setInputDecorator
Method for overriding currently configured input decorator- Since:
- 1.8
-
configure
Method for enabling or disabling specified generator feature (checkJsonGenerator.Feature
for list of features)- Since:
- 1.2
-
enable
Method for enabling specified generator features (checkJsonGenerator.Feature
for list of features)- Since:
- 1.2
-
disable
Method for disabling specified generator feature (checkJsonGenerator.Feature
for list of features)- Since:
- 1.2
-
isEnabled
Check whether specified generator feature is enabled.- Since:
- 1.2
-
enableGeneratorFeature
Deprecated.Useenable(JsonGenerator.Feature)
instead -
disableGeneratorFeature
Deprecated.Usedisable(JsonGenerator.Feature)
instead -
setGeneratorFeature
Deprecated.Useconfigure(JsonGenerator.Feature, boolean)
instead -
isGeneratorFeatureEnabled
Deprecated.UseisEnabled(JsonGenerator.Feature)
instead -
getCharacterEscapes
Method for accessing custom escapes factory uses forJsonGenerator
s it creates.- Since:
- 1.8
-
setCharacterEscapes
Method for defining custom escapes factory uses forJsonGenerator
s it creates.- Since:
- 1.8
-
getOutputDecorator
Method for getting currently configured output decorator (if any; there is no default decorator).- Since:
- 1.8
-
setOutputDecorator
Method for overriding currently configured output decorator- Since:
- 1.8
-
setCodec
Method for associating aObjectCodec
(typically aObjectMapper
) with this factory (and more importantly, parsers and generators it constructs). This is needed to use data-binding methods ofJsonParser
andJsonGenerator
instances. -
getCodec
-
createJsonParser
Method for constructing JSON parser instance to parse contents of specified file. Encoding is auto-detected from contents according to JSON specification recommended mechanism.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.
- Parameters:
f
- File that contains JSON content to parse- Throws:
IOException
JsonParseException
-
createJsonParser
Method for constructing JSON parser instance to parse contents of resource reference by given URL. Encoding is auto-detected from contents according to JSON specification recommended mechanism.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.
- Parameters:
url
- URL pointing to resource that contains JSON content to parse- Throws:
IOException
JsonParseException
-
createJsonParser
Method for constructing JSON parser instance to parse the contents accessed via specified input stream.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.
- Parameters:
in
- InputStream to use for reading JSON content to parse- Throws:
IOException
JsonParseException
-
createJsonParser
Method for constructing parser for parsing the contents accessed via specified Reader.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.- Parameters:
r
- Reader to use for reading JSON content to parse- Throws:
IOException
JsonParseException
-
createJsonParser
Method for constructing parser for parsing the contents of given byte array.- Throws:
IOException
JsonParseException
-
createJsonParser
public JsonParser createJsonParser(byte[] data, int offset, int len) throws IOException, JsonParseException Method for constructing parser for parsing the contents of given byte array.- Parameters:
data
- Buffer that contains data to parseoffset
- Offset of the first data byte within bufferlen
- Length of contents to parse within buffer- Throws:
IOException
JsonParseException
-
createJsonParser
Method for constructing parser for parsing contens of given String.- Throws:
IOException
JsonParseException
-
createJsonGenerator
Method for constructing JSON generator for writing JSON content using specified output stream. Encoding to use must be specified, and needs to be one of available types (as per JSON specification).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.
- Parameters:
out
- OutputStream to use for writing JSON contentenc
- Character encoding to use- Throws:
IOException
-
createJsonGenerator
Method for constructing JSON generator for writing JSON content using specified Writer.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.- Parameters:
out
- Writer to use for writing JSON content- Throws:
IOException
-
createJsonGenerator
Convenience method for constructing generator that uses default encoding of the format (UTF-8 for JSON and most other data formats).Note: there are formats that use fixed encoding (like most binary data formats).
- Throws:
IOException
- Since:
- 1.8
-
createJsonGenerator
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). Encoding to use must be specified, and needs to be one of available types (as per JSON specification).Underlying stream is owned by the generator constructed, i.e. generator will handle closing of file when
JsonGenerator.close()
is called.- Parameters:
f
- File to write contents toenc
- Character encoding to use- Throws:
IOException
-
_createJsonParser
protected JsonParser _createJsonParser(InputStream in, IOContext ctxt) throws IOException, JsonParseException Overridable factory method that actually instantiates desired parser givenInputStream
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.
- Throws:
IOException
JsonParseException
-
_createJsonParser
protected JsonParser _createJsonParser(Reader r, IOContext ctxt) throws IOException, JsonParseException Overridable factory method that actually instantiates parser using givenReader
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.
- Throws:
IOException
JsonParseException
-
_createJsonParser
protected JsonParser _createJsonParser(byte[] data, int offset, int len, IOContext ctxt) throws IOException, JsonParseException Overridable factory method that actually instantiates parser using givenReader
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.
- Throws:
IOException
JsonParseException
-
_createJsonGenerator
Overridable factory method that actually instantiates generator for givenWriter
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.
- Throws:
IOException
-
_createUTF8JsonGenerator
protected JsonGenerator _createUTF8JsonGenerator(OutputStream out, IOContext ctxt) throws IOException Overridable factory method that actually instantiates generator for givenOutputStream
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.
- Throws:
IOException
-
_createWriter
protected Writer _createWriter(OutputStream out, JsonEncoding enc, IOContext ctxt) throws IOException - Throws:
IOException
-
_createContext
Overridable factory method that actually instantiates desired context object. -
_getBufferRecycler
Method used by factory to create buffer recycler instances for parsers and generators.Note: only public to give access for
ObjectMapper
-
_optimizedStreamFromURL
Helper methods used for constructing an optimal stream for parsers to use, when input is to be read from an URL. This helps when reading file content via URL.- Throws:
IOException
-
disable(JsonGenerator.Feature)
instead