com.fasterxml.jackson.databind
Class JsonNode

java.lang.Object
  com.fasterxml.jackson.databind.JsonNode

All Implemented Interfaces:

TreeNode, Iterable<JsonNode>

Direct Known Subclasses:

BaseJsonNode

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

Field Summary

protected static List<JsonNode>	NO_NODES
protected static List<String>	NO_STRINGS

Constructor Summary

protected

JsonNode()

Method Summary

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.
abstract JsonToken	asToken() Method that can be used for efficient type detection when using stream abstraction for traversing nodes.
BigInteger	bigIntegerValue()
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	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()
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()
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.
Iterator<String>	fieldNames() Method for accessing names of all fields for this Node, iff this node is a JSON 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.
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 a JSON Object field with specified name in this node or its child nodes, and returning value it has.
List<JsonNode>	findValues(String fieldName) Method for finding JSON Object fields with specified name, and returning found ones as a List.
abstract List<JsonNode>	findValues(String fieldName, List<JsonNode> foundSoFar)
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)
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.
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()
boolean	isBigDecimal()
boolean	isBigInteger()
boolean	isBinary() Method that can be used to check if this node represents binary data (Base64 encoded).
boolean	isBoolean() Method that can be used to check if this node was created from JSON boolean value (literals "true" and "false").
boolean	isContainerNode() Method that returns true for container nodes: Arrays and Objects.
boolean	isDouble()
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.
boolean	isNull() Method that can be used to check if this node was created from JSON literal null value.
boolean	isNumber()
boolean	isObject()
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	isTextual()
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.
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()
abstract JsonParser.NumberType	numberType() If this node is a numeric type (as per isNumber()), returns native type that node uses to store the numeric value; otherwise returns null.
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.
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.
abstract String	toString() Note: marked as abstract to ensure all implementation classes define it properly.
abstract JsonParser	traverse() Method for constructing a JsonParser instance for iterating over contents of the tree that this node is root of.
JsonNode	with(String propertyName) Method that can be called on Object nodes, to access a property that has Object value; or if no such property exists, to create, add and return such Object node.
JsonNode	withArray(String propertyName) Method that can be called on Object nodes, to access a property that has Array value; or if no such property exists, to create, add and return such Array node.

Methods inherited from class java.lang.Object

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

Field Detail

NO_NODES

protected static final List<JsonNode> NO_NODES

NO_STRINGS

protected static final List<String> NO_STRINGS

Constructor Detail

JsonNode

protected JsonNode()

Method Detail

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

isValueNode

public boolean isValueNode()

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

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

isContainerNode

public boolean isContainerNode()

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

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

isMissingNode

public boolean isMissingNode()

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

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

isArray

public boolean isArray()

Returns:

True if this node represents JSON Array

isObject

public boolean isObject()

Returns:

True if this node represents JSON Object

isPojo

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

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 canConvertToInt() instead.

Returns:

True if the value contained by this node is stored as Java long

isDouble

public boolean isDouble()

isBigDecimal

public boolean isBigDecimal()

isBigInteger

public boolean isBigInteger()

isTextual

public boolean isTextual()

isBoolean

public boolean isBoolean()

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

isNull

public boolean isNull()

Method that can be used to check if this node was created from JSON literal null value.

isBinary

public 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

asToken

public abstract JsonToken asToken()

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

Specified by:

asToken in interface TreeNode

numberType

public abstract JsonParser.NumberType numberType()

If this node is a numeric type (as per isNumber()), returns native type that node uses to store the numeric value; otherwise returns null.

Specified by:

numberType in interface TreeNode

Returns:

Type of number contained, if any; or null if node does not contain numeric value.

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)

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)

Since:

2.0

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

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

doubleValue

public double doubleValue()

decimalValue

public BigDecimal decimalValue()

bigIntegerValue

public BigInteger bigIntegerValue()

get

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

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.

Returns:

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

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.

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 can not 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 can not 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 can not be converted to an 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 can not be converted to an 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 can not 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 can not 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 can not 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 can not be converted to a boolean value (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.

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

findValue

public abstract JsonNode findValue(String fieldName)

Method for finding a 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.

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, and returning found ones as a List. Note that sub-tree search ends if a 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)

size

public int size()

Method that returns number of child nodes this node contains: for Array nodes, number of child elements, for Object nodes, number of fields, and for all other nodes 0.

Returns:

For non-container nodes returns 0; for arrays number of contained elements, and for objects number of fields.

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.

fieldNames

public Iterator<String> fieldNames()

Method for accessing names of all fields for this Node, iff this node is a JSON Object node.

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

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.

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.

with

public JsonNode with(String propertyName)

Method that can be called on Object nodes, to access a property that has Object value; or if no such property exists, to create, add and return such Object node. If the node method is called on is not Object node, or if property exists and has value that is not Object node, UnsupportedOperationException is thrown

withArray

public JsonNode withArray(String propertyName)

Method that can be called on Object nodes, to access a property that has Array value; or if no such property exists, to create, add and return such Array node. If the node method is called on is not Object node, or if property exists and has value that is not Array node, UnsupportedOperationException is thrown

traverse

public abstract JsonParser traverse()

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

Specified by:

traverse in interface TreeNode

toString

public abstract String toString()

Note: marked as abstract to ensure all implementation classes define it properly.

Overrides:

toString in class Object

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