JsonParserSequence
Date: 2016-12-03

com.fasterxml.jackson.core.util

## Class JsonParserSequence

- java.lang.Object
- - com.fasterxml.jackson.core.JsonParser
  - - com.fasterxml.jackson.core.util.JsonParserDelegate
    - - com.fasterxml.jackson.core.util.JsonParserSequence

- All Implemented Interfaces:
    Versioned, java.io.Closeable, java.lang.AutoCloseable

      public class JsonParserSequence
      extends JsonParserDelegate

  Helper class that can be used to sequence multiple physical `JsonParser`s to create a single logical sequence of tokens, as a single `JsonParser`.

  Fairly simple use of `JsonParserDelegate`: only need to override `nextToken()` to handle transition

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class com.fasterxml.jackson.core.JsonParser

      `JsonParser.Feature, JsonParser.NumberType`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `_checkForExistingToken` Configuration that determines whether state of parsers is first verified to see if parser already points to a token (that is, `JsonParser.hasCurrentToken()` returns `true`), and if so that token is first return before `JsonParser.nextToken()` is called.
    `protected boolean` | `_hasToken` Flag used to indicate that `JsonParser.nextToken()` should not be called, due to parser already pointing to a token.
    `protected int` | `_nextParserIndex` Index of the next parser in `_parsers`.
    `protected JsonParser[]` | `_parsers` Parsers other than the first one (which is initially assigned as delegate)

    - ### Fields inherited from class com.fasterxml.jackson.core.util.JsonParserDelegate

      `delegate`

    - ### Fields inherited from class com.fasterxml.jackson.core.JsonParser

      `_features, _requestPayload`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `JsonParserSequence(boolean checkForExistingToken, JsonParser[] parsers)`
    `protected` | `JsonParserSequence(JsonParser[] parsers)` Deprecated.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addFlattenedActiveParsers(java.util.List<JsonParser> listToAddIn)`
    `void` | `close()` Closes the parser so that no further iteration or data access can be made; will also close the underlying input source if parser either owns the input source, or feature `JsonParser.Feature.AUTO_CLOSE_SOURCE` is enabled.
    `int` | `containedParsersCount()` Method that is most useful for debugging or testing; returns actual number of underlying parsers sequence was constructed with (nor just ones remaining active)
    `static JsonParserSequence` | `createFlattened(boolean checkForExistingToken, JsonParser first, JsonParser second)` Method that will construct a parser (possibly a sequence) that contains all given sub-parsers.
    `static JsonParserSequence` | `createFlattened(JsonParser first, JsonParser second)` Deprecated. Since 2.8 use `createFlattened(boolean, JsonParser, JsonParser)` instead
    `JsonToken` | `nextToken()` Main iteration method, which will advance stream enough to determine type of the next token, if any.
    `protected JsonToken` | `switchAndReturnNext()`
    `protected boolean` | `switchToNext()` Method that will switch active delegate parser from the current one to the next parser in sequence, if there is another parser left: if so, the next parser will become the active delegate parser.

    - ### Methods inherited from class com.fasterxml.jackson.core.util.JsonParserDelegate

      `canReadObjectId, canReadTypeId, canUseSchema, clearCurrentToken, currentToken, currentTokenId, disable, enable, finishToken, getBigIntegerValue, getBinaryValue, getBooleanValue, getByteValue, getCodec, getCurrentLocation, getCurrentName, getCurrentToken, getCurrentTokenId, getCurrentValue, getDecimalValue, getDoubleValue, getEmbeddedObject, getFeatureMask, getFloatValue, getInputSource, getIntValue, getLastClearedToken, getLongValue, getNumberType, getNumberValue, getObjectId, getParsingContext, getSchema, getShortValue, getText, getText, getTextCharacters, getTextLength, getTextOffset, getTokenLocation, getTypeId, getValueAsBoolean, getValueAsBoolean, getValueAsDouble, getValueAsDouble, getValueAsInt, getValueAsInt, getValueAsLong, getValueAsLong, getValueAsString, getValueAsString, hasCurrentToken, hasTextCharacters, hasToken, hasTokenId, isClosed, isEnabled, isExpectedStartArrayToken, isExpectedStartObjectToken, nextValue, overrideCurrentName, overrideFormatFeatures, overrideStdFeatures, readBinaryValue, requiresCustomCodec, setCodec, setCurrentValue, setFeatureMask, setSchema, skipChildren, version`

    - ### Methods inherited from class com.fasterxml.jackson.core.JsonParser

      `_codec, _constructError, _reportUnsupportedOperation, configure, getBinaryValue, getFormatFeatures, nextBooleanValue, nextFieldName, nextFieldName, nextIntValue, nextLongValue, nextTextValue, readBinaryValue, readValueAs, readValueAs, readValueAsTree, readValuesAs, readValuesAs, releaseBuffered, releaseBuffered, setRequestPayloadOnError, setRequestPayloadOnError, setRequestPayloadOnError`

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

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

- - ### Field Detail

    - #### _parsers

          protected final JsonParser[] _parsers

      Parsers other than the first one (which is initially assigned as delegate)

    - #### _checkForExistingToken

          protected final boolean _checkForExistingToken

      Configuration that determines whether state of parsers is first verified to see if parser already points to a token (that is, `JsonParser.hasCurrentToken()` returns `true`), and if so that token is first return before `JsonParser.nextToken()` is called. If enabled, this check is made; if disabled, no check is made and `JsonParser.nextToken()` is always called for all parsers.

      Default setting is `false` (for backwards-compatibility) so that possible existing token is not considered for parsers.

      Since:
        2.8

    - #### _nextParserIndex

          protected int _nextParserIndex

      Index of the next parser in `_parsers`.

    - #### _hasToken

          protected boolean _hasToken

      Flag used to indicate that `JsonParser.nextToken()` should not be called, due to parser already pointing to a token.
      Since:
        2.8

  - ### Constructor Detail

    - #### JsonParserSequence

          @Deprecated
          protected JsonParserSequence(JsonParser[] parsers)

      Deprecated.

    - #### JsonParserSequence

          protected JsonParserSequence(boolean checkForExistingToken,
                            JsonParser[] parsers)

      Since:
        2.8

  - ### Method Detail

    - #### createFlattened

          public static JsonParserSequence createFlattened(boolean checkForExistingToken,
                                           JsonParser first,
                                           JsonParser second)

      Method that will construct a parser (possibly a sequence) that contains all given sub-parsers. All parsers given are checked to see if they are sequences: and if so, they will be "flattened", that is, contained parsers are directly added in a new sequence instead of adding sequences within sequences. This is done to minimize delegation depth, ideally only having just a single level of delegation.

    - #### createFlattened

          @Deprecated
          public static JsonParserSequence createFlattened(JsonParser first,
                                                      JsonParser second)

      Deprecated. Since 2.8 use `createFlattened(boolean, JsonParser, JsonParser)` instead

    - #### addFlattenedActiveParsers

          protected void addFlattenedActiveParsers(java.util.List<JsonParser> listToAddIn)

    - #### close

          public void close()
                     throws java.io.IOException

      Description copied from class: `JsonParser`
      Closes the parser so that no further iteration or data access can be made; will also close the underlying input source if parser either owns the input source, or feature `JsonParser.Feature.AUTO_CLOSE_SOURCE` is enabled. Whether parser owns the input source depends on factory method that was used to construct instance (so check `JsonFactory` for details, but the general idea is that if caller passes in closable resource (such as `InputStream` or `Reader`) parser does NOT own the source; but if it passes a reference (such as `File` or `URL` and creates stream or reader it does own them.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `JsonParserDelegate`
      Throws:
        `java.io.IOException`

    - #### nextToken

          public JsonToken nextToken()
                              throws java.io.IOException

      Description copied from class: `JsonParser`
      Main iteration method, which will advance stream enough to determine type of the next token, if any. If none remaining (stream has no content other than possible white space before ending), null will be returned.
      Overrides:
        `nextToken` in class `JsonParserDelegate`
      Returns:
        Next token from the stream, if any found, or null to indicate end-of-input
      Throws:
        `java.io.IOException`

    - #### containedParsersCount

          public int containedParsersCount()

      Method that is most useful for debugging or testing; returns actual number of underlying parsers sequence was constructed with (nor just ones remaining active)

    - #### switchToNext

          protected boolean switchToNext()

      Method that will switch active delegate parser from the current one to the next parser in sequence, if there is another parser left: if so, the next parser will become the active delegate parser.
      Returns:
        True if switch succeeded; false otherwise
      Since:
        2.8

    - #### switchAndReturnNext

          protected JsonToken switchAndReturnNext()
                                           throws java.io.IOException

      Throws:
        `java.io.IOException`