JsonStreamContext (Jackson-core 2.14.0 API)

com.fasterxml.jackson.core

## Class JsonStreamContext

- java.lang.Object
- - com.fasterxml.jackson.core.JsonStreamContext

- Direct Known Subclasses:
    JsonReadContext, JsonWriteContext, TokenFilterContext

      public abstract class JsonStreamContext
      extends Object

  Shared base class for streaming processing contexts used during reading and writing of Json content using Streaming API. This context is also exposed to applications: context object can be used by applications to get an idea of relative position of the parser/generator within json content being processed. This allows for some contextual processing: for example, output within Array context can differ from that of Object context.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `_index` Index of the currently processed entry.
    `protected int` | `_type` Indicates logical type of context as one of `TYPE_xxx` constants.
    `static int` | `TYPE_ARRAY` Indicator for "Array" context.
    `static int` | `TYPE_OBJECT` Indicator for "Object" context.
    `static int` | `TYPE_ROOT` Indicator for "Root Value" context (has not parent)

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `JsonStreamContext()`
    `protected` | `JsonStreamContext(int type, int index)`
    `protected` | `JsonStreamContext(JsonStreamContext base)` Copy constructor used by sub-classes for creating copies for buffering.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getCurrentIndex()`
    `abstract String` | `getCurrentName()` Method for accessing name associated with the current location.
    `Object` | `getCurrentValue()` Method for accessing currently active value being used by data-binding (as the source of streaming data to write, or destination of data being read), at this level in hierarchy.
    `int` | `getEntryCount()`
    `abstract JsonStreamContext` | `getParent()` Accessor for finding parent context of this context; will return null for root context.
    `JsonLocation` | `getStartLocation(Object srcRef)` Deprecated. Since 2.13 use `startLocation(com.fasterxml.jackson.core.io.ContentReference)` instead
    `String` | `getTypeDesc()` Deprecated. Since 2.8 use `typeDesc()` instead
    `boolean` | `hasCurrentIndex()` Method that may be called to verify whether this context has valid index: will return `false` before the first entry of Object context or before first element of Array context; otherwise returns `true`.
    `boolean` | `hasCurrentName()`
    `boolean` | `hasPathSegment()` Method that may be called to check if this context is either: Object, with at least one entry written (partially or completely) Array, with at least one entry written (partially or completely) and if so, return `true`; otherwise return `false`.
    `boolean` | `inArray()` Method that returns true if this context is an Array context; that is, content is being read from or written to a JSON Array.
    `boolean` | `inObject()` Method that returns true if this context is an Object context; that is, content is being read from or written to a JSON Object.
    `boolean` | `inRoot()` Method that returns true if this context is a Root context; that is, content is being read from or written to without enclosing array or object structure.
    `JsonPointer` | `pathAsPointer()` Factory method for constructing a `JsonPointer` that points to the current location within the stream that this context is for, excluding information about "root context" (only relevant for multi-root-value cases)
    `JsonPointer` | `pathAsPointer(boolean includeRoot)` Factory method for constructing a `JsonPointer` that points to the current location within the stream that this context is for, optionally including "root value index"
    `void` | `setCurrentValue(Object v)` Method to call to pass value to be returned via `getCurrentValue()`; typically called indirectly through `JsonParser.setCurrentValue(java.lang.Object)` or `JsonGenerator.setCurrentValue(java.lang.Object)`).
    `JsonLocation` | `startLocation(ContentReference srcRef)` Optional method that may be used to access starting location of this context: for example, in case of JSON `Object` context, offset at which `[` token was read or written.
    `String` | `toString()` Overridden to provide developer readable "JsonPath" representation of the context.
    `String` | `typeDesc()` Method for accessing simple type description of current context; either ROOT (for root-level values), OBJECT (for field names and values of JSON Objects) or ARRAY (for values of JSON Arrays)

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

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

- - ### Field Detail

    - #### TYPE_ROOT

          public static final int TYPE_ROOT

      Indicator for "Root Value" context (has not parent)
      See Also:
        Constant Field Values

    - #### TYPE_ARRAY

          public static final int TYPE_ARRAY

      Indicator for "Array" context.
      See Also:
        Constant Field Values

    - #### TYPE_OBJECT

          public static final int TYPE_OBJECT

      Indicator for "Object" context.
      See Also:
        Constant Field Values

    - #### _type

          protected int _type

      Indicates logical type of context as one of `TYPE_xxx` constants.

    - #### _index

          protected int _index

      Index of the currently processed entry. Starts with -1 to signal that no entries have been started, and gets advanced each time a new entry is started, either by encountering an expected separator, or with new values if no separators are expected (the case for root context).

  - ### Constructor Detail

    - #### JsonStreamContext

          protected JsonStreamContext()

    - #### JsonStreamContext

          protected JsonStreamContext(JsonStreamContext base)

      Copy constructor used by sub-classes for creating copies for buffering.
      Parameters:
        `base` - Context instance to copy type and index from
      Since:
        2.9

    - #### JsonStreamContext

          protected JsonStreamContext(int type,
                                      int index)

  - ### Method Detail

    - #### getParent

          public abstract JsonStreamContext getParent()

      Accessor for finding parent context of this context; will return null for root context.
      Returns:
        Parent context of this context, if any; `null` for Root contexts

    - #### inArray

          public final boolean inArray()

      Method that returns true if this context is an Array context; that is, content is being read from or written to a JSON Array.
      Returns:
        `True` if this context represents an Array; `false` otherwise

    - #### inRoot

          public final boolean inRoot()

      Method that returns true if this context is a Root context; that is, content is being read from or written to without enclosing array or object structure.
      Returns:
        `True` if this context represents a sequence of Root values; `false` otherwise

    - #### inObject

          public final boolean inObject()

      Method that returns true if this context is an Object context; that is, content is being read from or written to a JSON Object.
      Returns:
        `True` if this context represents an Object; `false` otherwise

    - #### getTypeDesc

          @Deprecated
          public final String getTypeDesc()

      Deprecated. Since 2.8 use `typeDesc()` instead
      Returns:
        Type description String

    - #### typeDesc

          public String typeDesc()

      Method for accessing simple type description of current context; either ROOT (for root-level values), OBJECT (for field names and values of JSON Objects) or ARRAY (for values of JSON Arrays)
      Returns:
        Type description String
      Since:
        2.8

    - #### getEntryCount

          public final int getEntryCount()

      Returns:
        Number of entries that are complete and started.

    - #### getCurrentIndex

          public final int getCurrentIndex()

      Returns:
        Index of the currently processed entry, if any

    - #### hasCurrentIndex

          public boolean hasCurrentIndex()

      Method that may be called to verify whether this context has valid index: will return `false` before the first entry of Object context or before first element of Array context; otherwise returns `true`.
      Returns:
        `True` if this context has value index to access, `false` otherwise
      Since:
        2.9

    - #### hasPathSegment

          public boolean hasPathSegment()

      Method that may be called to check if this context is either:
      - Object, with at least one entry written (partially or completely)
      - Array, with at least one entry written (partially or completely)
      and if so, return `true`; otherwise return `false`. Latter case includes Root context (always), and Object/Array contexts before any entries/elements have been read or written.

      Method is mostly used to determine whether this context should be used for constructing `JsonPointer`

      Returns:
        `True` if this context has value path segment to access, `false` otherwise
      Since:
        2.9

    - #### getCurrentName

          public abstract String getCurrentName()

      Method for accessing name associated with the current location. Non-null for `FIELD_NAME` and value events that directly follow field names; null for root level and array values.
      Returns:
        Current field name within context, if any; `null` if none

    - #### hasCurrentName

          public boolean hasCurrentName()

      Returns:
        `True` if a call to `getCurrentName()` would return non-`null` name; `false` otherwise
      Since:
        2.9

    - #### getCurrentValue

          public Object getCurrentValue()

      Method for accessing currently active value being used by data-binding (as the source of streaming data to write, or destination of data being read), at this level in hierarchy.

      Note that "current value" is NOT populated (or used) by Streaming parser or generator; it is only used by higher-level data-binding functionality. The reason it is included here is that it can be stored and accessed hierarchically, and gets passed through data-binding.

      Returns:
        Currently active value, if one has been assigned.
      Since:
        2.5

    - #### setCurrentValue

          public void setCurrentValue(Object v)

      Method to call to pass value to be returned via `getCurrentValue()`; typically called indirectly through `JsonParser.setCurrentValue(java.lang.Object)` or `JsonGenerator.setCurrentValue(java.lang.Object)`).
      Parameters:
        `v` - Current value to assign to this context
      Since:
        2.5

    - #### pathAsPointer

          public JsonPointer pathAsPointer()

      Factory method for constructing a `JsonPointer` that points to the current location within the stream that this context is for, excluding information about "root context" (only relevant for multi-root-value cases)
      Returns:
        Pointer instance constructed
      Since:
        2.9

    - #### pathAsPointer

          public JsonPointer pathAsPointer(boolean includeRoot)

      Factory method for constructing a `JsonPointer` that points to the current location within the stream that this context is for, optionally including "root value index"
      Parameters:
        `includeRoot` - Whether root-value offset is included as the first segment or not;
      Returns:
        Pointer instance constructed
      Since:
        2.9

    - #### startLocation

          public JsonLocation startLocation(ContentReference srcRef)

      Optional method that may be used to access starting location of this context: for example, in case of JSON `Object` context, offset at which `[` token was read or written. Often used for error reporting purposes. Implementations that do not keep track of such location are expected to return `JsonLocation.NA`; this is what the default implementation does.
      Parameters:
        `srcRef` - Source reference needed to construct location instance
      Returns:
        Location pointing to the point where the context start marker was found (or written); never `null`.
      Since:
        2.13

    - #### getStartLocation

          @Deprecated
          public JsonLocation getStartLocation(Object srcRef)

      Deprecated. Since 2.13 use `startLocation(com.fasterxml.jackson.core.io.ContentReference)` instead
      Parameters:
        `srcRef` - Source reference needed to construct location instance
      Returns:
        Location pointing to the point where the context start marker was found (or written); never `null`.
      Since:
        2.9

    - #### toString

          public String toString()

      Overridden to provide developer readable "JsonPath" representation of the context.
      Overrides:
        `toString` in class `Object`
      Returns:
        Simple developer-readable description this context layer (note: NOT constructed with parents, unlike `pathAsPointer()`)
      Since:
        2.9

Copyright © 2008–2022 FasterXML. All rights reserved.