Package com.fasterxml.jackson.databind

Class ObjectReader

  • All Implemented Interfaces:
    Versioned, java.io.Serializable
    public class ObjectReader
extends ObjectCodec
implements Versioned, java.io.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 "mutant factory" 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.

    NOTE: this class is NOT meant as sub-classable (with Jackson 2.8 and above) by users. It is left as non-final mostly to allow frameworks that require bytecode generation for proxying and similar use cases, but there is no expecation that functionality should be extended by sub-classing.

    See Also:
    Serialized Form

    • Method Detail

      • version

        public Version version()
        Method that will return version information stored in and read from jar that contains this class.
        Specified by:
        version in interface Versioned
        Specified by:
        version in class 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​(JsonParser.Feature feature)
        Method for constructing a new reader instance that is configured with specified feature enabled.

      • withFeatures

        public ObjectReader withFeatures​(JsonParser.Feature... features)
        Method for constructing a new reader instance that is configured with specified features enabled.

      • without

        public ObjectReader without​(JsonParser.Feature feature)
        Method for constructing a new reader instance that is configured with specified feature disabled.

      • withoutFeatures

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

      • with

        public ObjectReader with​(FormatFeature feature)
        Method for constructing a new reader instance that is configured with specified feature enabled.
        Since:
        2.7

      • withFeatures

        public ObjectReader withFeatures​(FormatFeature... features)
        Method for constructing a new reader instance that is configured with specified features enabled.
        Since:
        2.7

      • without

        public ObjectReader without​(FormatFeature feature)
        Method for constructing a new reader instance that is configured with specified feature disabled.
        Since:
        2.7

      • withoutFeatures

        public ObjectReader withoutFeatures​(FormatFeature... features)
        Method for constructing a new reader instance that is configured with specified features disabled.
        Since:
        2.7

      • with

        public ObjectReader with​(DeserializationConfig config)
        Mutant factory method that will construct a new instance that has specified underlying DeserializationConfig.

        NOTE: use of this method is not recommended, as there are many other re-configuration methods available.

      • 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​(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​(java.lang.String rootName)
        Method for constructing a new instance with configuration that specifies what root name to expect for "root name unwrapping". See MapperConfigBase.withRootName(String) for details.

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

      • withoutRootName

        public ObjectReader withoutRootName()
        Convenience method that is same as calling: withRootName("") which will forcibly prevent use of root name wrapping when writing values with this ObjectReader.
        Since:
        2.6

      • with

        public ObjectReader with​(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.

      • forType

        public ObjectReader forType​(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.

        Since:
        2.5

      • forType

        public ObjectReader forType​(java.lang.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.

        Since:
        2.5

      • forType

        public ObjectReader forType​(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.

        Since:
        2.5

      • withType

        @Deprecated
public ObjectReader withType​(java.lang.Class<?> valueType)
        Deprecated.
        since 2.5 Use forType(Class) instead

      • withType

        @Deprecated
public ObjectReader withType​(java.lang.reflect.Type valueType)
        Deprecated.
        since 2.5 Use forType(Class) instead

      • withValueToUpdate

        public ObjectReader withValueToUpdate​(java.lang.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​(java.lang.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​(java.util.TimeZone tz)

      • 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 cannot 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 cannot 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

      • withAttributes

        public ObjectReader withAttributes​(java.util.Map<?,​?> attrs)
        Since:
        2.3

      • withAttribute

        public ObjectReader withAttribute​(java.lang.Object key,
                                  java.lang.Object value)
        Since:
        2.3

      • withoutAttribute

        public ObjectReader withoutAttribute​(java.lang.Object key)
        Since:
        2.3

      • getInjectableValues

        public InjectableValues getInjectableValues()
        Since:
        2.6

      • getValueType

        public JavaType getValueType()
        Since:
        2.10

      • readValue

        public <T> T readValue​(JsonParser p)
                throws java.io.IOException
        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:
        java.io.IOException

      • readValue

        public <T> T readValue​(JsonParser p,
                       java.lang.Class<T> valueType)
                throws java.io.IOException
        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 ObjectCodec
        Throws:
        java.io.IOException

      • readValue

        public <T> T readValue​(JsonParser p,
                       TypeReference<T> valueTypeRef)
                throws java.io.IOException
        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 ObjectCodec
        Throws:
        java.io.IOException

      • readValue

        public <T> T readValue​(JsonParser p,
                       ResolvedType valueType)
                throws java.io.IOException
        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 ObjectCodec
        Throws:
        java.io.IOException

      • readValue

        public <T> T readValue​(JsonParser p,
                       JavaType valueType)
                throws java.io.IOException
        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:
        java.io.IOException

      • readValues

        public <T> java.util.Iterator<T> readValues​(JsonParser p,
                                            java.lang.Class<T> valueType)
                                     throws java.io.IOException
        Convenience method that is equivalent to: 
           withType(valueType).readValues(p);

        Method reads a 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 (one that contains values to read) but rather to the token following it which is the first token of the first value to read.

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

        Specified by:
        readValues in class ObjectCodec
        Throws:
        java.io.IOException

      • readValues

        public <T> java.util.Iterator<T> readValues​(JsonParser p,
                                            TypeReference<T> valueTypeRef)
                                     throws java.io.IOException
        Convenience method that is equivalent to: 
           withType(valueTypeRef).readValues(p);

        Method reads a 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 (one that contains values to read) but rather to the token following it which is the first token of the first value to read.

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

        Specified by:
        readValues in class ObjectCodec
        Throws:
        java.io.IOException

      • readValues

        public <T> java.util.Iterator<T> readValues​(JsonParser p,
                                            ResolvedType valueType)
                                     throws java.io.IOException
        Convenience method that is equivalent to: 
           withType(valueType).readValues(p);

        Method reads a 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 (one that contains values to read) but rather to the token following it which is the first token of the first value to read.

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

        Specified by:
        readValues in class ObjectCodec
        Throws:
        java.io.IOException

      • readValues

        public <T> java.util.Iterator<T> readValues​(JsonParser p,
                                            JavaType valueType)
                                     throws java.io.IOException
        Convenience method that is equivalent to: 
           withType(valueType).readValues(p);

        Method reads a 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 (one that contains values to read) but rather to the token following it which is the first token of the first value to read.

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

        Throws:
        java.io.IOException

      • readTree

        public <T extends TreeNode> T readTree​(JsonParser p)
                                throws java.io.IOException
        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. Returns JsonNode that represents the root of the resulting tree, if there was content to read, or null if no more content is accessible via passed JsonParser.

        NOTE! Behavior with end-of-input (no more content) differs between this readTree method, and all other methods that take input source: latter will return "missing node", NOT null

        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 ObjectCodec
        Returns:
        next tree from p, or null if empty.
        Throws:
        java.io.IOException

      • readValue

        public <T> T readValue​(java.io.InputStream src)
                throws java.io.IOException
        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:
        java.io.IOException

      • readValue

        public <T> T readValue​(java.io.Reader src)
                throws java.io.IOException
        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:
        java.io.IOException

      • readValue

        public <T> T readValue​(byte[] src)
                throws java.io.IOException
        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:
        java.io.IOException

      • readValue

        public <T> T readValue​(byte[] src,
                       int offset,
                       int length)
                throws java.io.IOException
        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:
        java.io.IOException

      • readValue

        public <T> T readValue​(java.io.File src)
                throws java.io.IOException
        Throws:
        java.io.IOException

      • readValue

        public <T> T readValue​(java.net.URL src)
                throws java.io.IOException
        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).

        NOTE: handling of URL is delegated to JsonFactory.createParser(java.net.URL) and usually simply calls URL.openStream(), meaning no special handling is done. If different HTTP connection options are needed you will need to create InputStream separately.

        Throws:
        java.io.IOException

      • readValue

        public <T> T readValue​(JsonNode src)
                throws java.io.IOException
        Convenience method for converting results from given JSON tree into given value type. Basically short-cut for: 
           objectReader.readValue(src.traverse())
        Throws:
        java.io.IOException

      • readValue

        public <T> T readValue​(java.io.DataInput src)
                throws java.io.IOException
        Throws:
        java.io.IOException
        Since:
        2.8

      • readTree

        public JsonNode readTree​(java.io.InputStream src)
                  throws java.io.IOException
        Method that reads content from given input source, using configuration of this reader, and binds it as JSON Tree. Returns JsonNode that represents the root of the resulting tree, if there was content to read, or "missing node" (instance of for which JsonNode.isMissingNode() returns true, and behaves otherwise similar to "null node") if no more content is accessible through passed-in input source.

        NOTE! Behavior with end-of-input (no more content) differs between this readTree method, and readTree(JsonParser) -- latter returns null for "no content" case.

        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:
        java.io.IOException

      • readTree

        public JsonNode readTree​(java.io.Reader src)
                  throws java.io.IOException
        Same as readTree(InputStream) except content accessed through passed-in Reader
        Throws:
        java.io.IOException

      • readTree

        public JsonNode readTree​(byte[] json)
                  throws java.io.IOException
        Same as readTree(InputStream) except content read from passed-in byte array.
        Throws:
        java.io.IOException

      • readTree

        public JsonNode readTree​(byte[] json,
                         int offset,
                         int len)
                  throws java.io.IOException
        Same as readTree(InputStream) except content read from passed-in byte array.
        Throws:
        java.io.IOException

      • readTree

        public JsonNode readTree​(java.io.DataInput src)
                  throws java.io.IOException
        Same as readTree(InputStream) except content read using passed-in DataInput.
        Throws:
        java.io.IOException

      • readValues

        public <T> MappingIterator<T> readValues​(JsonParser p)
                                  throws java.io.IOException
        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:
        java.io.IOException

      • readValues

        public <T> MappingIterator<T> readValues​(java.io.InputStream src)
                                  throws java.io.IOException
        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:
        java.io.IOException

      • readValues

        public <T> MappingIterator<T> readValues​(java.lang.String json)
                                  throws java.io.IOException
        Overloaded version of readValue(InputStream).
        Parameters:
        json - String that contains JSON content to parse
        Throws:
        java.io.IOException

      • readValues

        public <T> MappingIterator<T> readValues​(byte[] src,
                                         int offset,
                                         int length)
                                  throws java.io.IOException
        Overloaded version of readValue(InputStream).
        Throws:
        java.io.IOException

      • readValues

        public <T> MappingIterator<T> readValues​(java.net.URL src)
                                  throws java.io.IOException
        Overloaded version of readValue(InputStream).

        NOTE: handling of URL is delegated to JsonFactory.createParser(java.net.URL) and usually simply calls URL.openStream(), meaning no special handling is done. If different HTTP connection options are needed you will need to create InputStream separately.

        Parameters:
        src - URL to read to access JSON content to parse.
        Throws:
        java.io.IOException

      • readValues

        public <T> MappingIterator<T> readValues​(java.io.DataInput src)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
        Since:
        2.8

      • writeValue

        public void writeValue​(JsonGenerator gen,
                       java.lang.Object value)
                throws java.io.IOException
        Description copied from class: ObjectCodec
        Method to serialize given Java Object, using generator provided.
        Specified by:
        writeValue in class ObjectCodec
        Throws:
        java.io.IOException