public abstract class JsonNode extends Object implements TreeNode, Iterable<JsonNode>, JsonSerializable
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)
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() |
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> |
deepCopy()
Method that can be called to get a node that is guaranteed
not to allow changing of this node through mutators on
this node or any of its children.
|
double |
doubleValue()
Returns 64-bit floating point (double) value for this node, if and only if
this node is numeric (
isNumber() returns true). |
Iterator<JsonNode> |
elements()
Method for accessing all value nodes of this Node, iff
this node is a JSON Array or Object node.
|
abstract boolean |
equals(Object o)
Equality for node objects is defined as full (deep) value
equality.
|
Iterator<String> |
fieldNames()
Method for accessing names of all fields for this node, iff
this node is an Object node.
|
Iterator<Map.Entry<String,JsonNode>> |
fields() |
abstract JsonNode |
findParent(String fieldName)
Method for finding a JSON Object that contains specified field,
within this node or its descendants.
|
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()
Method that returns true if this node is an Array node, false
otherwise.
|
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 |
isFloat() |
boolean |
isFloatingPointNumber() |
boolean |
isInt()
Method that can be used to check whether contained value
is a number represented as Java
int . |
boolean |
isIntegralNumber() |
boolean |
isLong()
Method that can be used to check whether contained value
is a number represented as Java
long . |
boolean |
isMissingNode()
Method that returns true for "virtual" nodes which represent
missing entries constructed by path accessor methods when
there is no actual node matching given criteria.
|
boolean |
isNull()
Method that can be used to check if this node was created from
JSON literal null value.
|
boolean |
isNumber() |
boolean |
isObject()
Method that returns true if this node is an Object node, false
otherwise.
|
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()
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()
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()
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.
|
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. |
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 int size()
TreeNode
public final boolean isValueNode()
TreeNode
Note: one and only one of methods TreeNode.isValueNode()
,
TreeNode.isContainerNode()
and TreeNode.isMissingNode()
ever
returns true for any given node.
isValueNode
in interface TreeNode
public final boolean isContainerNode()
TreeNode
Note: one and only one of methods TreeNode.isValueNode()
,
TreeNode.isContainerNode()
and TreeNode.isMissingNode()
ever
returns true for any given node.
isContainerNode
in interface TreeNode
public final boolean isMissingNode()
TreeNode
Note: one and only one of methods TreeNode.isValueNode()
,
TreeNode.isContainerNode()
and TreeNode.isMissingNode()
ever
returns true for any given node.
isMissingNode
in interface TreeNode
public final boolean isArray()
TreeNode
TreeNode.isContainerNode()
must also return true.public final boolean isObject()
TreeNode
TreeNode.isContainerNode()
must also return true.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()
TreeNode
TreeNode.size()
.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
canConvertToInt()
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()
public BigInteger bigIntegerValue()
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 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.
public int asInt(int defaultValue)
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.
public long asLong()
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.
public long asLong(long defaultValue)
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.
public double asDouble()
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.
public double asDouble(double defaultValue)
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.
public boolean asBoolean()
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.
public boolean asBoolean(boolean defaultValue)
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.
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 abstract String toString()
Note: marked as abstract to ensure all implementation classes define it properly.
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 © 2016 JBoss by Red Hat. All rights reserved.