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

Interface TreeNode

All Known Subinterfaces:
ArrayTreeNode, ObjectTreeNode
public interface TreeNode
Marker interface used to denote JSON Tree nodes, as far as the core package knows them (which is very little): mostly needed to allow ObjectReadContext and ObjectWriteContext to have some level of interoperability. Most functionality is within JsonNode base class in databind package.

  • Method Summary

    Modifier and Type
    Method
    Description
    JsonToken
    asToken()
    Method that can be used for efficient type detection when using stream abstraction for traversing nodes.
    TreeNode
    at(String ptrExpr)
    Convenience method that is functionally equivalent to:
    TreeNode
    at(JsonPointer ptr)
    Method for locating node specified by given JSON pointer instances.
    TreeNode
    get(int index)
    Method for accessing value of the specified element of an array node.
    TreeNode
    get(String propertyName)
    Method for accessing value of the specified property of an Object node.
    boolean
    isArray()
    Method that returns true if this node is an Array node, false otherwise.
    boolean
    isContainer()
    Method that returns true for container nodes: Arrays and Objects.
    boolean
    isEmbeddedValue()
    Method that returns true if this node represents an embedded "foreign" (or perhaps native?)
    boolean
    isMissingNode()
    Method that returns true for "virtual" nodes which represent missing entries constructed by path accessor methods when there is no actual node matching given criteria.
    boolean
    isNull()
    Method that returns true if this node is a node that represents logical null value.
    boolean
    isObject()
    Method that returns true if this node is an Object node, false otherwise.
    boolean
    isValueNode()
    Method that returns true for all value nodes: ones that are not containers, and that do not represent "missing" nodes in the path.
    JsonParser.NumberType
    numberType()
    If this node is a numeric type (as per JsonToken.isNumeric()), returns native type that node uses to store the numeric value; otherwise returns null.
    TreeNode
    path(int index)
    Method for accessing value of the specified element of an array node.
    TreeNode
    path(String propertyName)
    Method for accessing value of the specified property of an Object node.
    Collection<String>
    propertyNames()
    Method for accessing names of all properties for this node, if (and only if) this node is an Object node.
    int
    size()
    Method that returns number of child nodes this node contains: for Array nodes, number of child elements, for Object nodes, number of properties, and for all other nodes 0.
    JsonParser
    traverse(ObjectReadContext readCtxt)
    Method for constructing a JsonParser instance for iterating over contents of the tree that this node is root of.

  • Method Details

    • asToken

      JsonToken asToken()
      Method that can be used for efficient type detection when using stream abstraction for traversing nodes. Will return the first JsonToken that equivalent stream event would produce (for most nodes there is just one token but for structured/container types multiple)
      Returns:
      JsonToken that is most closely associated with the node type

    • numberType

      JsonParser.NumberType numberType()
      If this node is a numeric type (as per JsonToken.isNumeric()), returns native type that node uses to store the numeric value; otherwise returns null.
      Returns:
      Type of number contained, if any; or null if node does not contain numeric value.

    • size

      int size()
      Method that returns number of child nodes this node contains: for Array nodes, number of child elements, for Object nodes, number of properties, and for all other nodes 0.
      Returns:
      For non-container nodes returns 0; for arrays number of contained elements, and for objects number of properties.

    • isValueNode

      boolean isValueNode()
      Method that returns true for all value nodes: ones that are not containers, and that do not represent "missing" nodes in the path. Such value nodes represent String, Number, Boolean and null values from JSON.

      Note: one and only one of methods isValueNode(), isContainer() and isMissingNode() ever returns true for any given node.

      Returns:
      True if this node is considered a value node; something that represents either a scalar value or explicit null

    • isContainer

      boolean isContainer()
      Method that returns true for container nodes: Arrays and Objects.

      Note: one and only one of methods isValueNode(), isContainer() and isMissingNode() ever returns true for any given node.

      Returns:
      True for Array and Object nodes, false otherwise

    • isMissingNode

      boolean isMissingNode()
      Method that returns true for "virtual" nodes which represent missing entries constructed by path accessor methods when there is no actual node matching given criteria.

      Note: one and only one of methods isValueNode(), isContainer() and isMissingNode() ever returns true for any given node.

      Returns:
      True if this node represents a "missing" node

    • isArray

      boolean isArray()
      Method that returns true if this node is an Array node, false otherwise. Note that if true is returned, isContainer() must also return true.
      Returns:
      True for Array nodes, false for everything else

    • isObject

      boolean isObject()
      Method that returns true if this node is an Object node, false otherwise. Note that if true is returned, isContainer() must also return true.
      Returns:
      True for Object nodes, false for everything else

    • isNull

      boolean isNull()
      Method that returns true if this node is a node that represents logical null value.
      Returns:
      True for nodes representing explicit input null, false for everything else
      Since:
      3.0

    • isEmbeddedValue

      boolean isEmbeddedValue()
      Method that returns true if this node represents an embedded "foreign" (or perhaps native?) object (like POJO), not represented as regular content. Such nodes are used to pass information that either native format cannot express as-is, metadata not included within at all, or something else that requires special handling.
      Returns:
      True for nodes representing "embedded" (or format-specific, native) value -- ones that streaming api exposes as JsonToken.VALUE_EMBEDDED_OBJECT -- false for other nodes
      Since:
      3.0

    • get

      TreeNode get(String propertyName)
      Method for accessing value of the specified property of an Object node. If this node is not an Object (or it does not have a value for specified property) null is returned.

      NOTE: handling of explicit null values may vary between implementations; some trees may retain explicit nulls, others not.

      Parameters:
      propertyName - Name of the property to access
      Returns:
      Node that represent value of the specified property, if this node is an Object and has value for the specified property; null otherwise.

    • get

      TreeNode get(int index)
      Method for accessing value of the specified element of an array node. For other nodes, null is returned.

      For array nodes, index specifies exact location within array and allows for efficient iteration over child elements (underlying storage is guaranteed to be efficiently indexable, i.e. has random-access to elements). If index is less than 0, or equal-or-greater than node.size(), null is returned; no exception is thrown for any index.

      Parameters:
      index - Index of the Array node element to access
      Returns:
      Node that represent value of the specified element, if this node is an array and has specified element; null otherwise.

    • path

      TreeNode path(String propertyName)
      Method for accessing value of the specified property of an Object node. For other nodes, a "missing node" (virtual node for which isMissingNode() returns true) is returned.
      Parameters:
      propertyName - Name of the property to access
      Returns:
      Node that represent value of the specified Object property, if this node is an object and has value for the specified property; otherwise "missing node" is returned.

    • path

      TreeNode path(int index)
      Method for accessing value of the specified element of an array node. For other nodes, a "missing node" (virtual node for which isMissingNode() returns true) is returned.

      For array nodes, index specifies exact location within array and allows for efficient iteration over child elements (underlying storage is guaranteed to be efficiently indexable, i.e. has random-access to elements). If index is less than 0, or equal-or-greater than node.size(), "missing node" is returned; no exception is thrown for any index.

      Parameters:
      index - Index of the Array node element to access
      Returns:
      Node that represent value of the specified element, if this node is an array and has specified element; otherwise "missing node" is returned.

    • propertyNames

      Collection<String> propertyNames()
      Method for accessing names of all properties for this node, if (and only if) this node is an Object node. Number of property names accessible will be size().
      Returns:
      Collection of names of all properties this Object node has (if Object node); empty Collection otherwise (never null).

    • at

      TreeNode at(JsonPointer ptr)
      Method for locating node specified by given JSON pointer instances. Method will never return null; if no matching node exists, will return a node for which isMissingNode() returns true.
      Parameters:
      ptr - JsonPointer expression for descendant node to return
      Returns:
      Node that matches given JSON Pointer, if any: if no match exists, will return a "missing" node (for which isMissingNode() returns true).

    • at

      TreeNode at(String ptrExpr) throws IllegalArgumentException
      Convenience method that is functionally equivalent to: 
         return at(JsonPointer.valueOf(jsonPointerExpression));

      Note that if the same expression is used often, it is preferable to construct JsonPointer instance once and reuse it: this method will not perform any caching of compiled expressions.

      Parameters:
      ptrExpr - Expression to compile as a JsonPointer instance
      Returns:
      Node that matches given JSON Pointer, if any: if no match exists, will return a "missing" node (for which isMissingNode() returns true).
      Throws:
      IllegalArgumentException

    • traverse

      JsonParser traverse(ObjectReadContext readCtxt)
      Method for constructing a JsonParser instance for iterating over contents of the tree that this node is root of. Functionally equivalent to first serializing tree and then re-parsing but more efficient.

      NOTE: constructed parser instance will NOT initially point to a token, so before passing it to deserializers, it is typically necessary to advance it to the first available token by calling JsonParser.nextToken().

      Parameters:
      readCtxt - ObjectReadContext to associate with parser constructed (to allow seamless databinding functionality)
      Returns:
      JsonParser that will stream over contents of this node