MappingIterator
Date: 2016-12-04

com.fasterxml.jackson.databind

## Class MappingIterator<T>

- java.lang.Object
- - com.fasterxml.jackson.databind.MappingIterator<T>

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.util.Iterator<T>

      public class MappingIterator<T>
      extends java.lang.Object
      implements java.util.Iterator<T>, java.io.Closeable

  Iterator exposed by `ObjectMapper` when binding sequence of objects. Extension is done to allow more convenient exposing of `IOException` (which basic `Iterator` does not expose)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `_closeParser` Flag that indicates whether input `JsonParser` should be closed when we are done or not; generally only called when caller did not pass JsonParser.
    `protected DeserializationContext` | `_context` Context for deserialization, needed to pass through to deserializer
    `protected JsonDeserializer<T>` | `_deserializer` Deserializer for individual element values.
    `protected com.fasterxml.jackson.core.JsonParser` | `_parser` Underlying parser used for reading content to bind.
    `protected com.fasterxml.jackson.core.JsonStreamContext` | `_seqContext` Context to resynchronize to, in case an exception is encountered but caller wants to try to read more elements.
    `protected int` | `_state` State of the iterator
    `protected JavaType` | `_type` Type to bind individual elements to.
    `protected T` | `_updatedValue` If not null, "value to update" instead of creating a new instance for each call.
    `protected static MappingIterator<?>` | `EMPTY_ITERATOR`
    `protected static int` | `STATE_CLOSED` State in which iterator is closed
    `protected static int` | `STATE_HAS_VALUE` State in which "hasNextValue()" has been succesfully called and deserializer can be called to fetch value
    `protected static int` | `STATE_MAY_HAVE_VALUE` State in which no recovery is needed, but "hasNextValue()" needs to be called first
    `protected static int` | `STATE_NEED_RESYNC` State in which value read failed

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `MappingIterator(JavaType type, com.fasterxml.jackson.core.JsonParser p, DeserializationContext ctxt, JsonDeserializer<?> deser, boolean managedParser, java.lang.Object valueToUpdate)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected <R> R` | `_handleIOException(java.io.IOException e)`
    `protected <R> R` | `_handleMappingException(JsonMappingException e)`
    `protected void` | `_resync()`
    `protected <R> R` | `_throwNoSuchElement()`
    `void` | `close()`
    `protected static <T> MappingIterator<T>` | `emptyIterator()`
    `com.fasterxml.jackson.core.JsonLocation` | `getCurrentLocation()` Convenience method, functionally equivalent to: `iterator.getParser().getCurrentLocation()`
    `com.fasterxml.jackson.core.JsonParser` | `getParser()` Accessor for getting underlying parser this iterator uses.
    `com.fasterxml.jackson.core.FormatSchema` | `getParserSchema()` Accessor for accessing `FormatSchema` that the underlying parser (as per `getParser()`) is using, if any; only parser of schema-aware formats use schemas.
    `boolean` | `hasNext()`
    `boolean` | `hasNextValue()` Equivalent of `next()` but one that may throw checked exceptions from Jackson due to invalid input.
    `T` | `next()`
    `T` | `nextValue()`
    `java.util.List<T>` | `readAll()` Convenience method for reading all entries accessible via this iterator; resulting container will be a `ArrayList`.
    `<C extends java.util.Collection<? super T>> C` | `readAll(C results)` Convenience method for reading all entries accessible via this iterator
    `<L extends java.util.List<? super T>> L` | `readAll(L resultList)` Convenience method for reading all entries accessible via this iterator
    `void` | `remove()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY_ITERATOR

          protected static final MappingIterator<?> EMPTY_ITERATOR

    - #### STATE_CLOSED

          protected static final int STATE_CLOSED

      State in which iterator is closed
      See Also:
        Constant Field Values

    - #### STATE_NEED_RESYNC

          protected static final int STATE_NEED_RESYNC

      State in which value read failed
      See Also:
        Constant Field Values

    - #### STATE_MAY_HAVE_VALUE

          protected static final int STATE_MAY_HAVE_VALUE

      State in which no recovery is needed, but "hasNextValue()" needs to be called first
      See Also:
        Constant Field Values

    - #### STATE_HAS_VALUE

          protected static final int STATE_HAS_VALUE

      State in which "hasNextValue()" has been succesfully called and deserializer can be called to fetch value
      See Also:
        Constant Field Values

    - #### _type

          protected final JavaType _type

      Type to bind individual elements to.

    - #### _context

          protected final DeserializationContext _context

      Context for deserialization, needed to pass through to deserializer

    - #### _deserializer

          protected final JsonDeserializer<T> _deserializer

      Deserializer for individual element values.

    - #### _parser

          protected final com.fasterxml.jackson.core.JsonParser _parser

      Underlying parser used for reading content to bind. Initialized as not `null` but set as `null` when iterator is closed, to denote closing.

    - #### _seqContext

          protected final com.fasterxml.jackson.core.JsonStreamContext _seqContext

      Context to resynchronize to, in case an exception is encountered but caller wants to try to read more elements.

    - #### _updatedValue

          protected final T _updatedValue

      If not null, "value to update" instead of creating a new instance for each call.

    - #### _closeParser

          protected final boolean _closeParser

      Flag that indicates whether input `JsonParser` should be closed when we are done or not; generally only called when caller did not pass JsonParser.

    - #### _state

          protected int _state

      State of the iterator

  - ### Constructor Detail

    - #### MappingIterator

          protected MappingIterator(JavaType type,
                         com.fasterxml.jackson.core.JsonParser p,
                         DeserializationContext ctxt,
                         JsonDeserializer<?> deser,
                         boolean managedParser,
                         java.lang.Object valueToUpdate)

      Parameters:
        `managedParser` - Whether we "own" the `JsonParser` passed or not: if true, it was created by `ObjectReader` and code here needs to close it; if false, it was passed by calling code and should not be closed by iterator.

  - ### Method Detail

    - #### emptyIterator

          protected static <T> MappingIterator<T> emptyIterator()

    - #### hasNext

          public boolean hasNext()

      Specified by:
        `hasNext` in interface `java.util.Iterator<T>`

    - #### next

          public T next()

      Specified by:
        `next` in interface `java.util.Iterator<T>`

    - #### remove

          public void remove()

      Specified by:
        `remove` in interface `java.util.Iterator<T>`

    - #### close

          public void close()
                     throws java.io.IOException

      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `java.io.IOException`

    - #### hasNextValue

          public boolean hasNextValue()
                               throws java.io.IOException

      Equivalent of `next()` but one that may throw checked exceptions from Jackson due to invalid input.
      Throws:
        `java.io.IOException`

    - #### nextValue

          public T nextValue()
                      throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### readAll

          public java.util.List<T> readAll()
                                    throws java.io.IOException

      Convenience method for reading all entries accessible via this iterator; resulting container will be a `ArrayList`.
      Returns:
        List of entries read
      Throws:
        `java.io.IOException`
      Since:
        2.2

    - #### readAll

          public <L extends java.util.List<? super T>> L readAll(L resultList)
                                           throws java.io.IOException

      Convenience method for reading all entries accessible via this iterator
      Returns:
        List of entries read (same as passed-in argument)
      Throws:
        `java.io.IOException`
      Since:
        2.2

    - #### readAll

          public <C extends java.util.Collection<? super T>> C readAll(C results)
                                                 throws java.io.IOException

      Convenience method for reading all entries accessible via this iterator
      Throws:
        `java.io.IOException`
      Since:
        2.5

    - #### getParser

          public com.fasterxml.jackson.core.JsonParser getParser()

      Accessor for getting underlying parser this iterator uses.
      Since:
        2.2

    - #### getParserSchema

          public com.fasterxml.jackson.core.FormatSchema getParserSchema()

      Accessor for accessing `FormatSchema` that the underlying parser (as per `getParser()`) is using, if any; only parser of schema-aware formats use schemas.
      Since:
        2.2

    - #### getCurrentLocation

          public com.fasterxml.jackson.core.JsonLocation getCurrentLocation()

      Convenience method, functionally equivalent to: `iterator.getParser().getCurrentLocation()`
      Returns:
        Location of the input stream of the underlying parser
      Since:
        2.2.1

    - #### _resync

          protected void _resync()
                          throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### _throwNoSuchElement

          protected <R> R _throwNoSuchElement()

    - #### _handleMappingException

          protected <R> R _handleMappingException(JsonMappingException e)

    - #### _handleIOException

          protected <R> R _handleIOException(java.io.IOException e)