Class JsonNode
- Direct Known Subclasses:
BaseJsonNode
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 org.codehaus.jackson.node.ObjectNode
and org.codehaus.jackson.node.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
org.codehaus.jackson.node
, which is in 'mapper' jar
(whereas this class is in 'core' jar, since it is declared as
nominal type for operations in ObjectCodec
)
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
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 valid String representation of the container value, if the node is a value node (methodisValueNode()
returns true), otherwise empty String.abstract JsonToken
asToken()
Method that can be used for efficient type detection when using stream abstraction for traversing nodes.abstract boolean
Equality for node objects is defined as full (deep) value equality.abstract JsonNode
findParent
(String fieldName) Method for finding a JSON Object that contains specified field, within this node or its descendants.findParents
(String fieldName) Method for finding a JSON Object that contains specified field, within this node or its descendants.findParents
(String fieldName, List<JsonNode> foundSoFar) abstract JsonNode
Method similar tofindValue(java.lang.String)
, but that will return a "missing node" instead of null if no field is found.abstract JsonNode
Method for finding a JSON Object field with specified name in this node or its child nodes, and returning value it has.findValues
(String fieldName) Method for finding JSON Object fields with specified name, and returning found ones as a List.findValues
(String fieldName, List<JsonNode> foundSoFar) findValuesAsText
(String fieldName) Similar tofindValues(java.lang.String)
, but will additionally convert values into Strings, callinggetValueAsText()
.findValuesAsText
(String fieldName, List<String> foundSoFar) get
(int index) Method for accessing value of the specified element of an array node.Method for accessing value of the specified field of an object node.byte[]
Method to use for accessing binary content of binary nodes (nodes for whichisBinary()
returns true); or for Text Nodes (ones for whichgetTextValue()
returns non-null value), to read decoded base64 data.boolean
Method to use for accessing JSON boolean values (value literals 'true' and 'false').double
Method for accessing all value nodes of this Node, iff this node is a JSON Array or Object node.Method for accessing names of all fields for this Node, iff this node is a JSON Object node.int
Returns integer value for this node, if and only if this node is numeric (isNumber()
returns true).long
abstract JsonParser.NumberType
If this node is a numeric type (as perisNumber()
), returns native type that node uses to store the numeric value.Returns numeric value for this node, if and only if this node is numeric (isNumber()
returns true); otherwise returns nullfinal JsonNode
getPath
(int index) Deprecated.final JsonNode
Deprecated.Usepath(String)
insteadMethod to use for accessing String values.boolean
Deprecated.Since 1.9, useasBoolean()
insteadboolean
getValueAsBoolean
(boolean defaultValue) Deprecated.Since 1.9, useasBoolean()
insteaddouble
Deprecated.Since 1.9, useasDouble()
insteaddouble
getValueAsDouble
(double defaultValue) Deprecated.Since 1.9, useasDouble()
insteadint
Deprecated.Since 1.9, useasInt()
insteadint
getValueAsInt
(int defaultValue) Deprecated.Since 1.9, useasInt()
insteadlong
Deprecated.Since 1.9, useasLong()
insteadlong
getValueAsLong
(long defaultValue) Deprecated.Since 1.9, useasLong()
insteadDeprecated.Since 1.9, useasText()
insteadboolean
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
Method that allows checking whether this node is JSON Object node and contains value for specified property.boolean
isArray()
boolean
boolean
boolean
isBinary()
Method that can be used to check if this node represents binary data (Base64 encoded).boolean
Method that can be used to check if this node was created from Json boolean value (literals "true" and "false").boolean
Method that returns true for container nodes: Arrays and Objects.boolean
isDouble()
boolean
boolean
isInt()
boolean
boolean
isLong()
boolean
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 liternal 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
boolean
Method that returns true for all value nodes: ones that are not containers, and that do not represent "missing" nodes in the path.iterator()
Same as callinggetElements()
; implemented so that convenience "for-each" loop can be used for looping over elements of JSON Array constructs.abstract JsonNode
path
(int index) This method is similar toget(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 forisMissingNode()
) will be returned.abstract JsonNode
This method is similar toget(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 forisMissingNode()
) 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.abstract String
toString()
Note: marked as abstract to ensure all implementation classes define it properly.abstract JsonParser
traverse()
Method for constructing aJsonParser
instance for iterating over contents of the tree that this node is root of.Method that can be called on object nodes, to access a property that has object value; or if no such property exists, to create and return such object node.Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
Field Details
-
NO_NODES
-
NO_STRINGS
-
-
Constructor Details
-
JsonNode
protected JsonNode()
-
-
Method Details
-
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()
andisMissingNode()
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()
andisMissingNode()
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()
andisMissingNode()
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 ofPOJONode
.- 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()- Returns:
- True if this node represents an integral numeric Json value that withs in Java int value space
-
isLong
public boolean isLong()- Returns:
- True if this node represents an integral
numeric Json value that fits in Java long value space
(but not int value space, i.e.
isInt()
returns false)
-
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 liternal 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
Method that can be used for efficient type detection when using stream abstraction for traversing nodes. Will return the firstJsonToken
that equivalent stream event would produce (for most nodes there is just one token but for structured/container types multiple)- Since:
- 1.3
-
getNumberType
If this node is a numeric type (as perisNumber()
), returns native type that node uses to store the numeric value. -
getTextValue
Method to use for accessing String values. Does NOT do any conversions for non-String value nodes; for non-String values (ones for whichisTextual()
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)
-
getBinaryValue
Method to use for accessing binary content of binary nodes (nodes for whichisBinary()
returns true); or for Text Nodes (ones for whichgetTextValue()
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
-
getBooleanValue
public boolean getBooleanValue()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)
-
getNumberValue
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).
-
getIntValue
public int getIntValue()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.
-
getLongValue
public long getLongValue() -
getDoubleValue
public double getDoubleValue() -
getDecimalValue
-
getBigIntegerValue
-
get
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.- Returns:
- Node that represent value of the specified element, if this node is an array and has specified element. Null otherwise.
-
get
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.- 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
Method that will return valid String representation of the container value, if the node is a value node (methodisValueNode()
returns true), otherwise empty String.- Since:
- 1.9 (replaces
getValueAsText
)
-
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.
- Since:
- 1.9 (replaces
getValueAsInt
)
-
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.
- Since:
- 1.9 (replaces
getValueAsInt
)
-
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.
- Since:
- 1.9 (replaces
getValueAsLong
)
-
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.
- Since:
- 1.9 (replaces
getValueAsLong
)
-
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.
- Since:
- 1.9 (replaces
getValueAsDouble
)
-
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.
- Since:
- 1.9 (replaces
getValueAsLong
)
-
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.
- Since:
- 1.9 (replaces
getValueAsBoolean
)
-
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.
- Since:
- 1.9 (replaces
getValueAsBoolean
)
-
getValueAsText
Deprecated.Since 1.9, useasText()
insteadMethod that will return valid String representation of the container value, if the node is a value node (methodisValueNode()
returns true), otherwise null.Note: to serialize nodes of any type, you should call
toString()
instead. -
getValueAsInt
Deprecated.Since 1.9, useasInt()
insteadMethod 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.
- Since:
- 1.6
-
getValueAsInt
Deprecated.Since 1.9, useasInt()
insteadMethod 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.
- Since:
- 1.6
-
getValueAsLong
Deprecated.Since 1.9, useasLong()
insteadMethod 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.
- Since:
- 1.6
-
getValueAsLong
Deprecated.Since 1.9, useasLong()
insteadMethod 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.
- Since:
- 1.6
-
getValueAsDouble
Deprecated.Since 1.9, useasDouble()
insteadMethod 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.
- Since:
- 1.6
-
getValueAsDouble
Deprecated.Since 1.9, useasDouble()
insteadMethod 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.
- Since:
- 1.6
-
getValueAsBoolean
Deprecated.Since 1.9, useasBoolean()
insteadMethod 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.
- Since:
- 1.7
-
getValueAsBoolean
Deprecated.Since 1.9, useasBoolean()
insteadMethod 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.
- Since:
- 1.7
-
has
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)- 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)
- Since:
- 1.6
-
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
- 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)
- Since:
- 1.6
-
findValue
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
- Since:
- 1.6
-
findValues
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- Since:
- 1.6
-
findValuesAsText
Similar tofindValues(java.lang.String)
, but will additionally convert values into Strings, callinggetValueAsText()
.- Since:
- 1.6
-
findPath
Method similar tofindValue(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 whichisMissingNode()
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)
- Since:
- 1.6
-
findParent
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
- Since:
- 1.6
-
findParents
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
- Since:
- 1.6
-
findValues
-
findValuesAsText
-
findParents
-
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
Same as callinggetElements()
; implemented so that convenience "for-each" loop can be used for looping over elements of JSON Array constructs. -
getElements
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. -
getFieldNames
Method for accessing names of all fields for this Node, iff this node is a JSON Object node. -
getFields
- Returns:
- Iterator that can be used to traverse all key/value pairs for object nodes; empty iterator (no contents) for other types
- Since:
- 1.8 (although existed in ObjectNode since 1.0 or so)
-
path
This method is similar toget(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 forisMissingNode()
) will be returned. This allows for convenient and safe chained access via path calls. -
getPath
Deprecated.Usepath(String)
insteadAlias ofpath(String)
. -
path
This method is similar toget(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 forisMissingNode()
) will be returned. This allows for convenient and safe chained access via path calls. -
getPath
Deprecated.Usepath(int)
insteadAlias ofpath(int)
. -
with
Method that can be called on object nodes, to access a property that has object value; or if no such property exists, to create and return such object node. If node method is called on is not Object node, or if property exists and has value that is not object node,UnsupportedOperationException
is thrown- Since:
- 1.8
-
traverse
Method for constructing aJsonParser
instance for iterating over contents of the tree that this node is root of. Functionally equivalent to first serializing tree usingObjectCodec
and then re-parsing but more efficient. -
toString
Note: marked as abstract to ensure all implementation classes define it properly.
-
equals
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
.
-
path(int)
instead