com.fasterxml.jackson.core

Class JsonFactory

  • All Implemented Interfaces:
    Versioned, Serializable

    public class JsonFactory
extends Object
implements Versioned, Serializable
    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.

    Author:
    Tatu Saloranta
    See Also:
    Serialized Form

    • Field Detail

      • DEFAULT_FACTORY_FEATURE_FLAGS

        protected static final int DEFAULT_FACTORY_FEATURE_FLAGS
        Bitfield (set of flags) of all factory features that are enabled by default.

      • DEFAULT_PARSER_FEATURE_FLAGS

        protected static final int DEFAULT_PARSER_FEATURE_FLAGS
        Bitfield (set of flags) of all parser features that are enabled by default.

      • DEFAULT_GENERATOR_FEATURE_FLAGS

        protected static final int DEFAULT_GENERATOR_FEATURE_FLAGS
        Bitfield (set of flags) of all generator features that are enabled by default.

      • _rootCharSymbols

        protected final transient CharsToNameCanonicalizer _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.

      • _byteSymbolCanonicalizer

        protected final transient ByteQuadsCanonicalizer _byteSymbolCanonicalizer
        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.

        Since:
        2.6.0

      • _objectCodec

        protected ObjectCodec _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.

      • _factoryFeatures

        protected int _factoryFeatures
        Currently enabled factory features.

      • _parserFeatures

        protected int _parserFeatures
        Currently enabled parser features.

      • _generatorFeatures

        protected int _generatorFeatures
        Currently enabled generator features.

      • _characterEscapes

        protected CharacterEscapes _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.

      • _inputDecorator

        protected InputDecorator _inputDecorator
        Optional helper object that may decorate input sources, to do additional processing on input during parsing.

      • _outputDecorator

        protected OutputDecorator _outputDecorator
        Optional helper object that may decorate output object, to do additional processing on output during content generation.

      • _rootValueSeparator

        protected SerializableString _rootValueSeparator
        Separator used between root-level values, if any; null indicates "do not add separator". Default separator is a single space character.
        Since:
        2.1

    • Constructor Detail

      • 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

        protected JsonFactory(JsonFactory src,
                      ObjectCodec codec)
        Constructor used when copy()ing a factory instance.
        Since:
        2.2.1

    • Method Detail

      • copy

        public JsonFactory copy()
        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. Reason for this is that the codec is used for callbacks, and assumption is that there is strict 1-to-1 mapping between codec, factory. Caller has to, then, explicitly set codec after making the copy.
        Since:
        2.1

      • _checkInvalidCopy

        protected void _checkInvalidCopy(Class<?> exp)
        Parameters:
        exp -
        Since:
        2.1

      • readResolve

        protected Object readResolve()
        Method that we need to override to actually make restoration go through constructors etc. Also: must be overridden by sub-classes as well.

      • requiresPropertyOrdering

        public boolean requiresPropertyOrdering()
        Introspection method that higher-level functionality may call to see whether underlying data format requires a stable ordering of object properties or not. This is usually used for determining whether to force a stable ordering (like alphabetic ordering by name) if no ordering if explicitly specified.

        Default implementation returns false as JSON does NOT require stable ordering. Formats that require ordering include positional textual formats like CSV, and schema-based binary formats like Avro.

        Since:
        2.3

      • canHandleBinaryNatively

        public boolean canHandleBinaryNatively()
        Introspection method that higher-level functionality may call to see whether underlying data format can read and write binary data natively; that is, embeded it as-is without using encodings such as Base64.

        Default implementation returns false as JSON does not support native access: all binary content must use Base64 encoding. Most binary formats (like Smile and Avro) support native binary content.

        Since:
        2.3

      • canUseCharArrays

        public boolean canUseCharArrays()
        Introspection method that can be used by base factory to check whether access using char[] is something that actual parser implementations can take advantage of, over having to use Reader. Sub-types are expected to override definition; default implementation (suitable for JSON) alleges that optimization are possible; and thereby is likely to try to access String content by first copying it into recyclable intermediate buffer.
        Since:
        2.4

      • canParseAsync

        public boolean canParseAsync()
        Introspection method that can be used to check whether this factory can create non-blocking parsers: parsers that do not use blocking I/O abstractions but instead use a NonBlockingInputFeeder.
        Since:
        2.9

      • getFormatReadFeatureType

        public Class<? extends FormatFeature> getFormatReadFeatureType()
        Method for accessing kind of FormatFeature that a parser JsonParser produced by this factory would accept, if any; null returned if none.
        Since:
        2.6

      • getFormatWriteFeatureType

        public Class<? extends FormatFeature> getFormatWriteFeatureType()
        Method for accessing kind of FormatFeature that a parser JsonGenerator produced by this factory would accept, if any; null returned if none.
        Since:
        2.6

      • canUseSchema

        public boolean canUseSchema(FormatSchema schema)
        Method that can be used to quickly check whether given schema is something that parsers and/or generators constructed by this factory could use. Note that this means possible use, at the level of data format (i.e. schema is for same data format as parsers and generators this factory constructs); individual schema instances may have further usage restrictions.
        Since:
        2.1

      • getFormatName

        public String 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

      • requiresCustomCodec

        public boolean requiresCustomCodec()
        Method that can be called to determine if a custom ObjectCodec is needed for binding data parsed using JsonParser constructed by this factory (which typically also implies the same for serialization with JsonGenerator).
        Returns:
        True if custom codec is needed with parsers and generators created by this factory; false if a general ObjectCodec is enough
        Since:
        2.1

      • version

        public Version 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 (see Version for details).
        Specified by:
        version in interface Versioned

      • isEnabled

        public final boolean isEnabled(JsonFactory.Feature f)
        Checked whether specified parser feature is enabled.

      • isEnabled

        public final boolean isEnabled(JsonParser.Feature f)
        Checked whether specified parser feature is enabled.

      • getInputDecorator

        public InputDecorator getInputDecorator()
        Method for getting currently configured input decorator (if any; there is no default decorator).

      • setInputDecorator

        public JsonFactory setInputDecorator(InputDecorator d)
        Method for overriding currently configured input decorator

      • isEnabled

        public final boolean isEnabled(JsonGenerator.Feature f)
        Check whether specified generator feature is enabled.

      • getCharacterEscapes

        public CharacterEscapes getCharacterEscapes()
        Method for accessing custom escapes factory uses for JsonGenerators it creates.

      • getOutputDecorator

        public OutputDecorator getOutputDecorator()
        Method for getting currently configured output decorator (if any; there is no default decorator).

      • setOutputDecorator

        public JsonFactory setOutputDecorator(OutputDecorator d)
        Method for overriding currently configured output decorator

      • setRootValueSeparator

        public JsonFactory setRootValueSeparator(String sep)
        Method that allows overriding String used for separating root-level JSON values (default is single space character)
        Parameters:
        sep - Separator to use, if any; null means that no separator is automatically added
        Since:
        2.1

      • getRootValueSeparator

        public String getRootValueSeparator()
        Since:
        2.1

      • setCodec

        public JsonFactory setCodec(ObjectCodec oc)
        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.

      • createParser

        public JsonParser createParser(File f)
                        throws 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. Json specification supports only UTF-8, UTF-16 and UTF-32 as valid encodings, so auto-detection implemented only for this charsets. For other charsets use createParser(java.io.Reader).

        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
        Since:
        2.1

      • createParser

        public JsonParser createParser(URL url)
                        throws 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. Json specification supports only UTF-8, UTF-16 and UTF-32 as valid encodings, so auto-detection implemented only for this charsets. For other charsets use createParser(java.io.Reader).

        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
        Since:
        2.1

      • createParser

        public JsonParser createParser(InputStream in)
                        throws 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) 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. Json specification supports only UTF-8, UTF-16 and UTF-32 as valid encodings, so auto-detection implemented only for this charsets. For other charsets use createParser(java.io.Reader).

        Parameters:
        in - InputStream to use for reading JSON content to parse
        Throws:
        IOException
        JsonParseException
        Since:
        2.1

      • createParser

        public JsonParser createParser(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 parse
        offset - Offset of the first data byte within buffer
        len - Length of contents to parse within buffer
        Throws:
        IOException
        JsonParseException
        Since:
        2.1

      • createParser

        public JsonParser createParser(char[] content)
                        throws IOException
        Method for constructing parser for parsing contents of given char array.
        Throws:
        IOException
        Since:
        2.4

      • createParser

        public JsonParser createParser(char[] content,
                               int offset,
                               int len)
                        throws IOException
        Method for constructing parser for parsing contents of given char array.
        Throws:
        IOException
        Since:
        2.4

      • createJsonParser

        @Deprecated
public JsonParser createJsonParser(File f)
                                        throws IOException,
                                               JsonParseException
        Deprecated. Since 2.2, use createParser(File) instead.
        Method for constructing JSON parser instance to parse contents of specified file.

        Encoding is auto-detected from contents according to JSON specification recommended mechanism. Json specification supports only UTF-8, UTF-16 and UTF-32 as valid encodings, so auto-detection implemented only for this charsets. For other charsets use createParser(java.io.Reader).

        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

        @Deprecated
public JsonParser createJsonParser(URL url)
                                        throws IOException,
                                               JsonParseException
        Deprecated. Since 2.2, use createParser(URL) instead.
        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. Json specification supports only UTF-8, UTF-16 and UTF-32 as valid encodings, so auto-detection implemented only for this charsets. For other charsets use createParser(java.io.Reader).

        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

        @Deprecated
public JsonParser createJsonParser(InputStream in)
                                        throws IOException,
                                               JsonParseException
        Deprecated. Since 2.2, use createParser(InputStream) instead.
        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. Json specification supports only UTF-8, UTF-16 and UTF-32 as valid encodings, so auto-detection implemented only for this charsets. For other charsets use createParser(java.io.Reader).

        Parameters:
        in - InputStream to use for reading JSON content to parse
        Throws:
        IOException
        JsonParseException

      • createGenerator

        public JsonGenerator createGenerator(OutputStream out,
                                     JsonEncoding enc)
                              throws 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 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 content
        enc - Character encoding to use
        Throws:
        IOException
        Since:
        2.1

      • createGenerator

        public JsonGenerator createGenerator(OutputStream out)
                              throws 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).

        Throws:
        IOException
        Since:
        2.1

      • createGenerator

        public JsonGenerator createGenerator(Writer w)
                              throws 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 JsonGenerator.close() is called (unless auto-closing feature, JsonGenerator.Feature.AUTO_CLOSE_TARGET is enabled). Using application needs to close it explicitly.

        Parameters:
        w - Writer to use for writing JSON content
        Throws:
        IOException
        Since:
        2.1

      • createGenerator

        public JsonGenerator createGenerator(File f,
                                     JsonEncoding enc)
                              throws 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 JsonGenerator.close() is called.

        Parameters:
        f - File to write contents to
        enc - Character encoding to use
        Throws:
        IOException
        Since:
        2.1

      • createGenerator

        public JsonGenerator createGenerator(DataOutput out)
                              throws 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).

        Throws:
        IOException
        Since:
        2.8

      • createJsonGenerator

        @Deprecated
public JsonGenerator createJsonGenerator(OutputStream out,
                                                     JsonEncoding enc)
                                              throws IOException
        Deprecated. Since 2.2, use createGenerator(OutputStream, JsonEncoding) instead.
        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 content
        enc - Character encoding to use
        Throws:
        IOException

      • _createParser

        protected JsonParser _createParser(InputStream in,
                                   IOContext ctxt)
                            throws IOException
        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.

        Throws:
        IOException
        Since:
        2.1

      • _createParser

        protected JsonParser _createParser(Reader r,
                                   IOContext ctxt)
                            throws IOException
        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.

        Throws:
        IOException
        Since:
        2.1

      • _createParser

        protected JsonParser _createParser(char[] data,
                                   int offset,
                                   int len,
                                   IOContext ctxt,
                                   boolean recyclable)
                            throws IOException
        Overridable factory method that actually instantiates parser using given char[] object for accessing content.
        Throws:
        IOException
        Since:
        2.4

      • _createParser

        protected JsonParser _createParser(byte[] data,
                                   int offset,
                                   int len,
                                   IOContext ctxt)
                            throws IOException
        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.

        Throws:
        IOException

      • _createGenerator

        protected JsonGenerator _createGenerator(Writer out,
                                         IOContext ctxt)
                                  throws IOException
        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.

        Throws:
        IOException

      • _createUTF8Generator

        protected JsonGenerator _createUTF8Generator(OutputStream out,
                                             IOContext ctxt)
                                      throws IOException
        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.

        Throws:
        IOException

      • _getBufferRecycler

        public BufferRecycler _getBufferRecycler()
        Method used by factory to create buffer recycler instances for parsers and generators.

        Note: only public to give access for ObjectMapper

      • _createContext

        protected IOContext _createContext(Object srcRef,
                                   boolean resourceManaged)
        Overridable factory method that actually instantiates desired context object.

      • _createNonBlockingContext

        protected IOContext _createNonBlockingContext(Object srcRef)
        Overridable factory method that actually instantiates desired context object for async (non-blocking) parsing
        Since:
        2.9.7

      • _optimizedStreamFromURL

        protected InputStream _optimizedStreamFromURL(URL url)
                                       throws 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.
        Throws:
        IOException

Copyright © 2008–2018 FasterXML. All rights reserved.