TreeNode
Date: 2016-12-03

com.fasterxml.jackson.core

## Interface TreeNode

-     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 `ObjectCodec` to have some level of interoperability. Most functionality is within `JsonNode` base class in `mapper` package.

  Note that in Jackson 1.x `JsonNode` itself was part of core package: Jackson 2.x refactored this since conceptually Tree Model is part of mapper package, and so part visible to `core` package should be minimized.

  NOTE: starting with Jackson 2.2, there is more functionality available via this class, and the intent is that this should form actual base for multiple alternative tree representations; for example, immutable trees could use different implementation than mutable trees. It should also be possible to move actual Tree Model implementation out of databind package eventually (Jackson 3?).

  Since:
    2.2

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JsonToken` | `asToken()` Method that can be used for efficient type detection when using stream abstraction for traversing nodes.
    `TreeNode` | `at(JsonPointer ptr)` Method for locating node specified by given JSON pointer instances.
    `TreeNode` | `at(java.lang.String jsonPointerExpression)` Convenience method that is functionally equivalent to:
    `java.util.Iterator<java.lang.String>` | `fieldNames()` Method for accessing names of all fields for this node, iff this node is an Object node.
    `TreeNode` | `get(int index)` Method for accessing value of the specified element of an array node.
    `TreeNode` | `get(java.lang.String fieldName)` Method for accessing value of the specified field of an object node.
    `boolean` | `isArray()` Method that returns true if this node is an Array node, false otherwise.
    `boolean` | `isContainerNode()` Method that returns true for container nodes: Arrays and Objects.
    `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` | `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(java.lang.String fieldName)` Method for accessing value of the specified field of 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 fields, and for all other nodes 0.
    `JsonParser` | `traverse()` Method for constructing a `JsonParser` instance for iterating over contents of the tree that this node is root of.
    `JsonParser` | `traverse(ObjectCodec codec)` Same as `traverse()`, but additionally passes `ObjectCodec` to use if `JsonParser.readValueAs(Class)` is used (otherwise caller must call `JsonParser.setCodec(com.fasterxml.jackson.core.ObjectCodec)` on response explicitly).

- - ### Method Detail

    - #### 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)

    - #### 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 fields, and for all other nodes 0.
      Returns:
        For non-container nodes returns 0; for arrays number of contained elements, and for objects number of fields.
      Since:
        2.2

    - #### 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()`, `isContainerNode()` and `isMissingNode()` ever returns true for any given node.

      Since:
        2.2

    - #### isContainerNode

          boolean isContainerNode()

      Method that returns true for container nodes: Arrays and Objects.

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

      Since:
        2.2

    - #### 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()`, `isContainerNode()` and `isMissingNode()` ever returns true for any given node.

      Since:
        2.2

    - #### isArray

          boolean isArray()

      Method that returns true if this node is an Array node, false otherwise. Note that if true is returned, `isContainerNode()` must also return true.
      Since:
        2.2

    - #### isObject

          boolean isObject()

      Method that returns true if this node is an Object node, false otherwise. Note that if true is returned, `isContainerNode()` must also return true.
      Since:
        2.2

    - #### get

          TreeNode get(java.lang.String fieldName)

      Method for accessing value of the specified field of an object node. If this node is not an object (or it does not have a value for specified field name), or if there is no field with such name, null is returned.

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

      Returns:
        Node that represent value of the specified field, if this node is an object and has value for the specified field. Null otherwise.
      Since:
        2.2

    - #### 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.

      Returns:
        Node that represent value of the specified element, if this node is an array and has specified element. Null otherwise.
      Since:
        2.2

    - #### path

          TreeNode path(java.lang.String fieldName)

      Method for accessing value of the specified field of an object node. For other nodes, a "missing node" (virtual node for which `isMissingNode()` returns true) is returned.
      Returns:
        Node that represent value of the specified field, if this node is an object and has value for the specified field; otherwise "missing node" is returned.
      Since:
        2.2

    - #### 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.

      Returns:
        Node that represent value of the specified element, if this node is an array and has specified element; otherwise "missing node" is returned.
      Since:
        2.2

    - #### fieldNames

          java.util.Iterator<java.lang.String> fieldNames()

      Method for accessing names of all fields for this node, iff this node is an Object node. Number of field names accessible will be `size()`.
      Since:
        2.2

    - #### 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.
      Returns:
        Node that matches given JSON Pointer: if no match exists, will return a node for which `isMissingNode()` returns true.
      Since:
        2.3

    - #### at

          TreeNode at(java.lang.String jsonPointerExpression)
                      throws java.lang.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:
        `jsonPointerExpression` - Expression to compile as a `JsonPointer` instance
      Returns:
        Node that matches given JSON Pointer: if no match exists, will return a node for which `isMissingNode()` returns true.
      Throws:
        `java.lang.IllegalArgumentException`
      Since:
        2.3

    - #### traverse

          JsonParser traverse()

      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 using `ObjectCodec` 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()`.

      Also note that calling this method will NOT pass `ObjectCodec` reference, so data-binding callback methods like `JsonParser.readValueAs(Class)` will not work with calling `JsonParser.setCodec(com.fasterxml.jackson.core.ObjectCodec)`). It is often better to call `traverse(ObjectCodec)` to pass the codec explicitly.

    - #### traverse

          JsonParser traverse(ObjectCodec codec)

      Same as `traverse()`, but additionally passes `ObjectCodec` to use if `JsonParser.readValueAs(Class)` is used (otherwise caller must call `JsonParser.setCodec(com.fasterxml.jackson.core.ObjectCodec)` on response explicitly).

      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()`.

      Since:
        2.1