java.lang.Object | |
↳ | com.fasterxml.jackson.core.JsonFactory |
The main factory class of Jackson package, used to configure and
construct reader (aka parser, 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.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
JsonFactory.Feature | Enumeration that defines all on/off features that can only be
changed for JsonFactory . |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | FORMAT_NAME_JSON | Name used to identify JSON format
(and returned by getFormatName()
|
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
DEFAULT_FACTORY_FEATURE_FLAGS | Bitfield (set of flags) of all factory features that are enabled by default. | ||||||||||
DEFAULT_GENERATOR_FEATURE_FLAGS | Bitfield (set of flags) of all generator features that are enabled by default. | ||||||||||
DEFAULT_PARSER_FEATURE_FLAGS | Bitfield (set of flags) of all parser features that are enabled by default. | ||||||||||
_characterEscapes | Definition of custom character escapes to use for generators created by this factory, if any. | ||||||||||
_factoryFeatures | Currently enabled factory features. | ||||||||||
_generatorFeatures | Currently enabled generator features. | ||||||||||
_inputDecorator | Optional helper object that may decorate input sources, to do additional processing on input during parsing. | ||||||||||
_objectCodec | Object that implements conversion functionality between Java objects and JSON content. | ||||||||||
_outputDecorator | Optional helper object that may decorate output object, to do additional processing on output during content generation. | ||||||||||
_parserFeatures | Currently enabled parser features. | ||||||||||
_recyclerRef | This ThreadLocal contains a java.lang.ref.SoftRerefence
to a BufferRecycler used to provide a low-cost
buffer recycling between reader and writer instances. |
||||||||||
_rootByteSymbols | Alternative to the basic symbol table, some stream-based parsers use different name canonicalization method. | ||||||||||
_rootCharSymbols | Each factory comes equipped with a shared root symbol table. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Default constructor used to create factory instances.
| |||||||||||
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Method used by factory to create buffer recycler instances
for parsers and generators.
| |||||||||||
Method for enabling or disabling specified parser feature
(check
JsonParser.Feature for list of features)
| |||||||||||
Method for enabling or disabling specified parser feature
(check
JsonParser.Feature for list of features)
| |||||||||||
Method for enabling or disabling specified generator feature
(check
JsonGenerator.Feature for list of features)
| |||||||||||
Method for constructing a new
JsonFactory that has
the same settings as this instance, but is otherwise
independent (i.e. | |||||||||||
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).
| |||||||||||
Method for constructing JSON generator for writing JSON content
using specified output stream.
| |||||||||||
Convenience method for constructing generator that uses default
encoding of the format (UTF-8 for JSON and most other data formats).
| |||||||||||
Method for constructing JSON generator for writing JSON content
using specified Writer.
| |||||||||||
Method for constructing JSON generator for writing JSON content
using specified Writer.
| |||||||||||
Convenience method for constructing generator that uses default
encoding of the format (UTF-8 for JSON and most other data formats).
| |||||||||||
Method for constructing JSON generator for writing JSON content
using specified output stream.
| |||||||||||
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).
| |||||||||||
Method for constructing parser for parsing
contents of given String.
| |||||||||||
Method for constructing parser for parsing
the contents of given byte array.
| |||||||||||
Method for constructing JSON parser instance to parse
contents of resource reference by given URL.
| |||||||||||
Method for constructing JSON parser instance to parse
contents of specified file.
| |||||||||||
Method for constructing parser for parsing
the contents of given byte array.
| |||||||||||
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.
| |||||||||||
Method for constructing parser for parsing
contents of given String.
| |||||||||||
Method for constructing JSON parser instance to parse
contents of specified file.
| |||||||||||
Method for constructing parser for parsing
the contents accessed via specified Reader.
| |||||||||||
Method for constructing JSON parser instance to parse
contents of resource reference by given URL.
| |||||||||||
Method for constructing parser for parsing
the contents of given byte array.
| |||||||||||
Method for constructing parser for parsing
the contents of given byte array.
| |||||||||||
Method for constructing JSON parser instance to parse
the contents accessed via specified input stream.
| |||||||||||
Method for disabling specified generator feature
(check
JsonGenerator.Feature for list of features)
| |||||||||||
Method for disabling specified parser features
(check
JsonParser.Feature for list of features)
| |||||||||||
Method for disabling specified parser features
(check
JsonFactory.Feature for list of features)
| |||||||||||
Method for enabling specified generator features
(check
JsonGenerator.Feature for list of features)
| |||||||||||
Method for enabling specified parser feature
(check
JsonParser.Feature for list of features)
| |||||||||||
Method for enabling specified parser feature
(check
JsonFactory.Feature for list of features)
| |||||||||||
Method for accessing custom escapes factory uses for
JsonGenerator s
it creates. | |||||||||||
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).
| |||||||||||
Check whether specified generator feature is enabled.
| |||||||||||
Checked whether specified parser feature is enabled.
| |||||||||||
Checked whether specified parser feature is enabled.
| |||||||||||
Method for defining custom escapes factory uses for
JsonGenerator s
it creates. | |||||||||||
Method for associating a
ObjectCodec (typically
a com.fasterxml.jackson.databind.ObjectMapper )
with this factory (and more importantly, parsers and generators
it constructs). | |||||||||||
Method for overriding currently configured input decorator
| |||||||||||
Method for overriding currently configured output decorator
| |||||||||||
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). |
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Overridable factory method that actually instantiates desired
context object.
| |||||||||||
Overridable factory method that actually instantiates generator for
given
Writer and context object. | |||||||||||
This method is deprecated.
since 2.1 -- use
_createGenerator(Writer, IOContext) instead
| |||||||||||
This method is deprecated.
since 2.1 -- use
_createParser(byte[], int, int, IOContext) instead
| |||||||||||
This method is deprecated.
since 2.1 -- use
_createParser(Reader, IOContext) instead
| |||||||||||
This method is deprecated.
since 2.1 -- use
_createParser(InputStream, IOContext) instead
| |||||||||||
Overridable factory method that actually instantiates desired parser
given
InputStream and context object. | |||||||||||
Overridable factory method that actually instantiates parser
using given
Reader object for reading content. | |||||||||||
Overridable factory method that actually instantiates parser
using given
Reader object for reading content
passed as raw byte array. | |||||||||||
Overridable factory method that actually instantiates generator for
given
OutputStream and context object, using UTF-8 encoding. | |||||||||||
This method is deprecated.
since 2.1
| |||||||||||
Helper methods used for constructing an optimal stream for
parsers to use, when input is to be read from an URL.
| |||||||||||
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
From interface
com.fasterxml.jackson.core.Versioned
|
Name used to identify JSON format
(and returned by getFormatName()
Bitfield (set of flags) of all factory features that are enabled by default.
Bitfield (set of flags) of all generator features that are enabled by default.
Bitfield (set of flags) of all parser features that are enabled by default.
Definition of custom character escapes to use for generators created by this factory, if any. If null, standard data format specific escapes are used.
Currently enabled factory features.
Currently enabled generator features.
Optional helper object that may decorate input sources, to do additional processing on input during parsing.
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.
Optional helper object that may decorate output object, to do additional processing on output during content generation.
Currently enabled parser features.
This ThreadLocal
contains a java.lang.ref.SoftRerefence
to a BufferRecycler
used to provide a low-cost
buffer recycling between reader and writer instances.
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.
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.
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.
Method used by factory to create buffer recycler instances for parsers and generators.
Note: only public to give access for ObjectMapper
Method for enabling or disabling specified parser feature
(check JsonParser.Feature
for list of features)
Method for enabling or disabling specified parser feature
(check JsonParser.Feature
for list of features)
Method for enabling or disabling specified generator feature
(check JsonGenerator.Feature
for list of features)
Method for constructing a new JsonFactory
that has
the same settings as this instance, but is otherwise
independent (i.e. nothing is actually shared, symbol tables
are separate).
Note that ObjectCodec
reference is not copied but is
set to null; caller typically needs to set it after calling
this method.
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
close()
is called.
NOTE: starting with 2.1, should not be used (will be deprecated in 2.2);
instead, should call createGenerator
.
f | File to write contents to |
---|---|
enc | Character encoding to use |
IOException |
---|
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
close()
is called (unless auto-closing
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.
NOTE: starting with 2.1, should not be used (will be deprecated in 2.2);
instead, should call createGenerator
.
out | OutputStream to use for writing JSON content |
---|---|
enc | Character encoding to use |
IOException |
---|
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).
NOTE: starting with 2.1, should not be used (will be deprecated in 2.2);
instead, should call createGenerator
.
IOException |
---|
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
close()
is called (unless auto-closing
feature,
AUTO_CLOSE_TARGET
is enabled).
Using application needs to close it explicitly.
NOTE: starting with 2.1, should not be used (will be deprecated in 2.2);
instead, should call createGenerator
.
out | Writer to use for writing JSON content |
---|
IOException |
---|
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
close()
is called (unless auto-closing
feature,
AUTO_CLOSE_TARGET
is enabled).
Using application needs to close it explicitly.
NOTE: starting with 2.1, should not be used (will be deprecated in 2.2);
instead, should call createGenerator
.
out | Writer to use for writing JSON content |
---|
IOException |
---|
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).
NOTE: starting with 2.1, should not be used (will be deprecated in 2.2);
instead, should call createGenerator
.
IOException |
---|
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
close()
is called (unless auto-closing
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.
NOTE: starting with 2.1, should not be used (will be deprecated in 2.2);
instead, should call createGenerator
.
out | OutputStream to use for writing JSON content |
---|---|
enc | Character encoding to use |
IOException |
---|
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
close()
is called.
NOTE: starting with 2.1, should not be used (will be deprecated in 2.2);
instead, should call createGenerator
.
f | File to write contents to |
---|---|
enc | Character encoding to use |
IOException |
---|
Method for constructing parser for parsing contents of given String.
NOTE: as of 2.1, should not be used (will be deprecated in 2.2);
instead, should call createParser
.
IOException | |
---|---|
JsonParseException |
Method for constructing parser for parsing the contents of given byte array.
NOTE: as of 2.1, should not be used (will be deprecated in 2.2);
instead, should call createParser
.
data | Buffer that contains data to parse |
---|---|
offset | Offset of the first data byte within buffer |
len | Length of contents to parse within buffer |
IOException | |
---|---|
JsonParseException |
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.
NOTE: as of 2.1, should not be used (will be deprecated in 2.2);
instead, should call createParser
.
url | URL pointing to resource that contains JSON content to parse |
---|
IOException | |
---|---|
JsonParseException |
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.
NOTE: as of 2.1, should not be used (will be deprecated in 2.2);
instead, should call createParser
.
f | File that contains JSON content to parse |
---|
IOException | |
---|---|
JsonParseException |
Method for constructing parser for parsing the contents of given byte array.
NOTE: as of 2.1, should not be used (will be deprecated in 2.2);
instead, should call createParser
.
IOException | |
---|---|
JsonParseException |
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) AUTO_CLOSE_SOURCE
is enabled.
Note: no encoding argument is taken since it can always be auto-detected as suggested by JSON RFC.
NOTE: as of 2.1, should not be used (will be deprecated in 2.2);
instead, should call createParser
.
in | InputStream to use for reading JSON content to parse |
---|
IOException | |
---|---|
JsonParseException |
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) AUTO_CLOSE_SOURCE
is enabled.
NOTE: as of 2.1, should not be used (will be deprecated in 2.2);
instead, should call createParser
.
r | Reader to use for reading JSON content to parse |
---|
IOException | |
---|---|
JsonParseException |
Method for constructing parser for parsing contents of given String.
IOException | |
---|---|
JsonParseException |
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.
f | File that contains JSON content to parse |
---|
IOException | |
---|---|
JsonParseException |
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) AUTO_CLOSE_SOURCE
is enabled.
r | Reader to use for reading JSON content to parse |
---|
IOException | |
---|---|
JsonParseException |
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.
url | URL pointing to resource that contains JSON content to parse |
---|
IOException | |
---|---|
JsonParseException |
Method for constructing parser for parsing the contents of given byte array.
data | Buffer that contains data to parse |
---|---|
offset | Offset of the first data byte within buffer |
len | Length of contents to parse within buffer |
IOException | |
---|---|
JsonParseException |
Method for constructing parser for parsing the contents of given byte array.
IOException | |
---|---|
JsonParseException |
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) 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 parse |
---|
IOException | |
---|---|
JsonParseException |
Method for disabling specified generator feature
(check JsonGenerator.Feature
for list of features)
Method for disabling specified parser features
(check JsonParser.Feature
for list of features)
Method for disabling specified parser features
(check JsonFactory.Feature
for list of features)
Method for enabling specified generator features
(check JsonGenerator.Feature
for list of features)
Method for enabling specified parser feature
(check JsonParser.Feature
for list of features)
Method for enabling specified parser feature
(check JsonFactory.Feature
for list of features)
Method for accessing custom escapes factory uses for JsonGenerator
s
it creates.
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
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).
Check whether specified generator feature is enabled.
Checked whether specified parser feature is enabled.
Checked whether specified parser feature is enabled.
Method for defining custom escapes factory uses for JsonGenerator
s
it creates.
Method for associating a ObjectCodec
(typically
a com.fasterxml.jackson.databind.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.
Method for overriding currently configured input decorator
Method for overriding currently configured output decorator
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).
Overridable factory method that actually instantiates desired context object.
Overridable factory method that actually instantiates generator for
given 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 |
---|
This method is deprecated.
since 2.1 -- use _createGenerator(Writer, IOContext)
instead
IOException |
---|
This method is deprecated.
since 2.1 -- use _createParser(byte[], int, int, IOContext)
instead
IOException | |
---|---|
JsonParseException |
This method is deprecated.
since 2.1 -- use _createParser(Reader, IOContext)
instead
IOException | |
---|---|
JsonParseException |
This method is deprecated.
since 2.1 -- use _createParser(InputStream, IOContext)
instead
IOException | |
---|---|
JsonParseException |
Overridable factory method that actually instantiates desired parser
given 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 |
Overridable factory method that actually instantiates parser
using given 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 |
Overridable factory method that actually instantiates parser
using given 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 |
Overridable factory method that actually instantiates generator for
given 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 |
---|
IOException |
---|
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.
IOException |
---|