Package com.fasterxml.jackson.core

Class JsonStreamContext

  • Direct Known Subclasses:
    JsonReadContext, JsonWriteContext, TokenBufferReadContext, TokenFilterContext
    public abstract class JsonStreamContext
extends java.lang.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 Description
      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)

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      int getCurrentIndex()  
      abstract java.lang.String getCurrentName()
      Method for accessing name associated with the current location.
      java.lang.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()  
      int getNestingDepth()
      The nesting depth is a count of objects and arrays that have not been closed, `{` and `[` respectively.
      abstract JsonStreamContext getParent()
      Accessor for finding parent context of this context; will return null for root context.
      JsonLocation getStartLocation​(java.lang.Object srcRef)
      Deprecated.
      Since 2.13 use startLocation(com.fasterxml.jackson.core.io.ContentReference) instead
      java.lang.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​(java.lang.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.
      java.lang.String toString()
      Overridden to provide developer readable "JsonPath" representation of the context.
      java.lang.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

        equals, 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

    • 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

      • 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

      • getTypeDesc

        @Deprecated
public final java.lang.String getTypeDesc()
        Deprecated.
        Since 2.8 use typeDesc() instead
        Returns:
        Type description String

      • typeDesc

        public java.lang.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 java.lang.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 java.lang.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

      • 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​(java.lang.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 java.lang.String toString()
        Overridden to provide developer readable "JsonPath" representation of the context.
        Overrides:
        toString in class java.lang.Object
        Returns:
        Simple developer-readable description this context layer (note: NOT constructed with parents, unlike pathAsPointer())
        Since:
        2.9