All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.fasterxml.jackson.core.TreeNode Maven / Gradle / Ivy

The newest version!
/* Jackson JSON-processor.
 *
 * Copyright (c) 2007- Tatu Saloranta, [email protected]
 */

package com.fasterxml.jackson.core;

import java.util.Iterator;

/**
 * Marker interface used to denote JSON Tree nodes, as far as
 * the core package knows them (which is very little): mostly
 * needed to allow {@link 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 */ public interface TreeNode { /* /********************************************************** /* Minimal introspection methods /********************************************************** */ /** * Method that can be used for efficient type detection * when using stream abstraction for traversing nodes. * Will return the first {@link JsonToken} that equivalent * stream event would produce (for most nodes there is just * one token but for structured/container types multiple) */ JsonToken asToken(); /** * If this node is a numeric type (as per {@link JsonToken#isNumeric}), * returns native type that node uses to store the numeric value; * otherwise returns null. * * @return Type of number contained, if any; or null if node does not * contain numeric value. */ JsonParser.NumberType numberType(); /** * 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. * * @return For non-container nodes returns 0; for arrays number of * contained elements, and for objects number of fields. * * @since 2.2 */ int size(); /** * 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 {@link #isValueNode}, * {@link #isContainerNode} and {@link #isMissingNode} ever * returns true for any given node. * * @since 2.2 */ boolean isValueNode(); /** * Method that returns true for container nodes: Arrays and Objects. *

* Note: one and only one of methods {@link #isValueNode}, * {@link #isContainerNode} and {@link #isMissingNode} ever * returns true for any given node. * * @since 2.2 */ boolean isContainerNode(); /** * 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 {@link #isValueNode}, * {@link #isContainerNode} and {@link #isMissingNode} ever * returns true for any given node. * * @since 2.2 */ boolean isMissingNode(); /** * Method that returns true if this node is an Array node, false * otherwise. * Note that if true is returned, {@link #isContainerNode} * must also return true. * * @since 2.2 */ boolean isArray(); /** * Method that returns true if this node is an Object node, false * otherwise. * Note that if true is returned, {@link #isContainerNode} * must also return true. * * @since 2.2 */ boolean isObject(); /* /********************************************************** /* Basic traversal through structured entries (Arrays, Objects) /********************************************************** */ /** * 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. * * @return 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 */ TreeNode get(String fieldName); /** * 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. * * @return Node that represent value of the specified element, * if this node is an array and has specified element. * Null otherwise. * * @since 2.2 */ TreeNode get(int index); /** * Method for accessing value of the specified field of * an object node. * For other nodes, a "missing node" (virtual node * for which {@link #isMissingNode} returns true) is returned. * * @return 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 */ TreeNode path(String fieldName); /** * Method for accessing value of the specified element of * an array node. * For other nodes, a "missing node" (virtual node * for which {@link #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. * * @return 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 */ TreeNode path(int index); /** * Method for accessing names of all fields for this node, iff * this node is an Object node. Number of field names accessible * will be {@link #size}. * * @since 2.2 */ Iterator fieldNames(); /** * 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 {@link TreeNode#isMissingNode()} returns true. * * @return Node that matches given JSON Pointer: if no match exists, * will return a node for which {@link TreeNode#isMissingNode()} returns true. * * @since 2.3 */ TreeNode at(JsonPointer ptr); /** * 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 * {@link JsonPointer} instance once and reuse it: this method will not perform * any caching of compiled expressions. * * @param jsonPointerExpression Expression to compile as a {@link JsonPointer} * instance * * @return Node that matches given JSON Pointer: if no match exists, * will return a node for which {@link TreeNode#isMissingNode()} returns true. * * @since 2.3 */ TreeNode at(String jsonPointerExpression) throws IllegalArgumentException; /* /********************************************************** /* Converting to/from Streaming API /********************************************************** */ /** * Method for constructing a {@link JsonParser} instance for * iterating over contents of the tree that this node is root of. * Functionally equivalent to first serializing tree using * {@link 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 {@link JsonParser#nextToken()}. *

* Also note that calling this method will NOT pass {@link ObjectCodec} * reference, so data-binding callback methods like {@link JsonParser#readValueAs(Class)} * will not work with calling {@link JsonParser#setCodec}). * It is often better to call {@link #traverse(ObjectCodec)} to pass the codec explicitly. */ JsonParser traverse(); /** * Same as {@link #traverse()}, but additionally passes {@link com.fasterxml.jackson.core.ObjectCodec} * to use if {@link JsonParser#readValueAs(Class)} is used (otherwise caller must call * {@link JsonParser#setCodec} 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 {@link JsonParser#nextToken()}. * * @since 2.1 */ JsonParser traverse(ObjectCodec codec); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy