Package edu.internet2.middleware.grouperClientExt.com.fasterxml.jackson.databind

Class ObjectReader

java.lang.Object
edu.internet2.middleware.grouperClientExt.com.fasterxml.jackson.core.TreeCodec
edu.internet2.middleware.grouperClientExt.com.fasterxml.jackson.core.ObjectCodec
edu.internet2.middleware.grouperClientExt.com.fasterxml.jackson.databind.ObjectReader
All Implemented Interfaces:
Versioned, Serializable
public class ObjectReader extends ObjectCodec implements 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 "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:

  • Field Details

    • _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 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 cannot be modified because array size is immutable.

    • _schema

      protected final 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 cannot be detect reliably (as per detector settings), a StreamReadException will be thrown).

      Since:
      2.1

    • _rootDeserializers

      protected final ConcurrentHashMap<JavaType,JsonDeserializer<Object>> _rootDeserializers
      Root-level cached deserializers. Passed by ObjectMapper, shared with it.

    • _jsonNodeType

      protected transient JavaType _jsonNodeType
      Lazily resolved JavaType for JsonNode

  • Constructor Details

  • Method Details

    • 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
      Returns:
      Version of the component

    • _new

      protected ObjectReader _new(ObjectReader base, JsonFactory f)
      Overridable factory method called by various "withXxx()" methods
      Since:
      2.5

    • _new

      protected ObjectReader _new(ObjectReader base, DeserializationConfig config)
      Overridable factory method called by various "withXxx()" methods
      Since:
      2.5

    • _new

      protected ObjectReader _new(ObjectReader base, DeserializationConfig config, JavaType valueType, JsonDeserializer<Object> rootDeser, Object valueToUpdate, FormatSchema schema, InjectableValues injectableValues, DataFormatReaders dataFormatReaders)
      Overridable factory method called by various "withXxx()" methods
      Since:
      2.5

    • _newIterator

      protected <T> MappingIterator<T> _newIterator(JsonParser p, DeserializationContext ctxt, JsonDeserializer<?> deser, boolean parserManaged)
      Factory method used to create MappingIterator instances; either default, or custom subtype.
      Since:
      2.5

    • _initForReading

      protected JsonToken _initForReading(DeserializationContext ctxt, JsonParser p) throws IOException
      Throws:
      IOException

    • _initForMultiRead

      protected void _initForMultiRead(DeserializationContext ctxt, JsonParser p) throws IOException
      Alternative to _initForReading(edu.internet2.middleware.grouperClientExt.com.fasterxml.jackson.databind.DeserializationContext, edu.internet2.middleware.grouperClientExt.com.fasterxml.jackson.core.JsonParser) used in cases where reading of multiple values means that we may or may not want to advance the stream, but need to do other initialization.

      Base implementation only sets configured FormatSchema, if any, on parser.

      Throws:
      IOException
      Since:
      2.8

    • with

      public ObjectReader with(DeserializationFeature feature)
      Method for constructing a new reader instance that is configured with specified feature enabled.

    • with

      public ObjectReader with(DeserializationFeature first, DeserializationFeature... other)
      Method for constructing a new reader instance that is configured with specified features enabled.

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

    • without

      public ObjectReader without(DeserializationFeature first, DeserializationFeature... other)
      Method for constructing a new reader instance that is configured with specified features 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(DatatypeFeature feature)
      Method for constructing a new reader instance that is configured with specified feature enabled.
      Since:
      2.14

    • withFeatures

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

    • without

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

    • withoutFeatures

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

    • with

      public ObjectReader with(JsonParser.Feature feature)
      Method for constructing a new reader instance that is configured with specified feature enabled.
      Parameters:
      feature - Feature to enable
      Returns:
      Reader instance 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.
      Parameters:
      features - Features to enable
      Returns:
      Reader instance 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.
      Parameters:
      feature - Feature to disable
      Returns:
      Reader instance 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.
      Parameters:
      features - Features to disable
      Returns:
      Reader instance with specified features disabled

    • with

      public ObjectReader with(StreamReadFeature feature)
      Method for constructing a new reader instance that is configured with specified feature enabled.
      Returns:
      Reader instance with specified feature enabled
      Since:
      2.11

    • without

      public ObjectReader without(StreamReadFeature feature)
      Method for constructing a new reader instance that is configured with specified feature disabled.
      Returns:
      Reader instance with specified feature enabled
      Since:
      2.11

    • 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

    • at

      public ObjectReader at(String pointerExpr)
      Convenience method to bind from JsonPointer. JsonPointerBasedFilter is registered and will be used for parsing later.
      Since:
      2.6

    • at

      public ObjectReader at(JsonPointer pointer)
      Convenience method to bind from JsonPointer JsonPointerBasedFilter is registered and will be used for parsing later.
      Since:
      2.6

    • 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(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.

    • withRootName

      public ObjectReader withRootName(PropertyName rootName)
      Since:
      2.6

    • 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(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(JavaType valueType)
      Deprecated.
      since 2.5 Use forType(JavaType) instead

    • withType

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

    • withType

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

    • withType

      @Deprecated public ObjectReader withType(TypeReference<?> valueTypeRef)
      Deprecated.
      since 2.5 Use forType(TypeReference) instead

    • 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(Locale l)

    • with

      public ObjectReader with(TimeZone tz)

    • withHandler

      public ObjectReader withHandler(DeserializationProblemHandler h)

    • with

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

    • with

      public ObjectReader with(ContextAttributes attrs)
      Since:
      2.3

    • withAttributes

      public ObjectReader withAttributes(Map<?,?> attrs)
      Since:
      2.3

    • withAttribute

      public ObjectReader withAttribute(Object key, Object value)
      Since:
      2.3

    • withoutAttribute

      public ObjectReader withoutAttribute(Object key)
      Since:
      2.3

    • _with

      protected ObjectReader _with(DeserializationConfig newConfig)

    • isEnabled

      public boolean isEnabled(DeserializationFeature f)

    • isEnabled

      public boolean isEnabled(MapperFeature f)

    • isEnabled

      public boolean isEnabled(DatatypeFeature f)
      Since:
      2.14

    • isEnabled

      public boolean isEnabled(JsonParser.Feature f)

    • isEnabled

      public boolean isEnabled(StreamReadFeature f)
      Since:
      2.11

    • getConfig

      public DeserializationConfig getConfig()
      Since:
      2.2

    • getFactory

      public JsonFactory getFactory()
      Description copied from class: ObjectCodec
      Accessor for finding underlying data format factory (JsonFactory) codec will use for data binding.
      Overrides:
      getFactory in class ObjectCodec
      Returns:
      Underlying JsonFactory instance
      Since:
      2.1

    • getTypeFactory

      public TypeFactory getTypeFactory()

    • getAttributes

      public ContextAttributes getAttributes()
      Since:
      2.3

    • getInjectableValues

      public InjectableValues getInjectableValues()
      Since:
      2.6

    • getValueType

      public JavaType getValueType()
      Since:
      2.10

    • createParser

      public JsonParser createParser(File src) throws IOException
      Factory method for constructing properly initialized JsonParser to read content from specified File. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(URL src) throws IOException
      Factory method for constructing properly initialized JsonParser to read content from specified File. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(InputStream in) throws IOException
      Factory method for constructing properly initialized JsonParser to read content using specified InputStream. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(Reader r) throws IOException
      Factory method for constructing properly initialized JsonParser to read content using specified Reader. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(byte[] content) throws IOException
      Factory method for constructing properly initialized JsonParser to read content from specified byte array. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(byte[] content, int offset, int len) throws IOException
      Factory method for constructing properly initialized JsonParser to read content from specified byte array. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(String content) throws IOException
      Factory method for constructing properly initialized JsonParser to read content from specified String. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(char[] content) throws IOException
      Factory method for constructing properly initialized JsonParser to read content from specified character array Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(char[] content, int offset, int len) throws IOException
      Factory method for constructing properly initialized JsonParser to read content from specified character array. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createParser

      public JsonParser createParser(DataInput content) throws IOException
      Factory method for constructing properly initialized JsonParser to read content using specified DataInput. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • createNonBlockingByteArrayParser

      public JsonParser createNonBlockingByteArrayParser() throws IOException
      Factory method for constructing properly initialized JsonParser to read content using non-blocking (asynchronous) mode. Parser is not managed (or "owned") by ObjectReader: caller is responsible for properly closing it once content reading is complete.
      Throws:
      IOException
      Since:
      2.11

    • readValue

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

    • readValue

      public <T> T readValue(JsonParser p, Class<T> valueType) throws 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
      Type Parameters:
      T - Nominal parameter for target type
      Parameters:
      p - Parser to use for decoding content to bind
      valueType - Java value type to bind content to
      Returns:
      Value deserialized
      Throws:
      IOException - for low-level read issues, or JsonParseException for decoding problems

    • readValue

      public <T> T readValue(JsonParser p, TypeReference<T> valueTypeRef) throws 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
      Type Parameters:
      T - Nominal parameter for target type
      Parameters:
      p - Parser to use for decoding content to bind
      valueTypeRef - Java value type to bind content to
      Returns:
      Value deserialized
      Throws:
      IOException - for low-level read issues, or JsonParseException for decoding problems

    • readValue

      public <T> T readValue(JsonParser p, ResolvedType valueType) throws 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
      Type Parameters:
      T - Nominal parameter for target type
      Parameters:
      p - Parser to use for decoding content to bind
      valueType - Java value type to bind content to
      Returns:
      Value deserialized
      Throws:
      IOException - for low-level read issues, or JsonParseException for decoding problems

    • readValue

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

    • readValues

      public <T> Iterator<T> readValues(JsonParser p, Class<T> valueType) throws 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
      Type Parameters:
      T - Nominal parameter for target type
      Parameters:
      p - Parser to use for decoding content to bind
      valueType - Java value type to bind content to
      Returns:
      Iterator for incrementally deserializing values
      Throws:
      IOException - for low-level read issues, or JsonParseException for decoding problems

    • readValues

      public <T> Iterator<T> readValues(JsonParser p, TypeReference<T> valueTypeRef) throws 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
      Type Parameters:
      T - Nominal parameter for target type
      Parameters:
      p - Parser to use for decoding content to bind
      valueTypeRef - Java value type to bind content to
      Returns:
      Iterator for incrementally deserializing values
      Throws:
      IOException - for low-level read issues, or JsonParseException for decoding problems

    • readValues

      public <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType) throws 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
      Type Parameters:
      T - Nominal parameter for target type
      Parameters:
      p - Parser to use for decoding content to bind
      valueType - Java value type to bind content to
      Returns:
      Iterator for incrementally deserializing values
      Throws:
      IOException - for low-level read issues, or JsonParseException for decoding problems

    • readValues

      public <T> Iterator<T> readValues(JsonParser p, JavaType valueType) throws 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:
      IOException

    • createArrayNode

      public JsonNode createArrayNode()
      Description copied from class: ObjectCodec
      Method for construct root level Array nodes for Tree Model instances.
      Specified by:
      createArrayNode in class ObjectCodec
      Returns:
      Array node created

    • createObjectNode

      public JsonNode createObjectNode()
      Description copied from class: ObjectCodec
      Method for construct root level Object nodes for Tree Model instances.
      Specified by:
      createObjectNode in class ObjectCodec
      Returns:
      Object node created

    • missingNode

      public JsonNode missingNode()
      Overrides:
      missingNode in class TreeCodec
      Returns:
      Node that represents "missing" node during traversal: something referenced but that does not exist in content model

    • nullNode

      public JsonNode nullNode()
      Overrides:
      nullNode in class TreeCodec
      Returns:
      Node that represents explict null value in content

    • treeAsTokens

      public JsonParser treeAsTokens(TreeNode n)
      Description copied from class: ObjectCodec
      Method for constructing a JsonParser for reading contents of a JSON tree, as if it was external serialized JSON content.
      Specified by:
      treeAsTokens in class ObjectCodec
      Parameters:
      n - Content to traverse over
      Returns:
      Parser constructed for traversing over contents of specified node

    • readTree

      public <T extends TreeNode> T readTree(JsonParser p) throws 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:
      IOException - for low-level read issues, or JsonParseException for decoding problems

    • writeTree

      public void writeTree(JsonGenerator g, TreeNode rootNode)
      Description copied from class: ObjectCodec
      Method for serializing JSON content from given Tree instance, using specified generator.
      Specified by:
      writeTree in class ObjectCodec
      Parameters:
      g - Generator to use for serializing value
      rootNode - Tree to serialize

    • readValue

      public <T> T readValue(InputStream src) throws 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).
      Parameters:
      src - Source to read content from
      Throws:
      IOException

    • readValue

      public <T> T readValue(InputStream src, Class<T> valueType) throws IOException
      Same as readValue(InputStream) except that target value type overridden as valueType
      Parameters:
      src - Source to read content from
      valueType - Target type to bind content to
      Throws:
      IOException
      Since:
      2.11

    • readValue

      public <T> T readValue(Reader src) throws 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).
      Parameters:
      src - Source to read content from
      Throws:
      IOException

    • readValue

      public <T> T readValue(Reader src, Class<T> valueType) throws IOException
      Same as readValue(Reader) except that target value type overridden as valueType
      Parameters:
      src - Source to read content from
      valueType - Target type to bind content to
      Throws:
      IOException
      Since:
      2.11

    • readValue

      public <T> T readValue(String src) throws JsonProcessingException, JsonMappingException
      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).
      Parameters:
      src - String that contains content to read
      Throws:
      JsonProcessingException
      JsonMappingException

    • readValue

      public <T> T readValue(String src, Class<T> valueType) throws IOException
      Same as readValue(String) except that target value type overridden as valueType
      Parameters:
      src - String that contains content to read
      valueType - Target type to bind content to
      Throws:
      IOException
      Since:
      2.11

    • readValue

      public <T> T readValue(byte[] content) throws 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).
      Parameters:
      content - Byte array that contains encoded content to read
      Throws:
      IOException

    • readValue

      public <T> T readValue(byte[] content, Class<T> valueType) throws IOException
      Same as readValue(byte[]) except that target value type overridden as valueType
      Parameters:
      content - Byte array that contains encoded content to read
      valueType - Target type to bind content to
      Throws:
      IOException
      Since:
      2.11

    • readValue

      public <T> T readValue(byte[] buffer, int offset, int length) throws 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).
      Parameters:
      buffer - Byte array that contains encoded content to read
      offset - Offset of the first content byte in buffer
      length - Length of content in buffer, in bytes
      Throws:
      IOException

    • readValue

      public <T> T readValue(byte[] buffer, int offset, int length, Class<T> valueType) throws IOException
      Same as readValue(byte[],int,int) except that target value type overridden as valueType
      Parameters:
      buffer - Byte array that contains encoded content to read
      offset - Offset of the first content byte in buffer
      length - Length of content in buffer, in bytes
      valueType - Target type to bind content to
      Throws:
      IOException
      Since:
      2.11

    • readValue

      public <T> T readValue(File src) throws IOException
      Method that binds content read from given File using configuration of this reader. Value return is either newly constructed, or root value that was specified with withValueToUpdate(Object).
      Parameters:
      src - File that contains content to read
      Throws:
      IOException

    • readValue

      public <T> T readValue(File src, Class<T> valueType) throws IOException
      Same as readValue(File) except that target value type overridden as valueType
      Parameters:
      src - File that contains content to read
      valueType - Target type to bind content to
      Throws:
      IOException
      Since:
      2.11

    • readValue

      public <T> T readValue(URL src) throws 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:
      IOException

    • readValue

      public <T> T readValue(URL src, Class<T> valueType) throws IOException
      Same as readValue(URL) except that target value type overridden as valueType
      Parameters:
      src - URL pointing to resource that contains content to read
      valueType - Target type to bind content to
      Throws:
      IOException
      Since:
      2.11

    • readValue

      public <T> T readValue(JsonNode content) throws IOException
      Convenience method for converting results from given JSON tree into given value type. Basically short-cut for: 
         objectReader.readValue(src.traverse())
      Parameters:
      content - Tree that contains content to convert
      Throws:
      IOException

    • readValue

      public <T> T readValue(JsonNode content, Class<T> valueType) throws IOException
      Same as readValue(JsonNode) except that target value type overridden as valueType
      Parameters:
      content - Tree that contains content to convert
      valueType - Target type to convert content to
      Throws:
      IOException
      Since:
      2.11

    • readValue

      public <T> T readValue(DataInput src) throws IOException
      Throws:
      IOException

    • readValue

      public <T> T readValue(DataInput content, Class<T> valueType) throws IOException
      Same as readValue(DataInput) except that target value type overridden as valueType
      Parameters:
      content - DataInput that contains content to read
      valueType - Target type to bind content to
      Throws:
      IOException
      Since:
      2.11

    • readTree

      public JsonNode readTree(InputStream src) throws 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 JsonNode 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:
      IOException

    • readTree

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

    • readTree

      public JsonNode readTree(String json) throws JsonProcessingException, JsonMappingException
      Same as readTree(InputStream) except content read from passed-in String
      Throws:
      JsonProcessingException
      JsonMappingException

    • readTree

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

    • readTree

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

    • readTree

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

    • readValues

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

    • readValues

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

    • readValues

      public <T> MappingIterator<T> readValues(Reader src) throws IOException
      Overloaded version of readValue(InputStream).
      Throws:
      IOException

    • readValues

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

    • readValues

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

    • readValues

      public final <T> MappingIterator<T> readValues(byte[] src) throws IOException
      Overloaded version of readValue(InputStream).
      Throws:
      IOException

    • readValues

      public <T> MappingIterator<T> readValues(File src) throws IOException
      Overloaded version of readValue(InputStream).
      Throws:
      IOException

    • readValues

      public <T> MappingIterator<T> readValues(URL src) throws 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:
      IOException

    • readValues

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

    • treeToValue

      public <T> T treeToValue(TreeNode n, Class<T> valueType) throws JsonProcessingException
      Description copied from class: ObjectCodec
      Convenience method for converting given JSON tree into instance of specified value type. This is equivalent to first constructing a JsonParser to iterate over contents of the tree, and using that parser for data binding.
      Specified by:
      treeToValue in class ObjectCodec
      Type Parameters:
      T - Nominal parameter for target type
      Parameters:
      n - Tree to convert
      valueType - Java target value type to convert content to
      Returns:
      Converted value instance
      Throws:
      JsonProcessingException - if structural conversion fails

    • treeToValue

      public <T> T treeToValue(TreeNode n, JavaType valueType) throws JsonProcessingException
      Same as treeToValue(TreeNode, Class) but with type-resolved target value type.
      Throws:
      JsonProcessingException
      Since:
      2.13

    • writeValue

      public void writeValue(JsonGenerator gen, Object value) throws IOException
      Description copied from class: ObjectCodec
      Method to serialize given Java Object, using generator provided.
      Specified by:
      writeValue in class ObjectCodec
      Parameters:
      gen - Generator to use for serializing value
      value - Value to serialize
      Throws:
      IOException - for low-level write issues, or JsonGenerationException for decoding problems

    • _bind

      protected Object _bind(JsonParser p, Object valueToUpdate) throws IOException
      Actual implementation of value reading+binding operation.
      Throws:
      IOException

    • _bindAndClose

      protected Object _bindAndClose(JsonParser p0) throws IOException
      Throws:
      IOException

    • _bindAndCloseAsTree

      protected final JsonNode _bindAndCloseAsTree(JsonParser p0) throws IOException
      Throws:
      IOException

    • _bindAsTree

      protected final JsonNode _bindAsTree(JsonParser p) throws IOException
      Throws:
      IOException

    • _bindAsTreeOrNull

      protected final JsonNode _bindAsTreeOrNull(JsonParser p) throws IOException
      Same as _bindAsTree(edu.internet2.middleware.grouperClientExt.com.fasterxml.jackson.core.JsonParser) except end-of-input is reported by returning null, not "missing node"
      Throws:
      IOException

    • _bindAndReadValues

      protected <T> MappingIterator<T> _bindAndReadValues(JsonParser p) throws IOException
      Throws:
      IOException
      Since:
      2.1

    • _considerFilter

      protected JsonParser _considerFilter(JsonParser p, boolean multiValue)
      Consider filter when creating JsonParser.

    • _verifyNoTrailingTokens

      protected final void _verifyNoTrailingTokens(JsonParser p, DeserializationContext ctxt, JavaType bindType) throws IOException
      Throws:
      IOException
      Since:
      2.9

    • _detectBindAndClose

      protected Object _detectBindAndClose(byte[] src, int offset, int length) throws IOException
      Throws:
      IOException

    • _detectBindAndClose

      protected Object _detectBindAndClose(DataFormatReaders.Match match, boolean forceClosing) throws IOException
      Throws:
      IOException

    • _detectBindAndReadValues

      protected <T> MappingIterator<T> _detectBindAndReadValues(DataFormatReaders.Match match, boolean forceClosing) throws IOException
      Throws:
      IOException

    • _detectBindAndCloseAsTree

      protected JsonNode _detectBindAndCloseAsTree(InputStream in) throws IOException
      Throws:
      IOException

    • _reportUnkownFormat

      protected void _reportUnkownFormat(DataFormatReaders detector, DataFormatReaders.Match match) throws IOException
      Method called to indicate that format detection failed to detect format of given input
      Throws:
      IOException

    • _verifySchemaType

      protected void _verifySchemaType(FormatSchema schema)
      Since:
      2.2

    • createDeserializationContext

      protected DefaultDeserializationContext createDeserializationContext(JsonParser p)
      Internal helper method called to create an instance of DeserializationContext for deserializing a single root value. Can be overridden if a custom context is needed.

    • createDummyDeserializationContext

      protected DefaultDeserializationContext createDummyDeserializationContext()

    • _inputStream

      protected InputStream _inputStream(URL src) throws IOException
      Throws:
      IOException

    • _inputStream

      protected InputStream _inputStream(File f) throws IOException
      Throws:
      IOException

    • _reportUndetectableSource

      protected void _reportUndetectableSource(Object src) throws StreamReadException
      Throws:
      StreamReadException

    • _findRootDeserializer

      protected JsonDeserializer<Object> _findRootDeserializer(DeserializationContext ctxt) throws DatabindException
      Method called to locate deserializer for the passed root-level value.
      Throws:
      DatabindException

    • _findTreeDeserializer

      protected JsonDeserializer<Object> _findTreeDeserializer(DeserializationContext ctxt) throws DatabindException
      Throws:
      DatabindException
      Since:
      2.6

    • _prefetchRootDeserializer

      protected JsonDeserializer<Object> _prefetchRootDeserializer(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.

    • _jsonNodeType

      protected final JavaType _jsonNodeType()
      Since:
      2.10

    • _assertNotNull

      protected final void _assertNotNull(String paramName, Object src)