Module tools.jackson.core
Package tools.jackson.core

Class TokenStreamContext

java.lang.Object
tools.jackson.core.TokenStreamContext
Direct Known Subclasses:
JsonReadContext, JsonWriteContext, SimpleStreamReadContext, SimpleStreamWriteContext, TokenFilterContext
public abstract class TokenStreamContext extends Object
Shared base class for streaming processing contexts used during reading and writing of token streams 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 content being processed. This allows for some contextual processing: for example, output within Array context can differ from that of Object context. Perhaps more importantly context is hierarchic so that enclosing contexts can be inspected as well. All levels also include information about current property name (for Objects) and element index (for Arrays).

NOTE: in Jackson 2.x this class was named JsonStreamContext

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected int
    _index
    Index of the currently processed entry.
    protected int
    _nestingDepth
    The nesting depth is a count of objects and arrays that have not been closed, `{` and `[` respectively.
    protected int
    _type
    Indicates logical type of context as one of TYPE_xxx constants.
    static final int
    TYPE_ARRAY
    Indicator for "Array" context.
    static final int
    TYPE_OBJECT
    Indicator for "Object" context.
    static final int
    TYPE_ROOT
    Indicator for "Root Value" context (has not parent)

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    assignCurrentValue(Object v)
    Method to call to pass value to be returned via currentValue(); typically called indirectly through JsonParser.assignCurrentValue(java.lang.Object) or JsonGenerator.assignCurrentValue(java.lang.Object)).
    abstract String
    currentName()
    Method for accessing name associated with the current location.
    Object
    currentValue()
    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.
    final int
    getCurrentIndex()
     
    final int
    getEntryCount()
     
    final int
    getNestingDepth()
    The nesting depth is a count of objects and arrays that have not been closed, `{` and `[` respectively.
    abstract TokenStreamContext
    getParent()
    Accessor for finding parent context of this context; will return null for root context.
    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`.
    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.
    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.
    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.
    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"
    TokenStreamLocation
    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 Object property names and values) or ARRAY (for elements of JSON Arrays)

    Methods inherited from class java.lang.Object

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

  • Field Details

    • TYPE_ROOT

      public static final int TYPE_ROOT
      Indicator for "Root Value" context (has not parent)
      See Also:

    • TYPE_ARRAY

      public static final int TYPE_ARRAY
      Indicator for "Array" context.
      See Also:

    • TYPE_OBJECT

      public static final int TYPE_OBJECT
      Indicator for "Object" context.
      See Also:

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

    • _nestingDepth

      protected int _nestingDepth
      The nesting depth is a count of objects and arrays that have not been closed, `{` and `[` respectively.
      Since:
      2.15

  • Constructor Details

    • TokenStreamContext

      protected TokenStreamContext()

    • TokenStreamContext

      protected TokenStreamContext(TokenStreamContext base)
      Copy constructor used by sub-classes for creating copies for buffering.
      Parameters:
      base - Context instance to copy type and index from

    • TokenStreamContext

      protected TokenStreamContext(int type, int index)

  • Method Details

    • getParent

      public abstract TokenStreamContext 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

    • getNestingDepth

      public final int getNestingDepth()
      The nesting depth is a count of objects and arrays that have not been closed, `{` and `[` respectively.
      Returns:
      Nesting depth
      Since:
      2.15

    • typeDesc

      public String typeDesc()
      Method for accessing simple type description of current context; either ROOT (for root-level values), OBJECT (for Object property names and values) or ARRAY (for elements of JSON Arrays)
      Returns:
      Type description String

    • 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

    • 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

    • currentName

      public abstract String currentName()
      Method for accessing name associated with the current location. Non-null for PROPERTY_NAME and value events that directly follow Property names; null for root level and array values.
      Returns:
      Current property name within context, if any; null if none

    • hasCurrentName

      public boolean hasCurrentName()

    • currentValue

      public Object currentValue()
      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.

    • assignCurrentValue

      public void assignCurrentValue(Object v)
      Method to call to pass value to be returned via currentValue(); typically called indirectly through JsonParser.assignCurrentValue(java.lang.Object) or JsonGenerator.assignCurrentValue(java.lang.Object)).
      Parameters:
      v - Current value to assign to this context

    • 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

    • 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

    • startLocation

      public TokenStreamLocation 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 TokenStreamLocation.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.

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