Module tools.jackson.databind
Package tools.jackson.databind

Class JsonNode

java.lang.Object
tools.jackson.databind.JacksonSerializable.Base
tools.jackson.databind.JsonNode
All Implemented Interfaces:
Iterable<JsonNode>, TreeNode, JacksonSerializable
Direct Known Subclasses:
BaseJsonNode
public abstract class JsonNode extends JacksonSerializable.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 tools.jackson.databind.node.

Note that it is possible to "read" from nodes, using method TreeNode.traverse(tools.jackson.core.ObjectReadContext), 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 tools.jackson.databind.JacksonSerializable

    JacksonSerializable.Base

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    JsonNode()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract JsonNode
    _at(JsonPointer ptr)
    Helper method used by other methods for traversing the next step of given path expression, and returning matching value node if any: if no match, null is returned.
    protected <T> T
    _reportRequiredViolation(String msgTemplate, Object... args)
    Helper method that throws DatabindException as a result of violating "required-constraint" for this node (for required(java.lang.String) or related methods).
    protected <T> T
    _reportUnsupportedOperation(String msgTemplate, Object... args)
     
    protected <T extends JsonNode>
    T
    _this()
     
    abstract BigInteger
    asBigInteger()
    Method similar to bigIntegerValue() but in addition to coercing Number values (same as bigIntegerValue()), will also try to coerce a couple of additional types (or cases): JSON Floating-point numbers with fractions (ones without fractions are ok for bigIntegerValue()) will be truncated to integer value (like with BigDecimal.toBigInteger())) JSON Strings that represent JSON Numbers ("stringified" numbers) JSON Null (converted to 0)) POJO nodes that contain Number values
    abstract BigInteger
    asBigInteger(BigInteger defaultValue)
    Method similar to asBigInteger(), but that will return specified defaultValue if this node cannot be converted to BigInteger.
    abstract Optional<BigInteger>
    asBigIntegerOpt()
    Method similar to bigIntegerValue(), but that will return empty (Optional.empty()) if this node cannot be converted to Java BigInteger.
    abstract boolean
    asBoolean()
    Method that will try to convert value of this node to a Java boolean.
    abstract boolean
    asBoolean(boolean defaultValue)
    Similar to asBoolean(), but instead of throwing an exception for non-coercible values, will return specified default value.
    abstract Optional<Boolean>
    asBooleanOpt()
    Similar to asBoolean(), but instead of throwing an exception for non-coercible values, will return Optional.empty().
    abstract BigDecimal
    asDecimal()
    Method that will try to access value of this node as a BigDecimal: but if node value cannot be expressed exactly as a BigDecimal, a JsonNodeException will be thrown.
    abstract BigDecimal
    asDecimal(BigDecimal defaultValue)
    Method similar to asDecimal(), but that will return defaultValue if this node cannot be coerced to Java BigDecimal.
    abstract Optional<BigDecimal>
    asDecimalOpt()
    Method similar to asDecimal(), but that will return empty Optional (Optional.empty()) if this node cannot be coerced to BigDecimal.
    abstract double
    asDouble()
    Method similar to doubleValue() but in addition to coercing Number values will also try coerce couple of additional types: JSON String that represents JSON Numbers ("stringified" numbers) JSON Null (converted to 0.0d) POJO nodes that contain Number values
    abstract double
    asDouble(double defaultValue)
    Method similar to asDouble(), but that will return defaultValue if this node cannot be coerced to double.
    abstract OptionalDouble
    asDoubleOpt()
    Method similar to asDouble(), but that will return (OptionalDouble.empty()) if this node cannot be coerced to double.
    abstract float
    asFloat()
    Method similar to floatValue() but in addition to coercing Number values will also try coerce couple of additional types: JSON String that represents JSON Numbers ("stringified" numbers) JSON Null (converted to 0.0f) POJO nodes that contain Number values
    abstract float
    asFloat(float defaultValue)
    Method similar to asFloat(), but that will return defaultValue if this node cannot be coerced to float.
    abstract Optional<Float>
    asFloatOpt()
    Method similar to asFloat(), but that will return (Optional.empty()) if this node cannot be coerced to float.
    abstract int
    asInt()
    Method similar to intValue() but in addition to coercing Number values (same as intValue()), will also try to coerce a couple of additional types (or cases): JSON Floating-point numbers with fractions (ones without fractions are ok for intValue()) will be truncated to int (if (and only if) they fit in int range).
    abstract int
    asInt(int defaultValue)
    Method similar to intValue(), but that will return specified defaultValue if this node cannot be converted to int.
    abstract OptionalInt
    asIntOpt()
    Method similar to asInt(), but that will return (OptionalInt.empty()) if this node cannot be coerced to int.
    abstract long
    asLong()
    Method similar to longValue() but in addition to coercing Number values (same as longValue()), will also try to coerce a couple of additional types (or cases): JSON Floating-point numbers with fractions (ones without fractions are ok for longValue()) will be truncated to long (if (and only if) they fit in long range).
    abstract long
    asLong(long defaultValue)
    Method similar to asLong(), but that will return specified defaultValue if this node cannot be coerced to long (instead of throwing an exception).
    abstract OptionalLong
    asLongOpt()
    Method similar to asLong(), but that will return (OptionalLong.empty()) if this node cannot be coerced to long.
    Optional<JsonNode>
    asOptional()
    Method that will return a JsonNode wrapped in Java's Optional.
    abstract short
    asShort()
    Method similar to shortValue() but in addition to coercing Number values (same as shortValue()), will also try to coerce a couple of additional types (or cases): JSON Floating-point numbers with fractions (ones without fractions are ok for shortValue()) will be truncated to short (if (and only if) they fit in short range).
    abstract short
    asShort(short defaultValue)
    Method similar to shortValue(), but that will return specified defaultValue if this node cannot be converted to short.
    abstract Optional<Short>
    asShortOpt()
    Method similar to asShort(), but that will return (Optional.empty()) if this node cannot be coerced to short.
    abstract String
    asString()
    Method that will try to convert value of this node to a String.
    abstract String
    asString(String defaultValue)
    Similar to asString(), but instead of throwing an exception for non-coercible values, will return specified default value.
    abstract Optional<String>
    asStringOpt()
    Similar to asString(), but instead of throwing an exception for non-coercible values, will return Optional.empty().
    final String
    asText()
    Deprecated.
    Use asString() instead.
    String
    asText(String defaultValue)
    Deprecated.
    Use asString(String) instead.
    final JsonNode
    at(String jsonPtrExpr)
    Convenience method that is functionally equivalent to:
    final JsonNode
    at(JsonPointer ptr)
    Method for locating node specified by given JSON pointer instances.
    abstract BigInteger
    bigIntegerValue()
    Method that will try to access value of this node as a BigInteger, but if node value cannot be expressed exactly as a BigInteger, a JsonNodeException will be thrown.
    abstract BigInteger
    bigIntegerValue(BigInteger defaultValue)
    Method similar to bigIntegerValue(), but that will return specified defaultValue if this node cannot be converted to Java BigInteger.
    abstract Optional<BigInteger>
    bigIntegerValueOpt()
    Method similar to bigIntegerValue(), but that will return empty (Optional.empty()) if this node cannot be converted to Java BigInteger.
    abstract byte[]
    binaryValue()
    Method that will try to access value of this node as binary value (Java byte[]) which works if (and only if) node contains binary value (for JSON, Base64-encoded String, for other formats native binary value): if not, a JsonNodeException will be thrown.
    abstract boolean
    booleanValue()
    Method that will try to access value of this node as a Java boolean which works if (and only if) node contains JSON boolean value: if not, a JsonNodeException will be thrown.
    abstract boolean
    booleanValue(boolean defaultValue)
    Method similar to booleanValue(), but that will return specified defaultValue if this node does not contain a JSON boolean.
    abstract Optional<Boolean>
    booleanValueOpt()
    Method similar to booleanValue(), but that will return Optional.empty() if this node does not contain a JSON boolean.
    boolean
    canConvertToExactIntegral()
    Method that can be used to check whether contained value is numeric (returns true for isNumber()) and can be converted without loss 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 can be converted without loss to int (that is, its value fits in Java's 32-bit signed integer type, int and if it is a floating-point number, it does not have fractional part).
    boolean
    canConvertToLong()
    Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND can be converted without loss to long (that is, its value fits in Java's 64-bit signed integer type, long and if it is a floating-point number, it does not have fractional part).
    boolean
    canConvertToShort()
    Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND can be converted without loss to short (that is, its value fits in Java's 16-bit signed integer type, short and if it is a floating-point number, it does not have fractional part).
    abstract BigDecimal
    decimalValue()
    Method that will try to access value of this node as a Java BigDecimal: but if node value cannot be expressed exactly as a BigDecimal, a JsonNodeException will be thrown.
    abstract BigDecimal
    decimalValue(BigDecimal defaultValue)
    Method similar to decimalValue(), but that will return defaultValue if this node cannot be coerced to Java BigDecimal.
    abstract Optional<BigDecimal>
    decimalValueOpt()
    Method similar to decimalValue(), but that will return empty Optional (Optional.empty()) if this node cannot be coerced to BigDecimal.
    abstract JsonNode
    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.
    abstract double
    doubleValue()
    Method that will try to access value of this node as a double: but if node value cannot be expressed exactly as a double, a JsonNodeException will be thrown.
    abstract double
    doubleValue(double defaultValue)
    Method similar to doubleValue(), but that will return specified defaultValue if this node cannot be converted to double.
    abstract OptionalDouble
    doubleValueOpt()
    Method similar to doubleValue(), but that will return empty OptionalLong (OptionalDouble.empty()) if this node cannot be converted to Java double.
    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.
    abstract JsonNode
    findParent(String propertyName)
    Method for finding a JSON Object that contains specified field, within this node or its descendants.
    final List<JsonNode>
    findParents(String propertyName)
    Method for finding a JSON Object that contains specified field, within this node or its descendants.
    abstract List<JsonNode>
    findParents(String propertyName, List<JsonNode> foundSoFar)
     
    abstract JsonNode
    findPath(String propertyName)
    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 propertyName)
    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 propertyName)
    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 propertyName, List<JsonNode> foundSoFar)
     
    final List<String>
    findValuesAsString(String propertyName)
    Similar to findValues(java.lang.String), but will additionally convert values into Strings, calling asText().
    abstract List<String>
    findValuesAsString(String propertyName, List<String> foundSoFar)
     
    abstract float
    floatValue()
    Method that will try to access value of this node as a Java float: but if node value cannot be expressed exactly as a float, a JsonNodeException will be thrown.
    abstract float
    floatValue(float defaultValue)
    Method similar to floatValue(), but that will return specified defaultValue if this node cannot be converted to float.
    abstract Optional<Float>
    floatValueOpt()
    Method similar to floatValue(), but that will return empty Optional<Float> (Optional.empty()) if this node cannot be converted to Java float.
    void
    forEachEntry(BiConsumer<? super String,? super JsonNode> action)
    If this node is an ObjectNode, performs the given action for each property (key, value pair) until all entries have been processed or the action throws an exception.
    abstract JsonNode
    get(int index)
    Method for accessing value of the specified element of an array node.
    JsonNode
    get(String propertyName)
    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 propertyName)
    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 propertyName)
    Method that is similar to has(String), but that will return false for explicitly added nulls.
    abstract int
    intValue()
    Method that will try to access value of this node as a Java int: but if node value cannot be expressed exactly as an int, a JsonNodeException will be thrown.
    abstract int
    intValue(int defaultValue)
    Method similar to intValue(), but that will return specified defaultValue if this node cannot be converted to Java int.
    abstract OptionalInt
    intValueOpt()
    Method similar to intValue(), but that will return empty OptionalInt (OptionalInt.empty()) if this node cannot be converted to Java int.
    boolean
    isArray()
     
    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").
    boolean
    isContainer()
     
    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()
     
    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()
     
    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
    isString()
    Method that checks whether this node represents JSON String value.
    boolean
    isTextual()
    Deprecated.
    Use isString() instead.
    final boolean
    isValueNode()
     
    final Iterator<JsonNode>
    iterator()
    Implemented so that convenience "for-each" loop can be used for looping over elements of JSON Array constructs.
    abstract long
    longValue()
    Method that will try to access value of this node as a Java long: but if node value cannot be expressed exactly as a long, a JsonNodeException will be thrown.
    abstract long
    longValue(long defaultValue)
    Method similar to longValue(), but that will return specified defaultValue if this node cannot be converted to long.
    abstract OptionalLong
    longValueOpt()
    Method similar to longValue(), but that will return empty OptionalLong (OptionalLong.empty()) if this node cannot be converted to Java long.
    abstract Number
    numberValue()
    Method that will try to access value of this node as Number that accurately represents its value, if (and only if) this is a number node (returns true for isNumber()).
    Optional<JsonNode>
    optional(int index)
    Method for accessing value of the specified element of an array node, wrapped in an Optional.
    Optional<JsonNode>
    optional(String propertyName)
    Method for accessing value of the specified field of an object node.
    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 propertyName)
    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.
    Collection<String>
    propertyNames()
     
    Stream<Map.Entry<String,JsonNode>>
    propertyStream()
    Returns a stream of all properties (key, value pairs) of this Node, iff this node is an an ObjectNode.
    <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.
    abstract 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).
    abstract JsonNode
    required(String propertyName)
    Method is functionally equivalent to path(propertyName).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 propertyName (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).
    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).
    <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).
    abstract short
    shortValue()
    Method that will try to access value of this node as 16-bit signed integer value (Java short): but if node value cannot be expressed exactly as a short, a JsonNodeException will be thrown.
    abstract short
    shortValue(short defaultValue)
    Method similar to shortValue(), but that will return specified defaultValue if this node cannot be converted to Java short.
    abstract Optional<Short>
    shortValueOpt()
    Method similar to shortValue(), but that will return empty Optional<Short> (Optional.empty()) if this node cannot be converted to Java short.
    int
    size()
     
    final Spliterator<JsonNode>
    spliterator()
     
    abstract String
    stringValue()
    Method that will try to access value of this node as a Java String which works if (and only if) node contains JSON String or null value: if not, a JsonNodeException will be thrown.
    abstract String
    stringValue(String defaultValue)
    Method similar to stringValue(), but that will return specified defaultValue if this node does not contain a JSON String.
    abstract Optional<String>
    stringValueOpt()
    Method similar to stringValue(), but that will return Optional.empty() if this node does not contain a JSON String (NOTE: JSON null is not considered a String here)
    final String
    textValue()
    Deprecated.
    Use asString() instead.
    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.
    Collection<JsonNode>
    values()
    Method for accessing all value nodes of this Node, iff this node is a JSON Array or Object node.
    Stream<JsonNode>
    valueStream()
    Returns a stream of all value nodes of this Node, iff this node is an ArrayNode or ObjectNode.
    ArrayNode
    withArray(String exprOrProperty)
    Short-cut equivalent to:
    ArrayNode
    withArray(String expr, JsonNode.OverwriteMode overwriteMode, boolean preferIndex)
    Short-cut equivalent to:
    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.
    ArrayNode
    withArrayProperty(String propName)
    Method similar to withArray(JsonPointer, OverwriteMode, boolean) -- basically short-cut to:
    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:
    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
    withObjectProperty(String propName)
    Method similar to withObject(JsonPointer, OverwriteMode, boolean) -- basically short-cut to:

    Methods inherited from class tools.jackson.databind.JacksonSerializable.Base

    isEmpty

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach

    Methods inherited from interface tools.jackson.databind.JacksonSerializable

    serialize, serializeWithType

    Methods inherited from interface tools.jackson.core.TreeNode

    asToken, isEmbeddedValue, numberType, traverse

  • Constructor Details

    • JsonNode

      protected JsonNode()

  • Method Details

    • deepCopy

      public abstract JsonNode 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.

    • size

      public int size()
      Specified by:
      size in interface TreeNode

    • isEmpty

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

    • isValueNode

      public final boolean isValueNode()
      Specified by:
      isValueNode in interface TreeNode

    • isContainer

      public boolean isContainer()
      Specified by:
      isContainer in interface TreeNode

    • isMissingNode

      public boolean isMissingNode()
      Specified by:
      isMissingNode in interface TreeNode

    • isArray

      public boolean isArray()
      Specified by:
      isArray in interface TreeNode

    • isObject

      public boolean isObject()
      Specified by:
      isObject in interface TreeNode

    • 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
      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 propertyName)
      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
      Returns:
      Node that represent value of the specified field, if this node is an object and has value for the specified field. Null otherwise.

    • optional

      public Optional<JsonNode> optional(int index)
      Method for accessing value of the specified element of an array node, wrapped in an Optional. For other nodes, an empty Optional 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(), an empty Optional 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 wrapped in an Optional, not an empty Optional.

      Returns:
      Optional containing the node that represents the value of the specified element, if this node is an array and has the specified element and otherwise, an empty Optional, never null.

    • optional

      public Optional<JsonNode> optional(String propertyName)
      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, empty Optional is returned.

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

      Returns:
      Optional that may contain value of the specified field, if this node is an object and has value for the specified field. Empty Optional otherwise never null.

    • path

      public abstract JsonNode path(String propertyName)
      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

    • 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

    • propertyNames

      public Collection<String> propertyNames()
      Specified by:
      propertyNames in interface TreeNode

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

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

    • _at

      protected abstract JsonNode _at(JsonPointer ptr)
      Helper method used by other methods for traversing the next step of given path expression, and returning matching value node if any: if no match, null is returned.
      Parameters:
      ptr - Path expression to use
      Returns:
      Either matching JsonNode for the first step of path or null if no match (including case that this node is not a container)

    • getNodeType

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

    • 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()

    • isDouble

      public boolean isDouble()

    • isBigDecimal

      public boolean isBigDecimal()

    • isBigInteger

      public boolean isBigInteger()

    • isString

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

    • isTextual

      @Deprecated public boolean isTextual()
      Deprecated.
      Use isString() instead.

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

    • 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, isString() will return false if this method returns true.
      Returns:
      True if this node represents base64 encoded binary data

    • canConvertToShort

      public boolean canConvertToShort()
      Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND can be converted without loss to short (that is, its value fits in Java's 16-bit signed integer type, short and if it is a floating-point number, it does not have fractional part).

      NOTE: this method does not consider possible value type conversion from non-number types like JSON String into Number; so even if this method returns false, it is possible that asShort() could still succeed.

    • canConvertToInt

      public boolean canConvertToInt()
      Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND can be converted without loss to int (that is, its value fits in Java's 32-bit signed integer type, int and if it is a floating-point number, it does not have fractional part).

      NOTE: this method does not consider possible value type conversion from non-number types like JSON String into Number; so even if this method returns false, it is possible that asInt() could still succeed.

    • canConvertToLong

      public boolean canConvertToLong()
      Method that can be used to check whether this node is a numeric node (isNumber() would return true) AND can be converted without loss to long (that is, its value fits in Java's 64-bit signed integer type, long and if it is a floating-point number, it does not have fractional part).

      NOTE: this method does not consider possible value type conversion from non-number types like JSON String into Number; so even if this method returns false, it is possible that asLong() could still succeed.

    • canConvertToExactIntegral

      public boolean canConvertToExactIntegral()
      Method that can be used to check whether contained value is numeric (returns true for isNumber()) and can be converted without loss 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 cannot 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.

    • asOptional

      public Optional<JsonNode> asOptional()
      Method that will return a JsonNode wrapped in Java's Optional. All nodes except of MissingNode will return non-empty Optional; MissingNode will return empty Optional.
      Returns:
      Optional<JsonNode> containing this node, or Optional.empty() if this is a MissingNode.

    • stringValue

      public abstract String stringValue()
      Method that will try to access value of this node as a Java String which works if (and only if) node contains JSON String or null value: if not, a JsonNodeException will be thrown. In case of JSON null, Java null is returned.

      NOTE: for more conversions, use asString() instead.

      NOTE: in Jackson 2.x, this method was named textValue().

      Returns:
      String value this node represents (if JSON String), null for JSON null
      Throws:
      JsonNodeException - if node value is not a JSON String or Null value

    • stringValue

      public abstract String stringValue(String defaultValue)
      Method similar to stringValue(), but that will return specified defaultValue if this node does not contain a JSON String. This default value case includes JSON null.
      Parameters:
      defaultValue - Value to return if this node does not contain a JSON String.
      Returns:
      Java String value this node represents (if JSON String); defaultValue otherwise -- only returns null if defaultValue is null

    • stringValueOpt

      public abstract Optional<String> stringValueOpt()
      Method similar to stringValue(), but that will return Optional.empty() if this node does not contain a JSON String (NOTE: JSON null is not considered a String here)
      Returns:
      Optional<String> value (if node represents JSON String); Optional.empty() otherwise (including for JSON null)

    • textValue

      @Deprecated public final String textValue()
      Deprecated.
      Use asString() instead.

    • asString

      public abstract String asString()
      Method that will try to convert value of this node to a String. JSON Strings map naturally; other scalars map to their string representation (including Binary data as Base64 encoded String); JSON nulls map to empty String. Other values (including structured types like Objects and Arrays, and "missing" value) will result in a JsonNodeException being thrown.

      NOTE: this is NOT same as toString() in that result is

      NOT VALID ENCODED JSON

      for all nodes (although is for some, like NumberNodes and BooleanNodes).
      Returns:
      String representation of this node, if coercible; exception otherwise
      Throws:
      JsonNodeException - if node cannot be coerced to a String

    • asString

      public abstract String asString(String defaultValue)
      Similar to asString(), but instead of throwing an exception for non-coercible values, will return specified default value.

    • asStringOpt

      public abstract Optional<String> asStringOpt()
      Similar to asString(), but instead of throwing an exception for non-coercible values, will return Optional.empty().

    • asText

      @Deprecated public final String asText()
      Deprecated.
      Use asString() instead.

    • asText

      @Deprecated public String asText(String defaultValue)
      Deprecated.
      Use asString(String) instead.

    • binaryValue

      public abstract byte[] binaryValue()
      Method that will try to access value of this node as binary value (Java byte[]) which works if (and only if) node contains binary value (for JSON, Base64-encoded String, for other formats native binary value): if not, a JsonNodeException will be thrown. To check if this method can be used, you may call isBinary().

      Returns:
      Binary value this node represents (if node contains binary value)
      Throws:
      JsonNodeException - if node does not contain a Binary value (a

    • booleanValue

      public abstract boolean booleanValue()
      Method that will try to access value of this node as a Java boolean which works if (and only if) node contains JSON boolean value: if not, a JsonNodeException will be thrown.

      NOTE: for more lenient conversions, use asBoolean()

      Returns:
      boolean value this node represents (if JSON boolean)
      Throws:
      JsonNodeException - if node does not represent a JSON boolean value

    • booleanValue

      public abstract boolean booleanValue(boolean defaultValue)
      Method similar to booleanValue(), but that will return specified defaultValue if this node does not contain a JSON boolean.
      Parameters:
      defaultValue - Value to return if this node does not contain a JSON boolean.
      Returns:
      Java boolean value this node represents (if JSON boolean); defaultValue otherwise

    • booleanValueOpt

      public abstract Optional<Boolean> booleanValueOpt()
      Method similar to booleanValue(), but that will return Optional.empty() if this node does not contain a JSON boolean.
      Returns:
      Optional<Boolean> value (if node represents JSON boolean); Optional.empty() otherwise

    • asBoolean

      public abstract 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; null maps to false and Strings 'true' and 'false' map to corresponding values. Other values (including structured types like Objects and Arrays) will result in a JsonNodeException being thrown.
      Returns:
      Boolean value this node represents, if coercible; exception otherwise
      Throws:
      JsonNodeException - if node cannot be coerced to a Java boolean

    • asBoolean

      public abstract boolean asBoolean(boolean defaultValue)
      Similar to asBoolean(), but instead of throwing an exception for non-coercible values, will return specified default value.

    • asBooleanOpt

      public abstract Optional<Boolean> asBooleanOpt()
      Similar to asBoolean(), but instead of throwing an exception for non-coercible values, will return Optional.empty().

    • numberValue

      public abstract Number numberValue()
      Method that will try to access value of this node as Number that accurately represents its value, if (and only if) this is a number node (returns true for isNumber()). If this node is NOT a number node, a JsonNodeException will be thrown.
      Returns:
      Number value this node contains, if numeric node

    • shortValue

      public abstract short shortValue()
      Method that will try to access value of this node as 16-bit signed integer value (Java short): but if node value cannot be expressed exactly as a short, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Integer values that fit in Java 16-bit signed short range
      • JSON Floating-point values that fit in Java 16-bit signed short range AND do not have fractional part.

      Returns:
      Short value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to Java short

    • shortValue

      public abstract short shortValue(short defaultValue)
      Method similar to shortValue(), but that will return specified defaultValue if this node cannot be converted to Java short.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to Java short
      Returns:
      Java short value this node represents, if possible to accurately represent; defaultValue otherwise

    • shortValueOpt

      public abstract Optional<Short> shortValueOpt()
      Method similar to shortValue(), but that will return empty Optional<Short> (Optional.empty()) if this node cannot be converted to Java short.
      Returns:
      Java short value this node represents, as Optional<Short>, if possible to accurately represent; Optional.empty() otherwise

    • asShort

      public abstract short asShort()
      Method similar to shortValue() but in addition to coercing Number values (same as shortValue()), will also try to coerce a couple of additional types (or cases):
      • JSON Floating-point numbers with fractions (ones without fractions are ok for shortValue()) will be truncated to short (if (and only if) they fit in short range).
      • JSON Strings that represent JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0))
      • POJO nodes that contain Number values
      Returns:
      short value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to short

    • asShort

      public abstract short asShort(short defaultValue)
      Method similar to shortValue(), but that will return specified defaultValue if this node cannot be converted to short.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to short
      Returns:
      short value this node represents, if possible to accurately represent; defaultValue otherwise

    • asShortOpt

      public abstract Optional<Short> asShortOpt()
      Method similar to asShort(), but that will return (Optional.empty()) if this node cannot be coerced to short.
      Returns:
      Optional<Short> value this node represents, if possible to accurately represent; Optional.empty() otherwise

    • intValue

      public abstract int intValue()
      Method that will try to access value of this node as a Java int: but if node value cannot be expressed exactly as an int, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Integer values that fit in Java 32-bit signed int range
      • JSON Floating-point values that fit in Java 32-bit signed int range AND do not have fractional part.

      NOTE: for more lenient conversions, use asInt()

      Returns:
      Int value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to Java int

    • intValue

      public abstract int intValue(int defaultValue)
      Method similar to intValue(), but that will return specified defaultValue if this node cannot be converted to Java int.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to Java int
      Returns:
      Java int value this node represents, if possible to accurately represent; defaultValue otherwise

    • intValueOpt

      public abstract OptionalInt intValueOpt()
      Method similar to intValue(), but that will return empty OptionalInt (OptionalInt.empty()) if this node cannot be converted to Java int.
      Returns:
      Java int value this node represents, as OptionalInt, if possible to accurately represent; OptionalInt.empty() otherwise

    • asInt

      public abstract int asInt()
      Method similar to intValue() but in addition to coercing Number values (same as intValue()), will also try to coerce a couple of additional types (or cases):
      • JSON Floating-point numbers with fractions (ones without fractions are ok for intValue()) will be truncated to int (if (and only if) they fit in int range).
      • JSON Strings that represent JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0))
      • POJO nodes that contain Number values
      Returns:
      int value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to int

    • asInt

      public abstract int asInt(int defaultValue)
      Method similar to intValue(), but that will return specified defaultValue if this node cannot be converted to int.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to int
      Returns:
      int value this node represents, if possible to accurately represent; defaultValue otherwise

    • asIntOpt

      public abstract OptionalInt asIntOpt()
      Method similar to asInt(), but that will return (OptionalInt.empty()) if this node cannot be coerced to int.
      Returns:
      OptionalInt value this node represents, if possible to accurately represent; OptionalInt.empty() otherwise

    • longValue

      public abstract long longValue()
      Method that will try to access value of this node as a Java long: but if node value cannot be expressed exactly as a long, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Integer values that fit in Java 64-bit signed long range
      • JSON Floating-point values that fit in Java 64-bit signed long range AND do not have fractional part.

      NOTE: for more lenient conversions, use asLong()

      Returns:
      Long value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to Java long

    • longValue

      public abstract long longValue(long defaultValue)
      Method similar to longValue(), but that will return specified defaultValue if this node cannot be converted to long.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to long
      Returns:
      long value this node represents, if possible to accurately represent; defaultValue otherwise

    • longValueOpt

      public abstract OptionalLong longValueOpt()
      Method similar to longValue(), but that will return empty OptionalLong (OptionalLong.empty()) if this node cannot be converted to Java long.
      Returns:
      Java long value this node represents, as OptionalLong, if possible to accurately represent; OptionalLong.empty() otherwise

    • asLong

      public abstract long asLong()
      Method similar to longValue() but in addition to coercing Number values (same as longValue()), will also try to coerce a couple of additional types (or cases):
      • JSON Floating-point numbers with fractions (ones without fractions are ok for longValue()) will be truncated to long (if (and only if) they fit in long range).
      • JSON Strings that represent JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0))
      • POJO nodes that contain Number values
      Returns:
      long value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to long

    • asLong

      public abstract long asLong(long defaultValue)
      Method similar to asLong(), but that will return specified defaultValue if this node cannot be coerced to long (instead of throwing an exception).
      Parameters:
      defaultValue - Value to return if this node cannot be coerced to long
      Returns:
      long value this node represents, if possible to accurately represent; defaultValue otherwise

    • asLongOpt

      public abstract OptionalLong asLongOpt()
      Method similar to asLong(), but that will return (OptionalLong.empty()) if this node cannot be coerced to long.
      Returns:
      OptionalLong value this node represents (or can be coerced to), OptionalLong.empty() otherwise

    • bigIntegerValue

      public abstract BigInteger bigIntegerValue()
      Method that will try to access value of this node as a BigInteger, but if node value cannot be expressed exactly as a BigInteger, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Integer values
      • JSON Floating-point values that do not have fractional part.

      Returns:
      BigInteger value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to Java BigInteger

    • bigIntegerValue

      public abstract BigInteger bigIntegerValue(BigInteger defaultValue)
      Method similar to bigIntegerValue(), but that will return specified defaultValue if this node cannot be converted to Java BigInteger.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to Java BigInteger
      Returns:
      Java BigInteger value this node represents, if possible to accurately represent; defaultValue otherwise

    • bigIntegerValueOpt

      public abstract Optional<BigInteger> bigIntegerValueOpt()
      Method similar to bigIntegerValue(), but that will return empty (Optional.empty()) if this node cannot be converted to Java BigInteger.
      Returns:
      Java BigInteger value this node represents, as Optional<BigInteger>, if possible to accurately represent; Optional.empty() otherwise

    • asBigInteger

      public abstract BigInteger asBigInteger()
      Method similar to bigIntegerValue() but in addition to coercing Number values (same as bigIntegerValue()), will also try to coerce a couple of additional types (or cases):
      • JSON Floating-point numbers with fractions (ones without fractions are ok for bigIntegerValue()) will be truncated to integer value (like with BigDecimal.toBigInteger()))
      • JSON Strings that represent JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0))
      • POJO nodes that contain Number values
      Returns:
      BigInteger value this node represents, if possible to accurately convert; defaultValue otherwise

    • asBigInteger

      public abstract BigInteger asBigInteger(BigInteger defaultValue)
      Method similar to asBigInteger(), but that will return specified defaultValue if this node cannot be converted to BigInteger.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to BigInteger
      Returns:
      BigInteger value this node represents, if possible to accurately convert; defaultValue otherwise

    • asBigIntegerOpt

      public abstract Optional<BigInteger> asBigIntegerOpt()
      Method similar to bigIntegerValue(), but that will return empty (Optional.empty()) if this node cannot be converted to Java BigInteger.
      Returns:
      BigInteger value this node represents, as Optional<BigInteger>, if possible to accurately represent; Optional.empty() otherwise.

    • floatValue

      public abstract float floatValue()
      Method that will try to access value of this node as a Java float: but if node value cannot be expressed exactly as a float, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Floating-point values that fit in Java 32-bit double range
      • JSON Integer values that fit in Java 32-bit double range

      Returns:
      Float value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to Java float

    • floatValue

      public abstract float floatValue(float defaultValue)
      Method similar to floatValue(), but that will return specified defaultValue if this node cannot be converted to float.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to float
      Returns:
      float value this node represents, if possible to accurately represent; defaultValue otherwise

    • floatValueOpt

      public abstract Optional<Float> floatValueOpt()
      Method similar to floatValue(), but that will return empty Optional<Float> (Optional.empty()) if this node cannot be converted to Java float.
      Returns:
      Java float value this node represents, as Optional<Float>, if possible to accurately represent; Optional.empty() otherwise

    • asFloat

      public abstract float asFloat()
      Method similar to floatValue() but in addition to coercing Number values will also try coerce couple of additional types:
      • JSON String that represents JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0.0f)
      • POJO nodes that contain Number values

      Returns:
      float value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to float

    • asFloat

      public abstract float asFloat(float defaultValue)
      Method similar to asFloat(), but that will return defaultValue if this node cannot be coerced to float.
      Returns:
      float value this node represents, if possible to accurately represent; defaultValue otherwise

    • asFloatOpt

      public abstract Optional<Float> asFloatOpt()
      Method similar to asFloat(), but that will return (Optional.empty()) if this node cannot be coerced to float.
      Returns:
      Optional<Float> value this node represents, if possible to accurately represent; Optional.empty() otherwise

    • doubleValue

      public abstract double doubleValue()
      Method that will try to access value of this node as a double: but if node value cannot be expressed exactly as a double, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Floating-point values that fit in Java 64-bit double range
      • JSON Integer values that fit in Java 64-bit double range

      NOTE: for more lenient conversions, use asDouble()

      Returns:
      Double value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to double

    • doubleValue

      public abstract double doubleValue(double defaultValue)
      Method similar to doubleValue(), but that will return specified defaultValue if this node cannot be converted to double.
      Parameters:
      defaultValue - Value to return if this node cannot be converted to double
      Returns:
      double value this node represents, if possible to accurately represent; defaultValue otherwise

    • doubleValueOpt

      public abstract OptionalDouble doubleValueOpt()
      Method similar to doubleValue(), but that will return empty OptionalLong (OptionalDouble.empty()) if this node cannot be converted to Java double.
      Returns:
      Java double value this node represents, as OptionalDouble, if possible to accurately represent; OptionalDouble.empty() otherwise

    • asDouble

      public abstract double asDouble()
      Method similar to doubleValue() but in addition to coercing Number values will also try coerce couple of additional types:
      • JSON String that represents JSON Numbers ("stringified" numbers)
      • JSON Null (converted to 0.0d)
      • POJO nodes that contain Number values

      Returns:
      double value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to double

    • asDouble

      public abstract double asDouble(double defaultValue)
      Method similar to asDouble(), but that will return defaultValue if this node cannot be coerced to double.
      Returns:
      double value this node represents, if possible to accurately represent; defaultValue otherwise

    • asDoubleOpt

      public abstract OptionalDouble asDoubleOpt()
      Method similar to asDouble(), but that will return (OptionalDouble.empty()) if this node cannot be coerced to double.
      Returns:
      OptionalDouble value this node represents, if possible to accurately represent; OptionalDouble.empty() otherwise

    • decimalValue

      public abstract BigDecimal decimalValue()
      Method that will try to access value of this node as a Java BigDecimal: but if node value cannot be expressed exactly as a BigDecimal, a JsonNodeException will be thrown. Access works for following cases:
      • All JSON Number values

      NOTE: for more lenient conversions, use asDecimal()

      Returns:
      BigDecimal value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to Java BigDecimal

    • decimalValue

      public abstract BigDecimal decimalValue(BigDecimal defaultValue)
      Method similar to decimalValue(), but that will return defaultValue if this node cannot be coerced to Java BigDecimal.
      Returns:
      BigDecimal value this node represents, if possible to accurately represent; defaultValue otherwise

    • decimalValueOpt

      public abstract Optional<BigDecimal> decimalValueOpt()
      Method similar to decimalValue(), but that will return empty Optional (Optional.empty()) if this node cannot be coerced to BigDecimal.
      Returns:
      Java BigDecimal value this node represents, as Optional<BigDecimal>, if possible to accurately represent; Optional.empty() otherwise

    • asDecimal

      public abstract BigDecimal asDecimal()
      Method that will try to access value of this node as a BigDecimal: but if node value cannot be expressed exactly as a BigDecimal, a JsonNodeException will be thrown. Access works for following cases:
      • JSON Floating-point values (but not "NaN" or "Infinity")
      • JSON Integer values
      • JSON String that represents JSON Numbers ("stringified" numbers)
      • JSON Null (converted to BigDecimal.ZERO))
      • POJO nodes that contain Number values

      Returns:
      BigDecimal value this node represents, if possible to accurately represent
      Throws:
      JsonNodeException - if node value cannot be converted to BigDecimal

    • asDecimal

      public abstract BigDecimal asDecimal(BigDecimal defaultValue)
      Method similar to asDecimal(), but that will return defaultValue if this node cannot be coerced to Java BigDecimal.
      Returns:
      BigDecimal value this node represents, if possible to accurately represent; defaultValue otherwise

    • asDecimalOpt

      public abstract Optional<BigDecimal> asDecimalOpt()
      Method similar to asDecimal(), but that will return empty Optional (Optional.empty()) if this node cannot be coerced to BigDecimal.
      Returns:
      Java BigDecimal value this node represents, as Optional<BigDecimal>, if possible to accurately represent; Optional.empty() otherwise

    • require

      public <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. If not missing node, this is returned to allow chaining; otherwise exception is thrown.
      Returns:
      this node to allow chaining
      Throws:
      IllegalArgumentException - if this node is "missing node"

    • requireNonNull

      public <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). If non-null non-missing node, this is returned to allow chaining; otherwise exception is thrown.
      Returns:
      this node to allow chaining
      Throws:
      IllegalArgumentException - if this node is either "missing node" or "null node"

    • required

      public abstract JsonNode required(String propertyName)
      Method is functionally equivalent to path(propertyName).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 propertyName (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

    • required

      public abstract 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). 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

    • requiredAt

      public 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). 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

    • requiredAt

      public 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). 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

    • has

      public boolean has(String propertyName)
      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(propertyName) != 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:
      propertyName - 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 propertyName)
      Method that is similar to has(String), but that will return false for explicitly added nulls.

      This method is functionally equivalent to: 

         node.get(propertyName) != null && !node.get(propertyName).isNull()

    • 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()

    • iterator

      public final Iterator<JsonNode> iterator()
      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>

    • spliterator

      public final Spliterator<JsonNode> spliterator()
      Specified by:
      spliterator in interface Iterable<JsonNode>

    • values

      public Collection<JsonNode> values()
      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.

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

    • valueStream

      public Stream<JsonNode> valueStream()
      Returns a stream of all value nodes of this Node, iff this node is an ArrayNode or ObjectNode. In case of Object node, property names (keys) are not included, only values. For other types of nodes, returns empty stream.

    • propertyStream

      public Stream<Map.Entry<String,JsonNode>> propertyStream()
      Returns a stream of all properties (key, value pairs) of this Node, iff this node is an an ObjectNode. For other types of nodes, returns empty stream.

    • forEachEntry

      public void forEachEntry(BiConsumer<? super String,? super JsonNode> action)
      If this node is an ObjectNode, performs the given action for each property (key, value pair) until all entries have been processed or the action throws an exception. Exceptions thrown by the action are relayed to the caller. For other node types, no action is performed.

      Actions are performed in the order of properties, same as order returned by method properties(). This is generally the document order of properties in JSON object.

      Parameters:
      action - Action to perform for each entry

    • findValue

      public abstract JsonNode findValue(String propertyName)
      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 values())

      Parameters:
      propertyName - 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 propertyName)
      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:
      propertyName - Name of field to look for

    • findValuesAsString

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

    • findPath

      public abstract JsonNode findPath(String propertyName)
      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:
      propertyName - 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 propertyName)
      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:
      propertyName - 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 propertyName)
      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:
      propertyName - 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 propertyName, List<JsonNode> foundSoFar)

    • findValuesAsString

      public abstract List<String> findValuesAsString(String propertyName, List<String> foundSoFar)

    • findParents

      public abstract List<JsonNode> findParents(String propertyName, 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

    • withObject

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

    • 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

    • 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:
      JsonNodeException - if a conversion would be needed for given JsonPointer, document, but was not allowed for the type encountered

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

    • withArray

      public ArrayNode withArray(String exprOrProperty)
      Short-cut equivalent to: 
        withArray(JsonPointer.compile(expr), overwriteMode, preferIndex);

    • withArray

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

    • 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

    • 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:
      JsonNodeException - if a conversion would be needed for given JsonPointer, document, but was not allowed for the type encountered

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

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

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

    • 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

    • _this

      protected <T extends JsonNode> T _this()

    • _reportRequiredViolation

      protected <T> T _reportRequiredViolation(String msgTemplate, Object... args)
      Helper method that throws DatabindException as a result of violating "required-constraint" for this node (for required(java.lang.String) or related methods).

    • _reportUnsupportedOperation

      protected <T> T _reportUnsupportedOperation(String msgTemplate, Object... args)