Package com.fasterxml.jackson.databind

Class JsonNode

java.lang.Object
com.fasterxml.jackson.databind.JsonSerializable.Base
com.fasterxml.jackson.databind.JsonNode
All Implemented Interfaces:
TreeNode, JsonSerializable, Iterable<JsonNode>
Direct Known Subclasses:
BaseJsonNode
public abstract class JsonNode extends JsonSerializable.Base implements TreeNode, Iterable<JsonNode>
Base class for all JSON nodes, which form the basis of JSON Tree Model that Jackson implements. One way to think of these nodes is to consider them similar to DOM nodes in XML DOM trees.

As a general design rule, most accessors ("getters") are included in this base class, to allow for traversing structure without type casts. Most mutators, however, need to be accessed through specific sub-classes (such as ObjectNode and ArrayNode). This seems sensible because proper type information is generally available when building or modifying trees, but less often when reading a tree (newly built from parsed JSON content).

Actual concrete sub-classes can be found from package com.fasterxml.jackson.databind.node.

Note that it is possible to "read" from nodes, using method TreeNode.traverse(ObjectCodec), which will result in a JsonParser being constructed. This can be used for (relatively) efficient conversations between different representations; and it is what core databind uses for methods like ObjectMapper.treeToValue(TreeNode, Class) and ObjectMapper.treeAsTokens(TreeNode)

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    JsonNode.OverwriteMode
    Configuration setting used with withObject(JsonPointer) method overrides, to indicate which overwrites are acceptable if the path pointer indicates has incompatible nodes (for example, instead of Object node a Null node is encountered).

    Nested classes/interfaces inherited from interface com.fasterxml.jackson.databind.JsonSerializable

    JsonSerializable.Base

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    asBoolean()
    Method that will try to convert value of this node to a Java boolean.
    boolean
    asBoolean(boolean defaultValue)
    Method that will try to convert value of this node to a Java boolean.
    double
    asDouble()
    Method that will try to convert value of this node to a Java double.
    double
    asDouble(double defaultValue)
    Method that will try to convert value of this node to a Java double.
    int
    asInt()
    Method that will try to convert value of this node to a Java int.
    int
    asInt(int defaultValue)
    Method that will try to convert value of this node to a Java int.
    long
    asLong()
    Method that will try to convert value of this node to a Java long.
    long
    asLong(long defaultValue)
    Method that will try to convert value of this node to a Java long.
    abstract String
    asText()
    Method that will return a valid String representation of the container value, if the node is a value node (method isValueNode() returns true), otherwise empty String.
    String
    asText(String defaultValue)
    Returns the text value of this node or the provided defaultValue if this node does not have a text value.
    final JsonNode
    at(JsonPointer ptr)
    Method for locating node specified by given JSON pointer instances.
    final JsonNode
    at(String jsonPtrExpr)
    Convenience method that is functionally equivalent to:
    BigInteger
    bigIntegerValue()
    Returns integer value for this node (as BigInteger), if and only if this node is numeric (isNumber() returns true).
    byte[]
    binaryValue()
    Method to use for accessing binary content of binary nodes (nodes for which isBinary() returns true); or for Text Nodes (ones for which textValue() returns non-null value), to read decoded base64 data.
    boolean
    booleanValue()
    Method to use for accessing JSON boolean values (value literals 'true' and 'false').
    boolean
    canConvertToExactIntegral()
    Method that can be used to check whether contained value is numeric (returns true for isNumber()) and can be losslessly converted to integral number (specifically, BigInteger but potentially others, see canConvertToInt() and canConvertToInt()).
    boolean
    canConvertToInt()
    Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND its value fits within Java's 32-bit signed integer type, int.
    boolean
    canConvertToLong()
    Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND its value fits within Java's 64-bit signed integer type, long.
    BigDecimal
    decimalValue()
    Returns floating point value for this node (as BigDecimal), if and only if this node is numeric (isNumber() returns true).
    abstract <T extends JsonNode>
    T
    deepCopy()
    Method that can be called to get a node that is guaranteed not to allow changing of this node through mutators on this node or any of its children.
    double
    doubleValue()
    Returns 64-bit floating point (double) value for this node, if and only if this node is numeric (isNumber() returns true).
    Iterator<JsonNode>
    elements()
    Method for accessing all value nodes of this Node, iff this node is a JSON Array or Object node.
    abstract boolean
    equals(Object o)
    Equality for node objects is defined as full (deep) value equality.
    boolean
    equals(Comparator<JsonNode> comparator, JsonNode other)
    Entry method for invoking customizable comparison, using passed-in Comparator object.
    Iterator<String>
    fieldNames()
    Method for accessing names of all fields for this node, iff this node is an Object node.
    Iterator<Map.Entry<String,JsonNode>>
    fields()
     
    abstract JsonNode
    findParent(String fieldName)
    Method for finding a JSON Object that contains specified field, within this node or its descendants.
    final List<JsonNode>
    findParents(String fieldName)
    Method for finding a JSON Object that contains specified field, within this node or its descendants.
    abstract List<JsonNode>
    findParents(String fieldName, List<JsonNode> foundSoFar)
     
    abstract JsonNode
    findPath(String fieldName)
    Method similar to findValue(java.lang.String), but that will return a "missing node" instead of null if no field is found.
    abstract JsonNode
    findValue(String fieldName)
    Method for finding the first JSON Object field with specified name in this node or its child nodes, and returning value it has.
    final List<JsonNode>
    findValues(String fieldName)
    Method for finding JSON Object fields with specified name -- both immediate child values and descendants -- and returning found ones as a List.
    abstract List<JsonNode>
    findValues(String fieldName, List<JsonNode> foundSoFar)
     
    final List<String>
    findValuesAsText(String fieldName)
    Similar to findValues(java.lang.String), but will additionally convert values into Strings, calling asText().
    abstract List<String>
    findValuesAsText(String fieldName, List<String> foundSoFar)
     
    float
    floatValue()
    Returns 32-bit floating value for this node, if and only if this node is numeric (isNumber() returns true).
    abstract JsonNode
    get(int index)
    Method for accessing value of the specified element of an array node.
    JsonNode
    get(String fieldName)
    Method for accessing value of the specified field of an object node.
    abstract JsonNodeType
    getNodeType()
    Return the type of this node
    boolean
    has(int index)
    Method that allows checking whether this node is JSON Array node and contains a value for specified index If this is the case (including case of specified indexing having null as value), returns true; otherwise returns false.
    boolean
    has(String fieldName)
    Method that allows checking whether this node is JSON Object node and contains value for specified property.
    boolean
    hasNonNull(int index)
    Method that is similar to has(int), but that will return false for explicitly added nulls.
    boolean
    hasNonNull(String fieldName)
    Method that is similar to has(String), but that will return false for explicitly added nulls.
    int
    intValue()
    Returns integer value for this node, if and only if this node is numeric (isNumber() returns true).
    boolean
    isArray()
    Method that returns true if this node is an Array node, false otherwise.
    boolean
    isBigDecimal()
     
    boolean
    isBigInteger()
     
    final boolean
    isBinary()
    Method that can be used to check if this node represents binary data (Base64 encoded).
    final boolean
    isBoolean()
    Method that can be used to check if this node was created from JSON boolean value (literals "true" and "false").
    final boolean
    isContainerNode()
    Method that returns true for container nodes: Arrays and Objects.
    boolean
    isDouble()
     
    boolean
    isEmpty()
    Convenience method that is functionally same as:
    boolean
    isFloat()
     
    boolean
    isFloatingPointNumber()
     
    boolean
    isInt()
    Method that can be used to check whether contained value is a number represented as Java int.
    boolean
    isIntegralNumber()
     
    boolean
    isLong()
    Method that can be used to check whether contained value is a number represented as Java long.
    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.
    final boolean
    isNull()
    Method that can be used to check if this node was created from JSON literal null value.
    final boolean
    isNumber()
     
    boolean
    isObject()
    Method that returns true if this node is an Object node, false otherwise.
    final boolean
    isPojo()
    Method that can be used to check if the node is a wrapper for a POJO ("Plain Old Java Object" aka "bean".
    boolean
    isShort()
    Method that can be used to check whether contained value is a number represented as Java short.
    final boolean
    isTextual()
    Method that checks whether this node represents basic JSON String value.
    final 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.
    final Iterator<JsonNode>
    iterator()
    Same as calling elements(); implemented so that convenience "for-each" loop can be used for looping over elements of JSON Array constructs.
    long
    longValue()
    Returns 64-bit long value for this node, if and only if this node is numeric (isNumber() returns true).
    Number
    numberValue()
    Returns numeric value for this node, if and only if this node is numeric (isNumber() returns true); otherwise returns null
    abstract JsonNode
    path(int index)
    This method is similar to get(int), except that instead of returning null if no such element exists (due to index being out of range, or this node not being an array), a "missing node" (node that returns true for isMissingNode()) will be returned.
    abstract JsonNode
    path(String fieldName)
    This method is similar to get(String), except that instead of returning null if no such value exists (due to this node not being an object, or object not having value for the specified field), a "missing node" (node that returns true for isMissingNode()) will be returned.
    Set<Map.Entry<String,JsonNode>>
    properties()
    Accessor that will return properties of ObjectNode similar to how Map.entrySet() works; for other node types will return empty Set.
    <T extends JsonNode>
    T
    require()
    Method that may be called to verify that this node is NOT so-called "missing node": that is, one for which isMissingNode() returns true.
    JsonNode
    required(int index)
    Method is functionally equivalent to path(index).required() and can be used to check that this node is an ArrayNode (that is, represents JSON Array value) and has value for specified index (but note that value may be explicit JSON null value).
    JsonNode
    required(String propertyName)
    Method is functionally equivalent to path(fieldName).required() and can be used to check that this node is an ObjectNode (that is, represents JSON Object value) and has value for specified property with key fieldName (but note that value may be explicit JSON null value).
    final JsonNode
    requiredAt(JsonPointer path)
    Method is functionally equivalent to at(path).required() and can be used to check that there is an actual value node at specified JsonPointer starting from this node (but note that value may be explicit JSON null value).
    JsonNode
    requiredAt(String pathExpr)
    Method is functionally equivalent to at(pathExpr).required() and can be used to check that there is an actual value node at specified JsonPointer starting from this node (but note that value may be explicit JSON null value).
    <T extends JsonNode>
    T
    requireNonNull()
    Method that may be called to verify that this node is neither so-called "missing node" (that is, one for which isMissingNode() returns true) nor "null node" (one for which isNull() returns true).
    short
    shortValue()
    Returns 16-bit short value for this node, if and only if this node is numeric (isNumber() returns true).
    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.
    String
    textValue()
    Method to use for accessing String values.
    String
    toPrettyString()
    Alternative to toString() that will serialize this node using Jackson default pretty-printer.
    abstract String
    toString()
    Method that will produce (as of Jackson 2.10) valid JSON using default settings of databind, as String.
    <T extends JsonNode>
    T
    with(String exprOrProperty)
    Deprecated.
    Since 2.14 use withObject(String) instead
    final ArrayNode
    withArray(JsonPointer ptr)
    Same as withArray(JsonPointer, OverwriteMode, boolean) but with defaults of OvewriteMode#NULLS (overwrite mode) and true for preferIndex.
    ArrayNode
    withArray(JsonPointer ptr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
    Method that can be called on Object or Array nodes, to access a Array-valued node pointed to by given JsonPointer, if such a node exists: or if not, an attempt is made to create one and return it.
    <T extends JsonNode>
    T
    withArray(String exprOrProperty)
    Method that works in one of possible ways, depending on whether exprOrProperty is a valid JsonPointer expression or not (valid expression is either empty String "" or starts with leading slash / character).
    ArrayNode
    withArray(String expr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
    Short-cut equivalent to:
    ArrayNode
    withArrayProperty(String propName)
    Method similar to withArray(JsonPointer, OverwriteMode, boolean) -- basically short-cut to:
    final ObjectNode
    withObject(JsonPointer ptr)
    Same as withObject(JsonPointer, OverwriteMode, boolean) but with defaults of OvewriteMode#NULLS (overwrite mode) and true for preferIndex (that is, will try to consider JsonPointer segments index if at all possible and only secondarily as property name
    ObjectNode
    withObject(JsonPointer ptr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
    Method that can be called on Object or Array nodes, to access a Object-valued node pointed to by given JsonPointer, if such a node exists: or if not, an attempt is made to create one and return it.
    ObjectNode
    withObject(String exprOrProperty)
    Method that works in one of possible ways, depending on whether exprOrProperty is a valid JsonPointer expression or not (valid expression is either empty String "" or starts with leading slash / character).
    final ObjectNode
    withObject(String expr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
    Short-cut equivalent to:
    ObjectNode
    withObjectProperty(String propName)
    Method similar to withObject(JsonPointer, OverwriteMode, boolean) -- basically short-cut to:

    Methods inherited from class com.fasterxml.jackson.databind.JsonSerializable.Base

    isEmpty

    Methods inherited from class java.lang.Object

    getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

    Methods inherited from interface com.fasterxml.jackson.databind.JsonSerializable

    serialize, serializeWithType

    Methods inherited from interface com.fasterxml.jackson.core.TreeNode

    asToken, numberType, traverse, traverse

  • Method Details

    • deepCopy

      public abstract <T extends JsonNode> T deepCopy()
      Method that can be called to get a node that is guaranteed not to allow changing of this node through mutators on this node or any of its children. This means it can either make a copy of this node (and all mutable children and grand children nodes), or node itself if it is immutable.

      Note: return type is guaranteed to have same type as the node method is called on; which is why method is declared with local generic type.

      Returns:
      Node that is either a copy of this node (and all non-leaf children); or, for immutable leaf nodes, node itself.
      Since:
      2.0

    • size

      public int size()
      Description copied from interface: TreeNode
      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.
      Specified by:
      size in interface TreeNode
      Returns:
      For non-container nodes returns 0; for arrays number of contained elements, and for objects number of fields.

    • isEmpty

      public boolean isEmpty()
      Convenience method that is functionally same as: 
          size() == 0
      for all node types.
      Since:
      2.10

    • isValueNode

      public final boolean isValueNode()
      Description copied from interface: TreeNode
      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 TreeNode.isValueNode(), TreeNode.isContainerNode() and TreeNode.isMissingNode() ever returns true for any given node.

      Specified by:
      isValueNode in interface TreeNode
      Returns:
      True if this node is considered a value node; something that represents either a scalar value or explicit null

    • isContainerNode

      public final boolean isContainerNode()
      Description copied from interface: TreeNode
      Method that returns true for container nodes: Arrays and Objects.

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

      Specified by:
      isContainerNode in interface TreeNode
      Returns:
      True for Array and Object nodes, false otherwise

    • isMissingNode

      public boolean isMissingNode()
      Description copied from interface: TreeNode
      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 TreeNode.isValueNode(), TreeNode.isContainerNode() and TreeNode.isMissingNode() ever returns true for any given node.

      Specified by:
      isMissingNode in interface TreeNode
      Returns:
      True if this node represents a "missing" node

    • isArray

      public boolean isArray()
      Description copied from interface: TreeNode
      Method that returns true if this node is an Array node, false otherwise. Note that if true is returned, TreeNode.isContainerNode() must also return true.
      Specified by:
      isArray in interface TreeNode
      Returns:
      True for Array nodes, false for everything else

    • isObject

      public boolean isObject()
      Description copied from interface: TreeNode
      Method that returns true if this node is an Object node, false otherwise. Note that if true is returned, TreeNode.isContainerNode() must also return true.
      Specified by:
      isObject in interface TreeNode
      Returns:
      True for Object nodes, false for everything else

    • get

      public abstract JsonNode get(int index)
      Method for accessing value of the specified element of an array node. For other nodes, null is always 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.

      NOTE: if the element value has been explicitly set as null (which is different from removal!), a NullNode will be returned, not null.

      Specified by:
      get in interface TreeNode
      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.

    • get

      public JsonNode get(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: if the property value has been explicitly set as null (which is different from removal!), a NullNode will be returned, not null.

      Specified by:
      get in interface TreeNode
      Parameters:
      fieldName - Name of the field (of Object node) to access
      Returns:
      Node that represent value of the specified field, if this node is an object and has value for the specified field. Null otherwise.

    • path

      public abstract JsonNode path(String fieldName)
      This method is similar to get(String), except that instead of returning null if no such value exists (due to this node not being an object, or object not having value for the specified field), a "missing node" (node that returns true for isMissingNode()) will be returned. This allows for convenient and safe chained access via path calls.
      Specified by:
      path in interface TreeNode
      Parameters:
      fieldName - Name of the field (of Object node) to access
      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.

    • path

      public abstract JsonNode path(int index)
      This method is similar to get(int), except that instead of returning null if no such element exists (due to index being out of range, or this node not being an array), a "missing node" (node that returns true for isMissingNode()) will be returned. This allows for convenient and safe chained access via path calls.
      Specified by:
      path in interface TreeNode
      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.

    • fieldNames

      public Iterator<String> fieldNames()
      Description copied from interface: TreeNode
      Method for accessing names of all fields for this node, iff this node is an Object node. Number of field names accessible will be TreeNode.size().
      Specified by:
      fieldNames in interface TreeNode
      Returns:
      An iterator for traversing names of all fields this Object node has (if Object node); empty Iterator otherwise (never null).

    • at

      public final JsonNode 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.
      Specified by:
      at in interface TreeNode
      Parameters:
      ptr - JsonPointer expression for descendant node to return
      Returns:
      Node that matches given JSON Pointer: if no match exists, will return a node for which isMissingNode() returns true.
      Since:
      2.3

    • at

      public final JsonNode at(String jsonPtrExpr)
      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.

      Specified by:
      at in interface TreeNode
      Parameters:
      jsonPtrExpr - Expression to compile as a JsonPointer instance
      Returns:
      Node that matches given JSON Pointer: if no match exists, will return a node for which TreeNode.isMissingNode() returns true.
      Since:
      2.3

    • getNodeType

      public abstract JsonNodeType getNodeType()
      Return the type of this node
      Returns:
      the node type as a JsonNodeType enum value
      Since:
      2.2

    • isPojo

      public final boolean isPojo()
      Method that can be used to check if the node is a wrapper for a POJO ("Plain Old Java Object" aka "bean". Returns true only for instances of POJONode.
      Returns:
      True if this node wraps a POJO

    • isNumber

      public final boolean isNumber()
      Returns:
      True if this node represents a numeric JSON value

    • isIntegralNumber

      public boolean isIntegralNumber()
      Returns:
      True if this node represents an integral (integer) numeric JSON value

    • isFloatingPointNumber

      public boolean isFloatingPointNumber()
      Returns:
      True if this node represents a non-integral numeric JSON value

    • isShort

      public boolean isShort()
      Method that can be used to check whether contained value is a number represented as Java short. Note, however, that even if this method returns false, it is possible that conversion would be possible from other numeric types -- to check if this is possible, use canConvertToInt() instead.
      Returns:
      True if the value contained by this node is stored as Java short

    • isInt

      public boolean isInt()
      Method that can be used to check whether contained value is a number represented as Java int. Note, however, that even if this method returns false, it is possible that conversion would be possible from other numeric types -- to check if this is possible, use canConvertToInt() instead.
      Returns:
      True if the value contained by this node is stored as Java int

    • isLong

      public boolean isLong()
      Method that can be used to check whether contained value is a number represented as Java long. Note, however, that even if this method returns false, it is possible that conversion would be possible from other numeric types -- to check if this is possible, use canConvertToLong() instead.
      Returns:
      True if the value contained by this node is stored as Java long

    • isFloat

      public boolean isFloat()
      Since:
      2.2

    • isDouble

      public boolean isDouble()

    • isBigDecimal

      public boolean isBigDecimal()

    • isBigInteger

      public boolean isBigInteger()

    • isTextual

      public final boolean isTextual()
      Method that checks whether this node represents basic JSON String value.

    • isBoolean

      public final boolean isBoolean()
      Method that can be used to check if this node was created from JSON boolean value (literals "true" and "false").

    • isNull

      public final boolean isNull()
      Method that can be used to check if this node was created from JSON literal null value.

    • isBinary

      public final boolean isBinary()
      Method that can be used to check if this node represents binary data (Base64 encoded). Although this will be externally written as JSON String value, isTextual() will return false if this method returns true.
      Returns:
      True if this node represents base64 encoded binary data

    • canConvertToInt

      public boolean canConvertToInt()
      Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND its value fits within Java's 32-bit signed integer type, int. Note that floating-point numbers are convertible if the integral part fits without overflow (as per standard Java coercion rules)

      NOTE: this method does not consider possible value type conversion from JSON String into Number; so even if this method returns false, it is possible that asInt() could still succeed if node is a JSON String representing integral number, or boolean.

      Since:
      2.0

    • canConvertToLong

      public boolean canConvertToLong()
      Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND its value fits within Java's 64-bit signed integer type, long. Note that floating-point numbers are convertible if the integral part fits without overflow (as per standard Java coercion rules)

      NOTE: this method does not consider possible value type conversion from JSON String into Number; so even if this method returns false, it is possible that asLong() could still succeed if node is a JSON String representing integral number, or boolean.

      Since:
      2.0

    • canConvertToExactIntegral

      public boolean canConvertToExactIntegral()
      Method that can be used to check whether contained value is numeric (returns true for isNumber()) and can be losslessly converted to integral number (specifically, BigInteger but potentially others, see canConvertToInt() and canConvertToInt()). Latter part allows floating-point numbers (for which isFloatingPointNumber() returns true) that do not have fractional part. Note that "not-a-number" values of double and float will return false as they can not be converted to matching integral representations.
      Returns:
      True if the value is an actual number with no fractional part; false for non-numeric types, NaN representations of floating-point numbers, and floating-point numbers with fractional part.
      Since:
      2.12

    • textValue

      public String textValue()
      Method to use for accessing String values. Does NOT do any conversions for non-String value nodes; for non-String values (ones for which isTextual() returns false) null will be returned. For String values, null is never returned (but empty Strings may be)
      Returns:
      Textual value this node contains, iff it is a textual JSON node (comes from JSON String value entry)

    • binaryValue

      public byte[] binaryValue() throws IOException
      Method to use for accessing binary content of binary nodes (nodes for which isBinary() returns true); or for Text Nodes (ones for which textValue() returns non-null value), to read decoded base64 data. For other types of nodes, returns null.
      Returns:
      Binary data this node contains, iff it is a binary node; null otherwise
      Throws:
      IOException

    • booleanValue

      public boolean booleanValue()
      Method to use for accessing JSON boolean values (value literals 'true' and 'false'). For other types, always returns false.
      Returns:
      Textual value this node contains, iff it is a textual json node (comes from JSON String value entry)

    • numberValue

      public Number numberValue()
      Returns numeric value for this node, if and only if this node is numeric (isNumber() returns true); otherwise returns null
      Returns:
      Number value this node contains, if any (null for non-number nodes).

    • shortValue

      public short shortValue()
      Returns 16-bit short value for this node, if and only if this node is numeric (isNumber() returns true). For other types returns 0. For floating-point numbers, value is truncated using default Java coercion, similar to how cast from double to short operates.
      Returns:
      Short value this node contains, if any; 0 for non-number nodes.

    • intValue

      public int intValue()
      Returns integer value for this node, if and only if this node is numeric (isNumber() returns true). For other types returns 0. For floating-point numbers, value is truncated using default Java coercion, similar to how cast from double to int operates.
      Returns:
      Integer value this node contains, if any; 0 for non-number nodes.

    • longValue

      public long longValue()
      Returns 64-bit long value for this node, if and only if this node is numeric (isNumber() returns true). For other types returns 0. For floating-point numbers, value is truncated using default Java coercion, similar to how cast from double to long operates.
      Returns:
      Long value this node contains, if any; 0 for non-number nodes.

    • floatValue

      public float floatValue()
      Returns 32-bit floating value for this node, if and only if this node is numeric (isNumber() returns true). For other types returns 0.0. For integer values, conversion is done using coercion; this means that an overflow is possible for `long` values
      Returns:
      32-bit float value this node contains, if any; 0.0 for non-number nodes.
      Since:
      2.2

    • doubleValue

      public double doubleValue()
      Returns 64-bit floating point (double) value for this node, if and only if this node is numeric (isNumber() returns true). For other types returns 0.0. For integer values, conversion is done using coercion; this may result in overflows with BigInteger values.
      Returns:
      64-bit double value this node contains, if any; 0.0 for non-number nodes.
      Since:
      2.2

    • decimalValue

      public BigDecimal decimalValue()
      Returns floating point value for this node (as BigDecimal), if and only if this node is numeric (isNumber() returns true). For other types returns BigDecimal.ZERO.
      Returns:
      BigDecimal value this node contains, if numeric node; BigDecimal.ZERO for non-number nodes.

    • bigIntegerValue

      public BigInteger bigIntegerValue()
      Returns integer value for this node (as BigInteger), if and only if this node is numeric (isNumber() returns true). For other types returns BigInteger.ZERO.

      NOTE: In Jackson 2.x MAY throw StreamConstraintsException if the scale of the underlying BigDecimal is too large to convert (NOTE: thrown "sneakily" in Jackson 2.x due to API compatibility restrictions)

      Returns:
      BigInteger value this node contains, if numeric node; BigInteger.ZERO for non-number nodes.

    • asText

      public abstract String asText()
      Method that will return a valid String representation of the container value, if the node is a value node (method isValueNode() returns true), otherwise empty String.

    • asText

      public String asText(String defaultValue)
      Returns the text value of this node or the provided defaultValue if this node does not have a text value. Useful for nodes that are MissingNode or NullNode, ensuring a default value is returned instead of null or missing indicators.

      NOTE: This was deprecated in 2.17.0, but as discussed through [databind#4471], was un-deprecated in 2.17.1.

      Parameters:
      defaultValue - The default value to return if this node's text value is absent.
      Returns:
      The text value of this node, or defaultValue if the text value is absent.
      Since:
      2.4

    • asInt

      public int asInt()
      Method that will try to convert value of this node to a Java int. Numbers are coerced using default Java rules; booleans convert to 0 (false) and 1 (true), and Strings are parsed using default Java language integer parsing rules.

      If representation cannot be converted to an int (including structured types like Objects and Arrays), default value of 0 will be returned; no exceptions are thrown.

    • asInt

      public int asInt(int defaultValue)
      Method that will try to convert value of this node to a Java int. Numbers are coerced using default Java rules; booleans convert to 0 (false) and 1 (true), and Strings are parsed using default Java language integer parsing rules.

      If representation cannot be converted to an int (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.

    • asLong

      public long asLong()
      Method that will try to convert value of this node to a Java long. Numbers are coerced using default Java rules; booleans convert to 0 (false) and 1 (true), and Strings are parsed using default Java language integer parsing rules.

      If representation cannot be converted to a long (including structured types like Objects and Arrays), default value of 0 will be returned; no exceptions are thrown.

    • asLong

      public long asLong(long defaultValue)
      Method that will try to convert value of this node to a Java long. Numbers are coerced using default Java rules; booleans convert to 0 (false) and 1 (true), and Strings are parsed using default Java language integer parsing rules.

      If representation cannot be converted to a long (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.

    • asDouble

      public double asDouble()
      Method that will try to convert value of this node to a Java double. Numbers are coerced using default Java rules; booleans convert to 0.0 (false) and 1.0 (true), and Strings are parsed using default Java language integer parsing rules.

      If representation cannot be converted to an int (including structured types like Objects and Arrays), default value of 0.0 will be returned; no exceptions are thrown.

    • asDouble

      public double asDouble(double defaultValue)
      Method that will try to convert value of this node to a Java double. Numbers are coerced using default Java rules; booleans convert to 0.0 (false) and 1.0 (true), and Strings are parsed using default Java language integer parsing rules.

      If representation cannot be converted to an int (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.

    • asBoolean

      public boolean asBoolean()
      Method that will try to convert value of this node to a Java boolean. JSON booleans map naturally; integer numbers other than 0 map to true, and 0 maps to false and Strings 'true' and 'false' map to corresponding values.

      If representation cannot be converted to a boolean value (including structured types like Objects and Arrays), default value of false will be returned; no exceptions are thrown.

    • asBoolean

      public boolean asBoolean(boolean defaultValue)
      Method that will try to convert value of this node to a Java boolean. JSON booleans map naturally; integer numbers other than 0 map to true, and 0 maps to false and Strings 'true' and 'false' map to corresponding values.

      If representation cannot be converted to a boolean value (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.

    • require

      public <T extends JsonNode> T require() throws IllegalArgumentException
      Method that may be called to verify that this node is NOT so-called "missing node": that is, one for which isMissingNode() returns true. If not missing node, this is returned to allow chaining; otherwise IllegalArgumentException is thrown.
      Returns:
      this node to allow chaining
      Throws:
      IllegalArgumentException - if this node is "missing node"
      Since:
      2.10

    • requireNonNull

      public <T extends JsonNode> T requireNonNull() throws IllegalArgumentException
      Method that may be called to verify that this node is neither so-called "missing node" (that is, one for which isMissingNode() returns true) nor "null node" (one for which isNull() returns true). If non-null non-missing node, this is returned to allow chaining; otherwise IllegalArgumentException is thrown.
      Returns:
      this node to allow chaining
      Throws:
      IllegalArgumentException - if this node is either "missing node" or "null node"
      Since:
      2.10

    • required

      public JsonNode required(String propertyName) throws IllegalArgumentException
      Method is functionally equivalent to path(fieldName).required() and can be used to check that this node is an ObjectNode (that is, represents JSON Object value) and has value for specified property with key fieldName (but note that value may be explicit JSON null value). If this node is Object Node and has value for specified property, matching value is returned; otherwise IllegalArgumentException is thrown.
      Parameters:
      propertyName - Name of property to access
      Returns:
      Value of the specified property of this Object node
      Throws:
      IllegalArgumentException - if this node is not an Object node or if it does not have value for specified property
      Since:
      2.10

    • required

      public JsonNode required(int index) throws IllegalArgumentException
      Method is functionally equivalent to path(index).required() and can be used to check that this node is an ArrayNode (that is, represents JSON Array value) and has value for specified index (but note that value may be explicit JSON null value). If this node is Array Node and has value for specified index, value at index is returned; otherwise IllegalArgumentException is thrown.
      Parameters:
      index - Index of the value of this Array node to access
      Returns:
      Value at specified index of this Array node
      Throws:
      IllegalArgumentException - if this node is not an Array node or if it does not have value for specified index
      Since:
      2.10

    • requiredAt

      public JsonNode requiredAt(String pathExpr) throws IllegalArgumentException
      Method is functionally equivalent to at(pathExpr).required() and can be used to check that there is an actual value node at specified JsonPointer starting from this node (but note that value may be explicit JSON null value). If such value node exists it is returned; otherwise IllegalArgumentException is thrown.
      Parameters:
      pathExpr - JsonPointer expression (as String) to use for finding value node
      Returns:
      Matching value node for given expression
      Throws:
      IllegalArgumentException - if no value node exists at given JSON Pointer path
      Since:
      2.10

    • requiredAt

      public final JsonNode requiredAt(JsonPointer path) throws IllegalArgumentException
      Method is functionally equivalent to at(path).required() and can be used to check that there is an actual value node at specified JsonPointer starting from this node (but note that value may be explicit JSON null value). If such value node exists it is returned; otherwise IllegalArgumentException is thrown.
      Parameters:
      path - JsonPointer expression to use for finding value node
      Returns:
      Matching value node for given expression
      Throws:
      IllegalArgumentException - if no value node exists at given JSON Pointer path
      Since:
      2.10

    • has

      public boolean has(String fieldName)
      Method that allows checking whether this node is JSON Object node and contains value for specified property. If this is the case (including properties with explicit null values), returns true; otherwise returns false.

      This method is equivalent to: 

         node.get(fieldName) != null
      (since return value of get() is node, not value node contains)

      NOTE: when explicit null values are added, this method will return true for such properties.

      Parameters:
      fieldName - Name of element to check
      Returns:
      True if this node is a JSON Object node, and has a property entry with specified name (with any value, including null value)

    • has

      public boolean has(int index)
      Method that allows checking whether this node is JSON Array node and contains a value for specified index If this is the case (including case of specified indexing having null as value), returns true; otherwise returns false.

      Note: array element indexes are 0-based.

      This method is equivalent to: 

         node.get(index) != null

      NOTE: this method will return true for explicitly added null values.

      Parameters:
      index - Index to check
      Returns:
      True if this node is a JSON Object node, and has a property entry with specified name (with any value, including null value)

    • hasNonNull

      public boolean hasNonNull(String fieldName)
      Method that is similar to has(String), but that will return false for explicitly added nulls.

      This method is functionally equivalent to: 

         node.get(fieldName) != null && !node.get(fieldName).isNull()
      Since:
      2.1

    • hasNonNull

      public boolean hasNonNull(int index)
      Method that is similar to has(int), but that will return false for explicitly added nulls.

      This method is equivalent to: 

         node.get(index) != null && !node.get(index).isNull()
      Since:
      2.1

    • iterator

      public final Iterator<JsonNode> iterator()
      Same as calling elements(); implemented so that convenience "for-each" loop can be used for looping over elements of JSON Array constructs.
      Specified by:
      iterator in interface Iterable<JsonNode>

    • elements

      public Iterator<JsonNode> elements()
      Method for accessing all value nodes of this Node, iff this node is a JSON Array or Object node. In case of Object node, field names (keys) are not included, only values. For other types of nodes, returns empty iterator.

    • fields

      public Iterator<Map.Entry<String,JsonNode>> fields()
      Returns:
      Iterator that can be used to traverse all key/value pairs for object nodes; empty iterator (no contents) for other types

    • properties

      public Set<Map.Entry<String,JsonNode>> properties()
      Accessor that will return properties of ObjectNode similar to how Map.entrySet() works; for other node types will return empty Set.
      Returns:
      Set of properties, if this node is an ObjectNode (isObject() returns true); empty Set otherwise.
      Since:
      2.15

    • findValue

      public abstract JsonNode findValue(String fieldName)
      Method for finding the first JSON Object field with specified name in this node or its child nodes, and returning value it has. If no matching field is found in this node or its descendants, returns null.

      Note that traversal is done in document order (that is, order in which nodes are iterated if using elements())

      Parameters:
      fieldName - Name of field to look for
      Returns:
      Value of first matching node found, if any; null if none

    • findValues

      public final List<JsonNode> findValues(String fieldName)
      Method for finding JSON Object fields with specified name -- both immediate child values and descendants -- and returning found ones as a List. Note that sub-tree search ends when matching field is found, so possible children of result nodes are not included. If no matching fields are found in this node or its descendants, returns an empty List.
      Parameters:
      fieldName - Name of field to look for

    • findValuesAsText

      public final List<String> findValuesAsText(String fieldName)
      Similar to findValues(java.lang.String), but will additionally convert values into Strings, calling asText().

    • findPath

      public abstract JsonNode findPath(String fieldName)
      Method similar to findValue(java.lang.String), but that will return a "missing node" instead of null if no field is found. Missing node is a specific kind of node for which isMissingNode() returns true; and all value access methods return empty or missing value.
      Parameters:
      fieldName - Name of field to look for
      Returns:
      Value of first matching node found; or if not found, a "missing node" (non-null instance that has no value)

    • findParent

      public abstract JsonNode findParent(String fieldName)
      Method for finding a JSON Object that contains specified field, within this node or its descendants. If no matching field is found in this node or its descendants, returns null.
      Parameters:
      fieldName - Name of field to look for
      Returns:
      Value of first matching node found, if any; null if none

    • findParents

      public final List<JsonNode> findParents(String fieldName)
      Method for finding a JSON Object that contains specified field, within this node or its descendants. If no matching field is found in this node or its descendants, returns null.
      Parameters:
      fieldName - Name of field to look for
      Returns:
      Value of first matching node found, if any; null if none

    • findValues

      public abstract List<JsonNode> findValues(String fieldName, List<JsonNode> foundSoFar)

    • findValuesAsText

      public abstract List<String> findValuesAsText(String fieldName, List<String> foundSoFar)

    • findParents

      public abstract List<JsonNode> findParents(String fieldName, List<JsonNode> foundSoFar)

    • withObject

      public ObjectNode withObject(String exprOrProperty)
      Method that works in one of possible ways, depending on whether exprOrProperty is a valid JsonPointer expression or not (valid expression is either empty String "" or starts with leading slash / character). If it is, works as a short-cut to: 
        withObject(JsonPointer.compile(exprOrProperty));
      If it is NOT a valid JsonPointer expression, value is taken as a literal Object property name and calls is alias for 
        withObjectProperty(exprOrProperty);
      Parameters:
      exprOrProperty - JsonPointer expression to use (if valid as one), or, if not (no leading "/"), property name to match.
      Returns:
      ObjectNode found or created
      Since:
      2.14 (but semantics before 2.16 did NOT allow for non-JsonPointer expressions)

    • withObject

      public final ObjectNode withObject(String expr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
      Short-cut equivalent to: 
        withObject(JsonPointer.compile(expr), overwriteMode, preferIndex);
      Since:
      2.14

    • withObject

      public final ObjectNode withObject(JsonPointer ptr)
      Same as withObject(JsonPointer, OverwriteMode, boolean) but with defaults of OvewriteMode#NULLS (overwrite mode) and true for preferIndex (that is, will try to consider JsonPointer segments index if at all possible and only secondarily as property name
      Parameters:
      ptr - JsonPointer that indicates path to use for Object value to return (potentially creating as necessary)
      Returns:
      ObjectNode found or created
      Since:
      2.14

    • withObject

      public ObjectNode withObject(JsonPointer ptr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
      Method that can be called on Object or Array nodes, to access a Object-valued node pointed to by given JsonPointer, if such a node exists: or if not, an attempt is made to create one and return it. For example, on document 
        { "a" : {
       "b" : {
          "c" : 13
       }
    }
  }
      calling method with JsonPointer of /a/b would return ObjectNode 
        { "c" : 13 }

      In cases where path leads to "missing" nodes, a path is created. So, for example, on above document, and JsonPointer of /a/x an empty ObjectNode would be returned and the document would look like: 

        { "a" : {
       "b" : {
          "c" : 13
       },
       "x" : { }
    }
  }
      Finally, if the path is incompatible with the document -- there is an existing JsonNode through which expression cannot go -- a replacement is attempted if (and only if) conversion is allowed as per overwriteMode passed in. For example, with above document and expression of /a/b/c, conversion is allowed if passing OverwriteMode.SCALARS or OvewriteMode.ALL, and resulting document would look like: 
        { "a" : {
       "b" : {
          "c" : { }
       },
       "x" : { }
    }
  }
      but if different modes (NONE or NULLS) is passed, an exception is thrown instead.
      Parameters:
      ptr - Pointer that indicates path to use for ObjectNode value to return (potentially creating one as necessary)
      overwriteMode - Defines which node types may be converted in case of incompatible JsonPointer expression: if conversion not allowed, UnsupportedOperationException is thrown.
      preferIndex - When creating a path (for empty or replacement), and path contains segment that may be an array index (simple integer number like 3), whether to construct an ArrayNode (true) or ObjectNode (false). In latter case matching property with quoted number (like "3") is used within Object.
      Returns:
      ObjectNode found or created
      Throws:
      UnsupportedOperationException - if a conversion would be needed for given JsonPointer, document, but was not allowed for the type encountered
      Since:
      2.14

    • withObjectProperty

      public ObjectNode withObjectProperty(String propName)
      Method similar to withObject(JsonPointer, OverwriteMode, boolean) -- basically short-cut to: 
         withObject(JsonPointer.compile("/"+propName), OverwriteMode.NULLS, false);
      that is, only matches immediate property on ObjectNode and will either use an existing ObjectNode that is value of the property, or create one if no value or value is NullNode.
      Will fail with an exception if:
      • Node method called on is NOT ObjectNode
      • Property has an existing value that is NOT NullNode (explicit null)
      Parameters:
      propName - Name of property that has or will have ObjectNode as value
      Returns:
      ObjectNode value of given property (existing or created)
      Since:
      2.16

    • with

      @Deprecated public <T extends JsonNode> T with(String exprOrProperty)
      Deprecated.
      Since 2.14 use withObject(String) instead
      Method that works in one of possible ways, depending on whether exprOrProperty is a valid JsonPointer expression or not (valid expression is either empty String "" or starts with leading slash / character). If it is, works as a short-cut to: 
        withObject(JsonPointer.compile(exprOrProperty));
      If it is NOT a valid JsonPointer expression, value is taken as a literal Object property name and traversed like a single-segment JsonPointer.

      NOTE: before Jackson 2.14 behavior was always that of non-expression usage; that is, exprOrProperty was always considered as a simple property name.

    • withArray

      public <T extends JsonNode> T withArray(String exprOrProperty)
      Method that works in one of possible ways, depending on whether exprOrProperty is a valid JsonPointer expression or not (valid expression is either empty String "" or starts with leading slash / character). If it is, works as a short-cut to: 
        withObject(JsonPointer.compile(exprOrProperty));
      If it is NOT a valid JsonPointer expression, value is taken as a literal Object property name and traversed like a single-segment JsonPointer.

      NOTE: before Jackson 2.14 behavior was always that of non-expression usage; that is, exprOrProperty was always considered as a simple property name.

      Parameters:
      exprOrProperty - Either JsonPointer expression for full access (if valid pointer expression), or the name of property for the ArrayNode.
      Returns:
      ArrayNode found or created

    • withArray

      public ArrayNode withArray(String expr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
      Short-cut equivalent to: 
        withArray(JsonPointer.compile(expr), overwriteMode, preferIndex);
      Since:
      2.14

    • withArray

      public final ArrayNode withArray(JsonPointer ptr)
      Same as withArray(JsonPointer, OverwriteMode, boolean) but with defaults of OvewriteMode#NULLS (overwrite mode) and true for preferIndex.
      Parameters:
      ptr - Pointer that indicates path to use for ArrayNode to return (potentially creating as necessary)
      Returns:
      ArrayNode found or created
      Since:
      2.14

    • withArray

      public ArrayNode withArray(JsonPointer ptr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
      Method that can be called on Object or Array nodes, to access a Array-valued node pointed to by given JsonPointer, if such a node exists: or if not, an attempt is made to create one and return it. For example, on document 
        { "a" : {
       "b" : [ 1, 2 ]
    }
  }
      calling method with JsonPointer of /a/b would return Array 
        [ 1, 2 ]

      In cases where path leads to "missing" nodes, a path is created. So, for example, on above document, and JsonPointer of /a/x an empty ArrayNode would be returned and the document would look like: 

        { "a" : {
       "b" : [ 1, 2 ],
       "x" : [ ]
    }
  }
      Finally, if the path is incompatible with the document -- there is an existing JsonNode through which expression cannot go -- a replacement is attempted if (and only if) conversion is allowed as per overwriteMode passed in. For example, with above document and expression of /a/b/0, conversion is allowed if passing OverwriteMode.SCALARS or OvewriteMode.ALL, and resulting document would look like: 
        { "a" : {
       "b" : [ [ ], 2 ],
       "x" : [ ]
    }
  }
      but if different modes (NONE or NULLS) is passed, an exception is thrown instead.
      Parameters:
      ptr - Pointer that indicates path to use for ArrayNode value to return (potentially creating it as necessary)
      overwriteMode - Defines which node types may be converted in case of incompatible JsonPointer expression: if conversion not allowed, an exception is thrown.
      preferIndex - When creating a path (for empty or replacement), and path contains segment that may be an array index (simple integer number like 3), whether to construct an ArrayNode (true) or ObjectNode (false). In latter case matching property with quoted number (like "3") is used within Object.
      Returns:
      ArrayNode found or created
      Throws:
      UnsupportedOperationException - if a conversion would be needed for given JsonPointer, document, but was not allowed for the type encountered
      Since:
      2.14

    • withArrayProperty

      public ArrayNode withArrayProperty(String propName)
      Method similar to withArray(JsonPointer, OverwriteMode, boolean) -- basically short-cut to: 
         withArray(JsonPointer.compile("/"+propName), OverwriteMode.NULLS, false);
      that is, only matches immediate property on ObjectNode and will either use an existing ArrayNode that is value of the property, or create one if no value or value is NullNode.
      Will fail with an exception if:
      • Node method called on is NOT ObjectNode
      • Property has an existing value that is NOT NullNode (explicit null)
      Parameters:
      propName - Name of property that has or will have ArrayNode as value
      Returns:
      ArrayNode value of given property (existing or created)
      Since:
      2.16

    • equals

      public boolean equals(Comparator<JsonNode> comparator, JsonNode other)
      Entry method for invoking customizable comparison, using passed-in Comparator object. Nodes will handle traversal of structured types (arrays, objects), but defer to comparator for scalar value comparisons. If a "natural" Comparator is passed -- one that simply calls equals() on one of arguments, passing the other -- implementation is the same as directly calling equals() on node.

      Default implementation simply delegates to passed in comparator, with this as the first argument, and other as the second argument.

      Parameters:
      comparator - Object called to compare two scalar JsonNode instances, and return either 0 (are equals) or non-zero (not equal)
      Since:
      2.6

    • toString

      public abstract String toString()
      Method that will produce (as of Jackson 2.10) valid JSON using default settings of databind, as String. If you want other kinds of JSON output (or output formatted using one of other Jackson-supported data formats) make sure to use ObjectMapper or ObjectWriter to serialize an instance, for example: 
         String json = objectMapper.writeValueAsString(rootNode);

      Note: method defined as abstract to ensure all implementation classes explicitly implement method, instead of relying on Object.toString() definition.

      Overrides:
      toString in class Object

    • toPrettyString

      public String toPrettyString()
      Alternative to toString() that will serialize this node using Jackson default pretty-printer.
      Since:
      2.10

    • equals

      public abstract boolean equals(Object o)
      Equality for node objects is defined as full (deep) value equality. This means that it is possible to compare complete JSON trees for equality by comparing equality of root nodes.

      Note: marked as abstract to ensure all implementation classes define it properly and not rely on definition from Object.

      Overrides:
      equals in class Object