public abstract class JsonNode extends JsonSerializable.Base implements TreeNode, Iterable<JsonNode>
As a general design rule, most accessors ("getters") are included
in this base class, to allow for traversing structure without
type casts. Most mutators, however, need to be accessed through
specific sub-classes (such as ObjectNode
and ArrayNode
).
This seems sensible because proper type
information is generally available when building or modifying
trees, but less often when reading a tree (newly built from
parsed JSON content).
Actual concrete sub-classes can be found from package
com.fasterxml.jackson.databind.node
.
Note that it is possible to "read" from nodes, using
method TreeNode.traverse(ObjectCodec)
, which will result in
a JsonParser
being constructed. This can be used for (relatively)
efficient conversations between different representations; and it is what
core databind uses for methods like ObjectMapper.treeToValue(TreeNode, Class)
and ObjectMapper.treeAsTokens(TreeNode)
JsonSerializable.Base
Modifier | Constructor and Description |
---|---|
protected |
JsonNode() |
Modifier and Type | Method and Description |
---|---|
protected abstract JsonNode |
_at(JsonPointer ptr) |
boolean |
asBoolean()
Method that will try to convert value of this node to a Java boolean.
|
boolean |
asBoolean(boolean defaultValue)
Method that will try to convert value of this node to a Java boolean.
|
double |
asDouble()
Method that will try to convert value of this node to a Java double.
|
double |
asDouble(double defaultValue)
Method that will try to convert value of this node to a Java double.
|
int |
asInt()
Method that will try to convert value of this node to a Java int.
|
int |
asInt(int defaultValue)
Method that will try to convert value of this node to a Java int.
|
long |
asLong()
Method that will try to convert value of this node to a Java long.
|
long |
asLong(long defaultValue)
Method that will try to convert value of this node to a Java long.
|
abstract String |
asText()
Method that will return a valid String representation of
the container value, if the node is a value node
(method
isValueNode() returns true),
otherwise empty String. |
String |
asText(String defaultValue)
Method similar to
asText() , except that it will return
defaultValue in cases where null value would be returned;
either for missing nodes (trying to access missing property, or element
at invalid item for array) or explicit nulls. |
JsonNode |
at(JsonPointer ptr)
Method for locating node specified by given JSON pointer instances.
|
JsonNode |
at(String jsonPtrExpr)
Convenience method that is functionally equivalent to:
|
BigInteger |
bigIntegerValue()
Returns integer value for this node (as
BigDecimal ), if and only if
this node is numeric (isNumber() returns true). |
byte[] |
binaryValue()
Method to use for accessing binary content of binary nodes (nodes
for which
isBinary() returns true); or for Text Nodes
(ones for which textValue() returns non-null value),
to read decoded base64 data. |
boolean |
booleanValue()
Method to use for accessing JSON boolean values (value
literals 'true' and 'false').
|
boolean |
canConvertToInt()
Method that can be used to check whether this node is a numeric
node (
isNumber() would return true) AND its value fits
within Java's 32-bit signed integer type, int . |
boolean |
canConvertToLong()
Method that can be used to check whether this node is a numeric
node (
isNumber() would return true) AND its value fits
within Java's 64-bit signed integer type, long . |
BigDecimal |
decimalValue()
Returns floating point value for this node (as
BigDecimal ), if and only if
this node is numeric (isNumber() returns true). |
abstract <T extends JsonNode> |
deepCopy()
Method that can be called to get a node that is guaranteed
not to allow changing of this node through mutators on
this node or any of its children.
|
double |
doubleValue()
Returns 64-bit floating point (double) value for this node, if and only if
this node is numeric (
isNumber() returns true). |
Iterator<JsonNode> |
elements()
Method for accessing all value nodes of this Node, iff
this node is a JSON Array or Object node.
|
boolean |
equals(Comparator<JsonNode> comparator,
JsonNode other)
Entry method for invoking customizable comparison, using passed-in
Comparator object. |
abstract boolean |
equals(Object o)
Equality for node objects is defined as full (deep) value
equality.
|
Iterator<String> |
fieldNames() |
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) |
float |
floatValue()
Returns 32-bit floating value for this node, if and only if
this node is numeric (
isNumber() returns true). |
abstract JsonNode |
get(int index)
Method for accessing value of the specified element of
an array node.
|
JsonNode |
get(String fieldName)
Method for accessing value of the specified field of
an object node.
|
abstract JsonNodeType |
getNodeType()
Return the type of this node
|
boolean |
has(int index)
Method that allows checking whether this node is JSON Array node
and contains a value for specified index
If this is the case
(including case of specified indexing having null as value), returns true;
otherwise returns false.
|
boolean |
has(String fieldName)
Method that allows checking whether this node is JSON Object node
and contains value for specified property.
|
boolean |
hasNonNull(int index)
Method that is similar to
has(int) , but that will
return false for explicitly added nulls. |
boolean |
hasNonNull(String fieldName)
Method that is similar to
has(String) , but that will
return false for explicitly added nulls. |
int |
intValue()
Returns integer value for this node, if and only if
this node is numeric (
isNumber() returns true). |
boolean |
isArray() |
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() |
boolean |
isDouble() |
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() |
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 |
isShort()
Method that can be used to check whether contained value
is a number represented as Java
short . |
boolean |
isTextual()
Method that checks whether this node represents basic JSON String
value.
|
boolean |
isValueNode() |
Iterator<JsonNode> |
iterator()
Same as calling
elements() ; implemented so that
convenience "for-each" loop can be used for looping over elements
of JSON Array constructs. |
long |
longValue()
Returns 64-bit long value for this node, if and only if
this node is numeric (
isNumber() returns true). |
Number |
numberValue()
Returns numeric value for this node, if and only if
this node is numeric (
isNumber() returns true); otherwise
returns null |
abstract JsonNode |
path(int index)
This method is similar to
get(int) , except
that instead of returning null if no such element exists (due
to index being out of range, or this node not being an array),
a "missing node" (node that returns true for
isMissingNode() ) will be returned. |
abstract JsonNode |
path(String fieldName)
This method is similar to
get(String) , except
that instead of returning null if no such value exists (due
to this node not being an object, or object not having value
for the specified field),
a "missing node" (node that returns true for
isMissingNode() ) will be returned. |
short |
shortValue()
Returns 16-bit short value for this node, if and only if
this node is numeric (
isNumber() returns true). |
int |
size() |
String |
textValue()
Method to use for accessing String values.
|
abstract String |
toString()
Method that will produce developer-readable representation of the
node; which may or may not be as valid JSON.
|
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. |
isEmpty
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
asToken, numberType, traverse, traverse
forEach, spliterator
serialize, serializeWithType
public abstract <T extends JsonNode> T deepCopy()
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.
public final boolean isValueNode()
isValueNode
in interface TreeNode
public final boolean isContainerNode()
isContainerNode
in interface TreeNode
public boolean isMissingNode()
isMissingNode
in interface TreeNode
public abstract JsonNode get(int index)
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.
public JsonNode get(String fieldName)
NOTE: if the property value has been explicitly set as null
(which is different from removal!),
a NullNode
will be returned,
not null.
public abstract JsonNode path(String fieldName)
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.public abstract JsonNode path(int index)
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.public Iterator<String> fieldNames()
fieldNames
in interface TreeNode
public final JsonNode at(JsonPointer ptr)
isMissingNode()
returns true.at
in interface TreeNode
isMissingNode()
returns true.public final JsonNode at(String jsonPtrExpr)
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.
at
in interface TreeNode
jsonPtrExpr
- Expression to compile as a JsonPointer
instanceTreeNode.isMissingNode()
returns true.protected abstract JsonNode _at(JsonPointer ptr)
public abstract JsonNodeType getNodeType()
JsonNodeType
enum valuepublic final boolean isPojo()
POJONode
.public final boolean isNumber()
public boolean isIntegralNumber()
public boolean isFloatingPointNumber()
public boolean isShort()
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.public boolean isInt()
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.public boolean isLong()
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.long
public boolean isFloat()
public boolean isDouble()
public boolean isBigDecimal()
public boolean isBigInteger()
public final boolean isTextual()
public final boolean isBoolean()
public final boolean isNull()
public final boolean isBinary()
isTextual()
will
return false if this method returns true.public boolean canConvertToInt()
isNumber()
would return true) AND its value fits
within Java's 32-bit signed integer type, int
.
Note that floating-point numbers are convertible if the integral
part fits without overflow (as per standard Java coercion rules)
NOTE: this method does not consider possible value type conversion
from JSON String into Number; so even if this method returns false,
it is possible that asInt()
could still succeed
if node is a JSON String representing integral number, or boolean.
public boolean canConvertToLong()
isNumber()
would return true) AND its value fits
within Java's 64-bit signed integer type, long
.
Note that floating-point numbers are convertible if the integral
part fits without overflow (as per standard Java coercion rules)
NOTE: this method does not consider possible value type conversion
from JSON String into Number; so even if this method returns false,
it is possible that asLong()
could still succeed
if node is a JSON String representing integral number, or boolean.
public String textValue()
isTextual()
returns
false) null will be returned.
For String values, null is never returned (but empty Strings may be)public byte[] binaryValue() throws IOException
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.IOException
public boolean booleanValue()
public Number numberValue()
isNumber()
returns true); otherwise
returns nullpublic short shortValue()
isNumber()
returns true). For other
types returns 0.
For floating-point numbers, value is truncated using default
Java coercion, similar to how cast from double to short operates.public int intValue()
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.public long longValue()
isNumber()
returns true). For other
types returns 0.
For floating-point numbers, value is truncated using default
Java coercion, similar to how cast from double to long operates.public float floatValue()
isNumber()
returns true). For other
types returns 0.0.
For integer values, conversion is done using coercion; this means
that an overflow is possible for `long` valuespublic double doubleValue()
isNumber()
returns true). For other
types returns 0.0.
For integer values, conversion is done using coercion; this may result
in overflows with BigInteger
values.public BigDecimal decimalValue()
BigDecimal
), if and only if
this node is numeric (isNumber()
returns true). For other
types returns BigDecimal.ZERO
.BigDecimal
value this node contains, if numeric node; BigDecimal.ZERO
for non-number nodes.public BigInteger bigIntegerValue()
BigDecimal
), if and only if
this node is numeric (isNumber()
returns true). For other
types returns BigInteger.ZERO
.BigInteger
value this node contains, if numeric node; BigInteger.ZERO
for non-number nodes.public abstract String asText()
isValueNode()
returns true),
otherwise empty String.public String asText(String defaultValue)
asText()
, except that it will return
defaultValue
in cases where null value would be returned;
either for missing nodes (trying to access missing property, or element
at invalid item for array) or explicit nulls.public int asInt()
If representation cannot be converted to an int (including structured types like Objects and Arrays), default value of 0 will be returned; no exceptions are thrown.
public int asInt(int defaultValue)
If representation cannot be converted to an int (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.
public long asLong()
If representation cannot be converted to an long (including structured types like Objects and Arrays), default value of 0 will be returned; no exceptions are thrown.
public long asLong(long defaultValue)
If representation cannot be converted to an long (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.
public double asDouble()
If representation cannot be converted to an int (including structured types like Objects and Arrays), default value of 0.0 will be returned; no exceptions are thrown.
public double asDouble(double defaultValue)
If representation cannot be converted to an int (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.
public boolean asBoolean()
If representation cannot be converted to a boolean value (including structured types like Objects and Arrays), default value of false will be returned; no exceptions are thrown.
public boolean asBoolean(boolean defaultValue)
If representation cannot be converted to a boolean value (including structured types like Objects and Arrays), specified defaultValue will be returned; no exceptions are thrown.
public boolean has(String fieldName)
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.
fieldName
- Name of element to checkpublic boolean has(int index)
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.
index
- Index to checkpublic boolean hasNonNull(String fieldName)
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()
public boolean hasNonNull(int index)
has(int)
, but that will
return false
for explicitly added nulls.
This method is equivalent to:
node.get(index) != null && !node.get(index).isNull()
public final Iterator<JsonNode> iterator()
elements()
; implemented so that
convenience "for-each" loop can be used for looping over elements
of JSON Array constructs.public Iterator<JsonNode> elements()
public Iterator<Map.Entry<String,JsonNode>> fields()
public abstract JsonNode findValue(String fieldName)
fieldName
- Name of field to look forpublic final List<JsonNode> findValues(String fieldName)
fieldName
- Name of field to look forpublic final List<String> findValuesAsText(String fieldName)
findValues(java.lang.String)
, but will additionally convert
values into Strings, calling asText()
.public abstract JsonNode findPath(String fieldName)
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.fieldName
- Name of field to look forpublic abstract JsonNode findParent(String fieldName)
fieldName
- Name of field to look forpublic final List<JsonNode> findParents(String fieldName)
fieldName
- Name of field to look forpublic abstract List<String> findValuesAsText(String fieldName, List<String> foundSoFar)
public JsonNode with(String propertyName)
UnsupportedOperationException
is thrownpublic JsonNode withArray(String propertyName)
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 thrownpublic boolean equals(Comparator<JsonNode> comparator, JsonNode other)
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.
comparator
- Object called to compare two scalar JsonNode
instances, and return either 0 (are equals) or non-zero (not equal)public abstract String toString()
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.
public abstract boolean equals(Object o)
Note: marked as abstract to ensure all implementation
classes define it properly and not rely on definition
from Object
.
Copyright © 2008–2020 FasterXML. All rights reserved.