com.fasterxml.jackson.databind

Class ObjectReader

  • java.lang.Object
    • com.fasterxml.jackson.core.TreeCodec
      • com.fasterxml.jackson.core.ObjectCodec
        • com.fasterxml.jackson.databind.ObjectReader
  • All Implemented Interfaces:
    com.fasterxml.jackson.core.Versioned, Serializable


    public class ObjectReader
    extends com.fasterxml.jackson.core.ObjectCodec
    implements com.fasterxml.jackson.core.Versioned, Serializable
    Builder object that can be used for per-serialization configuration of deserialization parameters, such as root type to use or object to update (instead of constructing new instance).

    Uses "fluent" (or, kind of, builder) pattern so that instances are immutable (and thus fully thread-safe with no external synchronization); new instances are constructed for different configurations. Instances are initially constructed by ObjectMapper and can be reused, shared, cached; both because of thread-safety and because instances are relatively light-weight.

    See Also:
    Serialized Form
    • Field Detail

      • _config

        protected final DeserializationConfig _config
        General serialization configuration settings; while immutable, can use copy-constructor to create modified instances as necessary.
      • _context

        protected final DefaultDeserializationContext _context
        Blueprint instance of deserialization context; used for creating actual instance when needed.
      • _parserFactory

        protected final com.fasterxml.jackson.core.JsonFactory _parserFactory
        Factory used for constructing JsonGenerators
      • _unwrapRoot

        protected final boolean _unwrapRoot
        Flag that indicates whether root values are expected to be unwrapped or not
      • _valueType

        protected final JavaType _valueType
        Declared type of value to instantiate during deserialization. Defines which deserializer to use; as well as base type of instance to construct if an updatable value is not configured to be used (subject to changes by embedded type information, for polymorphic types). If _valueToUpdate is non-null, only used for locating deserializer.
      • _rootDeserializer

        protected final JsonDeserializer<Object> _rootDeserializer
        We may pre-fetch deserializer as soon as _valueType is known, and if so, reuse it afterwards. This allows avoiding further deserializer lookups and increases performance a bit on cases where readers are reused.
        Since:
        2.1
      • _valueToUpdate

        protected final Object _valueToUpdate
        Instance to update with data binding; if any. If null, a new instance is created, if non-null, properties of this value object will be updated instead. Note that value can be of almost any type, except not ArrayType; array types can not be modified because array size is immutable.
      • _schema

        protected final com.fasterxml.jackson.core.FormatSchema _schema
        When using data format that uses a schema, schema is passed to parser.
      • _injectableValues

        protected final InjectableValues _injectableValues
        Values that can be injected during deserialization, if any.
      • _dataFormatReaders

        protected final DataFormatReaders _dataFormatReaders
        Optional detector used for auto-detecting data format that byte-based input uses.

        NOTE: If defined non-null, readValue() methods that take Reader or String input will fail with exception, because format-detection only works on byte-sources. Also, if format can not be detect reliably (as per detector settings), a JsonParseException will be thrown).

        Since:
        2.1
      • _rootNames

        protected final RootNameLookup _rootNames
        Cache for root names used when root-wrapping is enabled.
    • Method Detail

      • version

        public com.fasterxml.jackson.core.Version version()
        Method that will return version information stored in and read from jar that contains this class.
        Specified by:
        version in interface com.fasterxml.jackson.core.Versioned
        Overrides:
        version in class com.fasterxml.jackson.core.ObjectCodec
      • withFeatures

        public ObjectReader withFeatures(DeserializationFeature... features)
        Method for constructing a new reader instance that is configured with specified features enabled.
      • without

        public ObjectReader without(DeserializationFeature feature)
        Method for constructing a new reader instance that is configured with specified feature disabled.
      • withoutFeatures

        public ObjectReader withoutFeatures(DeserializationFeature... features)
        Method for constructing a new reader instance that is configured with specified features disabled.
      • with

        public ObjectReader with(InjectableValues injectableValues)
        Method for constructing a new instance with configuration that uses passed InjectableValues to provide injectable values.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • with

        public ObjectReader with(JsonNodeFactory f)
        Method for constructing a new reader instance with configuration that uses passed JsonNodeFactory for constructing JsonNode instances.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • with

        public ObjectReader with(com.fasterxml.jackson.core.JsonFactory f)
        Method for constructing a new reader instance with configuration that uses passed JsonFactory for constructing underlying Readers.

        NOTE: only factories that DO NOT REQUIRE SPECIAL MAPPERS (that is, ones that return false for JsonFactory.requiresCustomCodec()) can be used: trying to use one that requires custom codec will throw exception

        Since:
        2.1
      • withRootName

        public ObjectReader withRootName(String rootName)
        Method for constructing a new instance with configuration that specifies what root name to expect for "root name unwrapping". See DeserializationConfig.withRootName(String) for details.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • with

        public ObjectReader with(com.fasterxml.jackson.core.FormatSchema schema)
        Method for constructing a new instance with configuration that passes specified FormatSchema to JsonParser that is constructed for parsing content.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • withType

        public ObjectReader withType(JavaType valueType)
        Method for constructing a new reader instance that is configured to data bind into specified type.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • withType

        public ObjectReader withType(Class<?> valueType)
        Method for constructing a new reader instance that is configured to data bind into specified type.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • withType

        public ObjectReader withType(Type valueType)
        Method for constructing a new reader instance that is configured to data bind into specified type.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • withType

        public ObjectReader withType(com.fasterxml.jackson.core.type.TypeReference<?> valueTypeRef)
        Method for constructing a new reader instance that is configured to data bind into specified type.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • withValueToUpdate

        public ObjectReader withValueToUpdate(Object value)
        Method for constructing a new instance with configuration that updates passed Object (as root value), instead of constructing a new value.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • withView

        public ObjectReader withView(Class<?> activeView)
        Method for constructing a new instance with configuration that uses specified View for filtering.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • with

        public ObjectReader with(com.fasterxml.jackson.core.Base64Variant defaultBase64)
      • withFormatDetection

        public ObjectReader withFormatDetection(ObjectReader... readers)
        Fluent factory method for constructing a reader that will try to auto-detect underlying data format, using specified list of JsonFactory instances, and default DataFormatReaders settings (for customized DataFormatReaders, you can construct instance yourself). to construct appropriate JsonParser for actual parsing.

        Note: since format detection only works with byte sources, it is possible to get a failure from some 'readValue()' methods. Also, if input can not be reliably (enough) detected as one of specified types, an exception will be thrown.

        Note: not all JsonFactory types can be passed: specifically, ones that require "custom codec" (like XML factory) will not work. Instead, use method that takes ObjectReader instances instead of factories.

        Parameters:
        readers - Data formats accepted, in decreasing order of priority (that is, matches checked in listed order, first match wins)
        Returns:
        Newly configured writer instance
        Since:
        2.1
      • withFormatDetection

        public ObjectReader withFormatDetection(DataFormatReaders readers)
        Fluent factory method for constructing a reader that will try to auto-detect underlying data format, using specified DataFormatReaders.

        NOTE: since format detection only works with byte sources, it is possible to get a failure from some 'readValue()' methods. Also, if input can not be reliably (enough) detected as one of specified types, an exception will be thrown.

        Parameters:
        readers - DataFormatReaders to use for detecting underlying format.
        Returns:
        Newly configured writer instance
        Since:
        2.1
      • isEnabled

        public boolean isEnabled(com.fasterxml.jackson.core.JsonParser.Feature f)
      • getFactory

        public com.fasterxml.jackson.core.JsonFactory getFactory()
        Overrides:
        getFactory in class com.fasterxml.jackson.core.ObjectCodec
        Since:
        2.1
      • getJsonFactory

        @Deprecated
        public com.fasterxml.jackson.core.JsonFactory getJsonFactory()
        Deprecated. Since 2.1: Use getFactory() instead
        Overrides:
        getJsonFactory in class com.fasterxml.jackson.core.ObjectCodec
      • readValue

        public <T> T readValue(com.fasterxml.jackson.core.JsonParser jp)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Method that binds content read using given parser, using configuration of this reader, including expected result type. Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(com.fasterxml.jackson.core.JsonParser jp,
                      Class<T> valueType)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Convenience method that binds content read using given parser, using configuration of this reader, except that expected value type is specified with the call (instead of currently configured root type). Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Specified by:
        readValue in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(com.fasterxml.jackson.core.JsonParser jp,
                      com.fasterxml.jackson.core.type.TypeReference<?> valueTypeRef)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Convenience method that binds content read using given parser, using configuration of this reader, except that expected value type is specified with the call (instead of currently configured root type). Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Specified by:
        readValue in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(com.fasterxml.jackson.core.JsonParser jp,
                      com.fasterxml.jackson.core.type.ResolvedType valueType)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Convenience method that binds content read using given parser, using configuration of this reader, except that expected value type is specified with the call (instead of currently configured root type). Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Specified by:
        readValue in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(com.fasterxml.jackson.core.JsonParser jp,
                      JavaType valueType)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Type-safe overloaded method, basically alias for readValue(JsonParser, ResolvedType).

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValues

        public <T> Iterator<T> readValues(com.fasterxml.jackson.core.JsonParser jp,
                                 Class<T> valueType)
                               throws IOException,
                                      com.fasterxml.jackson.core.JsonProcessingException
        Convenience method that is equivalent to:
           withType(valueType).readValues(jp);
        

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Specified by:
        readValues in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValues

        public <T> Iterator<T> readValues(com.fasterxml.jackson.core.JsonParser jp,
                                 com.fasterxml.jackson.core.type.TypeReference<?> valueTypeRef)
                               throws IOException,
                                      com.fasterxml.jackson.core.JsonProcessingException
        Convenience method that is equivalent to:
           withType(valueTypeRef).readValues(jp);
        

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Specified by:
        readValues in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValues

        public <T> Iterator<T> readValues(com.fasterxml.jackson.core.JsonParser jp,
                                 com.fasterxml.jackson.core.type.ResolvedType valueType)
                               throws IOException,
                                      com.fasterxml.jackson.core.JsonProcessingException
        Convenience method that is equivalent to:
           withType(valueType).readValues(jp);
        

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Specified by:
        readValues in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValues

        public <T> Iterator<T> readValues(com.fasterxml.jackson.core.JsonParser jp,
                                 JavaType valueType)
                               throws IOException,
                                      com.fasterxml.jackson.core.JsonProcessingException
        Convenience method that is equivalent to:
           withType(valueType).readValues(jp);
        

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • createArrayNode

        public JsonNode createArrayNode()
        Specified by:
        createArrayNode in class com.fasterxml.jackson.core.ObjectCodec
      • createObjectNode

        public JsonNode createObjectNode()
        Specified by:
        createObjectNode in class com.fasterxml.jackson.core.ObjectCodec
      • treeAsTokens

        public com.fasterxml.jackson.core.JsonParser treeAsTokens(com.fasterxml.jackson.core.TreeNode n)
        Specified by:
        treeAsTokens in class com.fasterxml.jackson.core.ObjectCodec
      • readTree

        public <T extends com.fasterxml.jackson.core.TreeNode> T readTree(com.fasterxml.jackson.core.JsonParser jp)
                                                               throws IOException,
                                                                      com.fasterxml.jackson.core.JsonProcessingException
        Convenience method that binds content read using given parser, using configuration of this reader, except that content is bound as JSON tree instead of configured root value type.

        Note: if an object was specified with withValueToUpdate(java.lang.Object), it will be ignored.

        NOTE: this method never tries to auto-detect format, since actual (data-format specific) parser is given.

        Specified by:
        readTree in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • writeTree

        public void writeTree(com.fasterxml.jackson.core.JsonGenerator jgen,
                     com.fasterxml.jackson.core.TreeNode rootNode)
        Specified by:
        writeTree in class com.fasterxml.jackson.core.ObjectCodec
      • readValue

        public <T> T readValue(InputStream src)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Method that binds content read from given input source, using configuration of this reader. Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(Reader src)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Method that binds content read from given input source, using configuration of this reader. Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(String src)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Method that binds content read from given JSON string, using configuration of this reader. Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(byte[] src)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Method that binds content read from given byte array, using configuration of this reader. Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(byte[] src,
                      int offset,
                      int length)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Method that binds content read from given byte array, using configuration of this reader. Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(File src)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(URL src)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Method that binds content read from given input source, using configuration of this reader. Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValue

        public <T> T readValue(JsonNode src)
                    throws IOException,
                           com.fasterxml.jackson.core.JsonProcessingException
        Convenience method for converting results from given JSON tree into given value type. Basically short-cut for:
           objectReader.readValue(src.traverse())
        
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readTree

        public JsonNode readTree(InputStream in)
                          throws IOException,
                                 com.fasterxml.jackson.core.JsonProcessingException
        Method that reads content from given input source, using configuration of this reader, and binds it as JSON Tree.

        Note that if an object was specified with a call to withValueToUpdate(Object) it will just be ignored; result is always a newly constructed JsonNode instance.

        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readTree

        public JsonNode readTree(Reader r)
                          throws IOException,
                                 com.fasterxml.jackson.core.JsonProcessingException
        Method that reads content from given input source, using configuration of this reader, and binds it as JSON Tree.

        Note that if an object was specified with a call to withValueToUpdate(Object) it will just be ignored; result is always a newly constructed JsonNode instance.

        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readTree

        public JsonNode readTree(String json)
                          throws IOException,
                                 com.fasterxml.jackson.core.JsonProcessingException
        Method that reads content from given JSON input String, using configuration of this reader, and binds it as JSON Tree.

        Note that if an object was specified with a call to withValueToUpdate(Object) it will just be ignored; result is always a newly constructed JsonNode instance.

        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValues

        public <T> MappingIterator<T> readValues(com.fasterxml.jackson.core.JsonParser jp)
                                      throws IOException,
                                             com.fasterxml.jackson.core.JsonProcessingException
        Method for reading sequence of Objects from parser stream.

        Sequence can be either root-level "unwrapped" sequence (without surrounding JSON array), or a sequence contained in a JSON Array. In either case JsonParser must point to the first token of the first element, OR not point to any token (in which case it is advanced to the next token). This means, specifically, that for wrapped sequences, parser MUST NOT point to the surrounding START_ARRAY but rather to the token following it.

        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValues

        public <T> MappingIterator<T> readValues(InputStream src)
                                      throws IOException,
                                             com.fasterxml.jackson.core.JsonProcessingException
        Method for reading sequence of Objects from parser stream.

        Sequence can be either wrapped or unwrapped root-level sequence: wrapped means that the elements are enclosed in JSON Array; and unwrapped that elements are directly accessed at main level. Assumption is that iff the first token of the document is START_ARRAY, we have a wrapped sequence; otherwise unwrapped. For wrapped sequences, leading START_ARRAY is skipped, so that for both cases, underlying JsonParser will point to what is expected to be the first token of the first element.

        Note that the wrapped vs unwrapped logic means that it is NOT possible to use this method for reading an unwrapped sequence of elements written as JSON Arrays: to read such sequences, one has to use readValues(JsonParser), making sure parser points to the first token of the first element (i.e. the second START_ARRAY which is part of the first element).

        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • readValues

        public <T> MappingIterator<T> readValues(URL src)
                                      throws IOException,
                                             com.fasterxml.jackson.core.JsonProcessingException
        Overloaded version of readValue(InputStream).
        Parameters:
        src - URL to read to access JSON content to parse.
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • treeToValue

        public <T> T treeToValue(com.fasterxml.jackson.core.TreeNode n,
                        Class<T> valueType)
                      throws com.fasterxml.jackson.core.JsonProcessingException
        Specified by:
        treeToValue in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        com.fasterxml.jackson.core.JsonProcessingException
      • writeValue

        public void writeValue(com.fasterxml.jackson.core.JsonGenerator jgen,
                      Object value)
                        throws IOException,
                               com.fasterxml.jackson.core.JsonProcessingException
        Specified by:
        writeValue in class com.fasterxml.jackson.core.ObjectCodec
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
      • _bindAndReadValues

        protected <T> MappingIterator<T> _bindAndReadValues(com.fasterxml.jackson.core.JsonParser p,
                                                Object valueToUpdate)
                                                 throws IOException,
                                                        com.fasterxml.jackson.core.JsonProcessingException
        Throws:
        IOException
        com.fasterxml.jackson.core.JsonProcessingException
        Since:
        2.1
      • _prefetchRootDeserializer

        protected JsonDeserializer<Object> _prefetchRootDeserializer(DeserializationConfig config,
                                                         JavaType valueType)
        Method called to locate deserializer ahead of time, if permitted by configuration. Method also is NOT to throw an exception if access fails.
      • _reportUnkownFormat

        protected void _reportUnkownFormat(DataFormatReaders detector,
                               DataFormatReaders.Match match)
                                    throws com.fasterxml.jackson.core.JsonProcessingException
        Method called to indicate that format detection failed to detect format of given input
        Throws:
        com.fasterxml.jackson.core.JsonProcessingException
      • _verifySchemaType

        protected void _verifySchemaType(com.fasterxml.jackson.core.FormatSchema schema)
        Since:
        2.2
      • _reportUndetectableSource

        protected void _reportUndetectableSource(Object src)
                                          throws com.fasterxml.jackson.core.JsonProcessingException
        Throws:
        com.fasterxml.jackson.core.JsonProcessingException

Copyright © 2014 FasterXML. All Rights Reserved.