Class JSON

  • All Implemented Interfaces:
    com.fasterxml.jackson.core.Versioned

    public class JSON
    extends java.lang.Object
    implements com.fasterxml.jackson.core.Versioned
    Main entry point for functionality for reading and writing JSON and configuring details of reading and writing.

    Note that instances are fully immutable, and thereby thread-safe.

    Note on source types: source to read is declared as Object but covers following types:

    • InputStream
    • Reader
    • byte[]
    • char[]
    • String/CharSequence
    • URL
    • File
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  JSON.Builder
      Builder class that needs to be used for certain kind of "static" configuration (settings that can not vary on per-call basis for JSON), such as Extension registration.
      static class  JSON.Feature
      Simple on/off (enabled/disabled) features for JSON; used for simple configuration aspects.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected int _features  
      protected com.fasterxml.jackson.core.JsonFactory _jsonFactory
      Underlying JSON factory used for creating Streaming parsers and generators.
      protected com.fasterxml.jackson.core.PrettyPrinter _prettyPrinter  
      protected JSONReader _reader
      Blueprint instance of the reader to use for reading JSON as simple Objects.
      protected com.fasterxml.jackson.core.TreeCodec _treeCodec
      Optional handler for TreeNode values: if defined, we can read and write TreeNode instances that codec supports.
      protected ValueReaderLocator _valueReaderLocator  
      protected ValueWriterLocator _valueWriterLocator  
      protected JSONWriter _writer
      Blueprint instance of the writer to use for writing JSON given simple Objects.
      static int CACHE_FLAGS  
      static JSON std
      Singleton instance with standard, default configuration.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected void _close​(java.io.Closeable cl)  
      protected <T> T _closeWithError​(java.io.Closeable cl, java.lang.Exception e)  
      protected com.fasterxml.jackson.core.JsonGenerator _config​(com.fasterxml.jackson.core.JsonGenerator g)  
      protected com.fasterxml.jackson.core.JsonParser _config​(com.fasterxml.jackson.core.JsonParser p)  
      protected JSONReader _defaultReader()  
      protected JSONWriter _defaultWriter()  
      protected com.fasterxml.jackson.core.JsonParser _initForReading​(com.fasterxml.jackson.core.JsonParser p)  
      protected void _noTreeCodec​(java.lang.String msg)  
      protected com.fasterxml.jackson.core.JsonParser _parser​(java.lang.Object source)  
      protected JSONReader _readerForOperation​(com.fasterxml.jackson.core.JsonParser p)  
      protected <T> T _throw​(java.lang.Exception e)  
      protected JSON _with​(int features)
      Internal mutant factory method used for constructing
      protected JSON _with​(int features, com.fasterxml.jackson.core.JsonFactory jsonF, com.fasterxml.jackson.core.TreeCodec trees, JSONReader reader, JSONWriter writer, com.fasterxml.jackson.core.PrettyPrinter pp)  
      protected void _writeAndClose​(java.lang.Object value, com.fasterxml.jackson.core.JsonGenerator g)  
      protected JSONWriter _writerForOperation​(com.fasterxml.jackson.core.JsonGenerator gen)  
      java.lang.Object anyFrom​(java.lang.Object source)
      Read method that will take given JSON Source (of one of supported types), read contents and map it to one of simple mappings (Map for JSON Objects, List for JSON Arrays, String for JSON Strings, null for JSON null, Boolean for JSON booleans and Number for JSON numbers.
      ValueIterator<java.lang.Object> anySequenceFrom​(java.lang.Object source)
      Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound as "Simple" type: Map, List, String, Number or Boolean.
      java.lang.Object[] arrayFrom​(java.lang.Object source)  
      <T> T[] arrayOfFrom​(java.lang.Class<T> type, java.lang.Object source)  
      byte[] asBytes​(java.lang.Object value)  
      com.fasterxml.jackson.core.ObjectCodec asCodec()
      Convenience method for constructing an adapter that uses this instance as a ObjectCodec
      java.lang.String asString​(java.lang.Object value)  
      <T> T beanFrom​(java.lang.Class<T> type, java.lang.Object source)  
      <T> ValueIterator<T> beanSequenceFrom​(java.lang.Class<T> type, java.lang.Object source)
      Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound to specific Bean (POJO) type.
      static JSON.Builder builder()  
      static JSON.Builder builder​(com.fasterxml.jackson.core.JsonFactory streamFactory)  
      JSONComposer<byte[]> composeBytes()  
      <C extends java.util.Collection<java.lang.Object>>
      CollectionComposer<?,​C>
      composeCollection​(C collection)  
      CollectionComposer<?,​java.util.List<java.lang.Object>> composeList()  
      MapComposer<?> composeMap()  
      MapComposer<?> composeMap​(java.util.Map<java.lang.String,​java.lang.Object> map)  
      JSONComposer<java.lang.String> composeString()  
      JSONComposer<java.io.OutputStream> composeTo​(java.io.File f)  
      JSONComposer<java.io.OutputStream> composeTo​(java.io.OutputStream out)  
      JSONComposer<java.io.OutputStream> composeTo​(java.io.Writer w)  
      JSONComposer<java.io.OutputStream> composeUsing​(com.fasterxml.jackson.core.JsonGenerator gen)  
      <T extends com.fasterxml.jackson.core.TreeNode>
      T
      createArrayNode()
      Convenience method, equivalent to:
      <T extends com.fasterxml.jackson.core.TreeNode>
      T
      createObjectNode()
      Convenience method, equivalent to:
      com.fasterxml.jackson.core.JsonParser createParser​(java.lang.Object source)
      Factory method for opening a JsonParser to read content from one of following supported sources InputStream Reader byte[] char[] String/CharSequence URL File
      com.fasterxml.jackson.core.JsonFactory getStreamingFactory()  
      com.fasterxml.jackson.core.TreeCodec getTreeCodec()  
      boolean isEnabled​(JSON.Feature f)  
      java.util.List<java.lang.Object> listFrom​(java.lang.Object source)  
      <T> java.util.List<T> listOfFrom​(java.lang.Class<T> type, java.lang.Object source)  
      java.util.Map<java.lang.String,​java.lang.Object> mapFrom​(java.lang.Object source)  
      <T> java.util.Map<java.lang.String,​T> mapOfFrom​(java.lang.Class<T> type, java.lang.Object source)
      Read method for reading a Map of type (usually POJO) values.
      <T extends com.fasterxml.jackson.core.TreeNode>
      T
      treeFrom​(java.lang.Object source)
      Method for reading content as a JSON Tree (of type that configured TreeCodec, see with(TreeCodec)) supports.
      <T extends com.fasterxml.jackson.core.TreeNode>
      ValueIterator<T>
      treeSequenceFrom​(java.lang.Object source)
      Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound as JSON Trees(of type that configured TreeCodec, see with(TreeCodec)) supports.
      com.fasterxml.jackson.core.Version version()  
      JSON with​(com.fasterxml.jackson.core.JsonFactory f)
      Deprecated.
      Since 2.11 should not try changing underlying stream factory but create a new instance if necessary: method will be removed from 3.0 at latest
      JSON with​(com.fasterxml.jackson.core.PrettyPrinter pp)
      Mutant factory for constructing an instance with specified PrettyPrinter, and returning new instance (or, if there would be no change, this instance).
      JSON with​(com.fasterxml.jackson.core.TreeCodec c)
      Deprecated.
      Since 2.11 should try using builder (see builder() and create properly configured instance
      JSON with​(CollectionBuilder b)
      Mutant factory for constructing an instance with specified CollectionBuilder, and returning new instance (or, if there would be no change, this instance).
      JSON with​(MapBuilder b)
      Mutant factory for constructing an instance with specified MapBuilder, and returning new instance (or, if there would be no change, this instance).
      JSON with​(ReaderWriterProvider rwp)
      Deprecated.
      Since 2.11 should register using JacksonJrExtension
      JSON with​(JSONReader r)
      Deprecated.
      Since 2.11 should try using builder (see builder() and create properly configured instance
      JSON with​(JSONWriter w)
      Deprecated.
      Since 2.11 should try using builder (see builder() and create properly configured instance
      JSON with​(JSON.Feature... features)
      Mutant factory for constructing an instance with specified features enabled.
      JSON with​(JSON.Feature feature, boolean state)
      Mutant factory for constructing an instance with specified feature enabled or disabled (depending on state), and returning an instance with that setting; this may either be this instance (if feature already had specified state), or a newly constructed instance.
      JSON without​(JSON.Feature... features)
      Mutant factory for constructing an instance with specified features disabled.
      void write​(java.lang.Object value, com.fasterxml.jackson.core.JsonGenerator gen)  
      void write​(java.lang.Object value, java.io.File f)  
      void write​(java.lang.Object value, java.io.OutputStream out)  
      void write​(java.lang.Object value, java.io.Writer w)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • CACHE_FLAGS

        public static final int CACHE_FLAGS
      • std

        public static final JSON std
        Singleton instance with standard, default configuration. May be used with direct references like:
           String json = JSON.std.asString(map);
        
      • _jsonFactory

        protected final com.fasterxml.jackson.core.JsonFactory _jsonFactory
        Underlying JSON factory used for creating Streaming parsers and generators.
      • _treeCodec

        protected final com.fasterxml.jackson.core.TreeCodec _treeCodec
        Optional handler for TreeNode values: if defined, we can read and write TreeNode instances that codec supports.
      • _reader

        protected final JSONReader _reader
        Blueprint instance of the reader to use for reading JSON as simple Objects.
      • _writer

        protected final JSONWriter _writer
        Blueprint instance of the writer to use for writing JSON given simple Objects.
      • _features

        protected final int _features
      • _prettyPrinter

        protected final com.fasterxml.jackson.core.PrettyPrinter _prettyPrinter
    • Constructor Detail

      • JSON

        public JSON()
      • JSON

        public JSON​(com.fasterxml.jackson.core.JsonFactory jsonF)
      • JSON

        public JSON​(JSON.Builder b)
        Constructor used when creating instance using JSON.Builder.
        Parameters:
        b - Builder that has configured settings to use.
        Since:
        2.11
      • JSON

        protected JSON​(JSON base,
                       int features,
                       com.fasterxml.jackson.core.JsonFactory jsonF,
                       com.fasterxml.jackson.core.TreeCodec trees,
                       JSONReader r,
                       JSONWriter w,
                       com.fasterxml.jackson.core.PrettyPrinter pp)
    • Method Detail

      • builder

        public static JSON.Builder builder()
        Since:
        2.11
      • builder

        public static JSON.Builder builder​(com.fasterxml.jackson.core.JsonFactory streamFactory)
        Since:
        2.11
      • _defaultReader

        protected JSONReader _defaultReader()
      • _defaultWriter

        protected JSONWriter _defaultWriter()
      • asCodec

        public com.fasterxml.jackson.core.ObjectCodec asCodec()
        Convenience method for constructing an adapter that uses this instance as a ObjectCodec
        Returns:
        Wrapper over this object to adapt to ObjectCodec API
      • version

        public com.fasterxml.jackson.core.Version version()
        Specified by:
        version in interface com.fasterxml.jackson.core.Versioned
      • with

        public JSON with​(com.fasterxml.jackson.core.PrettyPrinter pp)
        Mutant factory for constructing an instance with specified PrettyPrinter, and returning new instance (or, if there would be no change, this instance).
        Parameters:
        pp - PrettyPrinter to use for pretty-printing output (of null to disable pretty-printing)
        Returns:
        New instance with specified PrettyPrinter (if not same as currently configured); this otherwise.
      • with

        public JSON with​(JSON.Feature feature,
                         boolean state)
        Mutant factory for constructing an instance with specified feature enabled or disabled (depending on state), and returning an instance with that setting; this may either be this instance (if feature already had specified state), or a newly constructed instance.
      • with

        public JSON with​(JSON.Feature... features)
        Mutant factory for constructing an instance with specified features enabled.
      • without

        public JSON without​(JSON.Feature... features)
        Mutant factory for constructing an instance with specified features disabled.
      • _with

        protected final JSON _with​(int features)
        Internal mutant factory method used for constructing
      • with

        @Deprecated
        public JSON with​(com.fasterxml.jackson.core.JsonFactory f)
        Deprecated.
        Since 2.11 should not try changing underlying stream factory but create a new instance if necessary: method will be removed from 3.0 at latest
        Mutant factory method for constructing new instance with specified JsonFactory if different from currently configured one (if not, return this as-is)
        Parameters:
        f - Jackson core format factory to use for low-level decoding/encoding
        Returns:
        New instance with specified factory (if not same as currently configured); this otherwise.
      • with

        @Deprecated
        public JSON with​(com.fasterxml.jackson.core.TreeCodec c)
        Deprecated.
        Since 2.11 should try using builder (see builder() and create properly configured instance
        Mutant factory for constructing an instance with specified TreeCodec, and returning new instance (or, if there would be no change, this instance).
        Parameters:
        c - Tree codec to use for reading/writing of tree representation
        Returns:
        New instance with specified codec (if not same as currently configured); this otherwise.
      • with

        @Deprecated
        public JSON with​(JSONReader r)
        Deprecated.
        Since 2.11 should try using builder (see builder() and create properly configured instance
        Mutant factory for constructing an instance with specified JSONReader, and returning new instance (or, if there would be no change, this instance).
        Parameters:
        r - Customized JSONReader to use instead of standard one
        Returns:
        New instance with specified JSONReader (if not same as currently configured); this otherwise.
      • with

        @Deprecated
        public JSON with​(JSONWriter w)
        Deprecated.
        Since 2.11 should try using builder (see builder() and create properly configured instance
        Mutant factory for constructing an instance with specified JSONWriter, and returning new instance (or, if there would be no change, this instance).
        Parameters:
        w - Customized JSONWriter to use instead of standard one
        Returns:
        New instance with specified JSONWriter (if not same as currently configured); this otherwise.
      • with

        public JSON with​(MapBuilder b)
        Mutant factory for constructing an instance with specified MapBuilder, and returning new instance (or, if there would be no change, this instance).
      • with

        public JSON with​(CollectionBuilder b)
        Mutant factory for constructing an instance with specified CollectionBuilder, and returning new instance (or, if there would be no change, this instance).
      • _with

        protected JSON _with​(int features,
                             com.fasterxml.jackson.core.JsonFactory jsonF,
                             com.fasterxml.jackson.core.TreeCodec trees,
                             JSONReader reader,
                             JSONWriter writer,
                             com.fasterxml.jackson.core.PrettyPrinter pp)
      • getTreeCodec

        public com.fasterxml.jackson.core.TreeCodec getTreeCodec()
      • getStreamingFactory

        public com.fasterxml.jackson.core.JsonFactory getStreamingFactory()
      • isEnabled

        public final boolean isEnabled​(JSON.Feature f)
      • createParser

        public com.fasterxml.jackson.core.JsonParser createParser​(java.lang.Object source)
                                                           throws java.io.IOException,
                                                                  JSONObjectException
        Factory method for opening a JsonParser to read content from one of following supported sources
        • InputStream
        • Reader
        • byte[]
        • char[]
        • String/CharSequence
        • URL
        • File

        Rules regarding closing of the underlying source follow rules that JsonFactory has for its createParser method.

        Throws:
        java.io.IOException
        JSONObjectException
        Since:
        2.10
      • write

        public void write​(java.lang.Object value,
                          com.fasterxml.jackson.core.JsonGenerator gen)
                   throws java.io.IOException,
                          JSONObjectException
        Throws:
        java.io.IOException
        JSONObjectException
      • composeList

        public CollectionComposer<?,​java.util.List<java.lang.Object>> composeList()
      • composeCollection

        public <C extends java.util.Collection<java.lang.Object>> CollectionComposer<?,​C> composeCollection​(C collection)
      • composeMap

        public MapComposer<?> composeMap​(java.util.Map<java.lang.String,​java.lang.Object> map)
      • listOfFrom

        public <T> java.util.List<T> listOfFrom​(java.lang.Class<T> type,
                                                java.lang.Object source)
                                         throws java.io.IOException,
                                                JSONObjectException
        Throws:
        java.io.IOException
        JSONObjectException
      • arrayOfFrom

        public <T> T[] arrayOfFrom​(java.lang.Class<T> type,
                                   java.lang.Object source)
                            throws java.io.IOException,
                                   JSONObjectException
        Throws:
        java.io.IOException
        JSONObjectException
      • mapFrom

        public java.util.Map<java.lang.String,​java.lang.Object> mapFrom​(java.lang.Object source)
                                                                       throws java.io.IOException,
                                                                              JSONObjectException
        Throws:
        java.io.IOException
        JSONObjectException
      • mapOfFrom

        public <T> java.util.Map<java.lang.String,​T> mapOfFrom​(java.lang.Class<T> type,
                                                                     java.lang.Object source)
                                                              throws java.io.IOException,
                                                                     JSONObjectException
        Read method for reading a Map of type (usually POJO) values.
        Throws:
        java.io.IOException
        JSONObjectException
        Since:
        2.10
      • anyFrom

        public java.lang.Object anyFrom​(java.lang.Object source)
                                 throws java.io.IOException
        Read method that will take given JSON Source (of one of supported types), read contents and map it to one of simple mappings (Map for JSON Objects, List for JSON Arrays, String for JSON Strings, null for JSON null, Boolean for JSON booleans and Number for JSON numbers.

        Supported source types include:

        • InputStream
        • Reader
        • File
        • URL
        • String
        • byte[]
        • char[]
        Throws:
        java.io.IOException
      • treeFrom

        public <T extends com.fasterxml.jackson.core.TreeNode> T treeFrom​(java.lang.Object source)
                                                                   throws java.io.IOException,
                                                                          JSONObjectException
        Method for reading content as a JSON Tree (of type that configured TreeCodec, see with(TreeCodec)) supports.
        Throws:
        java.io.IOException
        JSONObjectException
        Since:
        2.8
      • beanSequenceFrom

        public <T> ValueIterator<T> beanSequenceFrom​(java.lang.Class<T> type,
                                                     java.lang.Object source)
                                              throws java.io.IOException,
                                                     JSONObjectException
        Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound to specific Bean (POJO) type.
        Throws:
        java.io.IOException
        JSONObjectException
        Since:
        2.10
      • anySequenceFrom

        public ValueIterator<java.lang.Object> anySequenceFrom​(java.lang.Object source)
                                                        throws java.io.IOException,
                                                               JSONObjectException
        Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound as "Simple" type: Map, List, String, Number or Boolean.
        Throws:
        java.io.IOException
        JSONObjectException
        Since:
        2.10
      • treeSequenceFrom

        public <T extends com.fasterxml.jackson.core.TreeNode> ValueIterator<T> treeSequenceFrom​(java.lang.Object source)
                                                                                          throws java.io.IOException,
                                                                                                 JSONObjectException
        Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound as JSON Trees(of type that configured TreeCodec, see with(TreeCodec)) supports.
        Throws:
        java.io.IOException
        JSONObjectException
      • createArrayNode

        public <T extends com.fasterxml.jackson.core.TreeNode> T createArrayNode()
        Convenience method, equivalent to:
           getTreeCodec().createArrayNode();
        
        Note that for call to succeed a TreeCodec must have been configured with this instance using with(TreeCodec) method.
        Since:
        2.8
      • createObjectNode

        public <T extends com.fasterxml.jackson.core.TreeNode> T createObjectNode()
        Convenience method, equivalent to:
           getTreeCodec().createObjectNode();
        
        Note that for call to succeed a TreeCodec must have been configured with this instance using with(TreeCodec) method.
        Since:
        2.8
      • _writeAndClose

        protected final void _writeAndClose​(java.lang.Object value,
                                            com.fasterxml.jackson.core.JsonGenerator g)
                                     throws java.io.IOException
        Throws:
        java.io.IOException
      • _writerForOperation

        protected JSONWriter _writerForOperation​(com.fasterxml.jackson.core.JsonGenerator gen)
      • _readerForOperation

        protected JSONReader _readerForOperation​(com.fasterxml.jackson.core.JsonParser p)
      • _parser

        protected com.fasterxml.jackson.core.JsonParser _parser​(java.lang.Object source)
                                                         throws java.io.IOException,
                                                                JSONObjectException
        Throws:
        java.io.IOException
        JSONObjectException
      • _initForReading

        protected com.fasterxml.jackson.core.JsonParser _initForReading​(com.fasterxml.jackson.core.JsonParser p)
                                                                 throws java.io.IOException
        Throws:
        java.io.IOException
      • _config

        protected com.fasterxml.jackson.core.JsonGenerator _config​(com.fasterxml.jackson.core.JsonGenerator g)
      • _config

        protected com.fasterxml.jackson.core.JsonParser _config​(com.fasterxml.jackson.core.JsonParser p)
      • _closeWithError

        protected <T> T _closeWithError​(java.io.Closeable cl,
                                        java.lang.Exception e)
                                 throws java.io.IOException
        Throws:
        java.io.IOException
      • _close

        protected void _close​(java.io.Closeable cl)
      • _throw

        protected <T> T _throw​(java.lang.Exception e)
                        throws java.io.IOException
        Throws:
        java.io.IOException
      • _noTreeCodec

        protected void _noTreeCodec​(java.lang.String msg)