Package com.fasterxml.jackson.databind.node

Class ObjectNode

    • Method Detail

      • deepCopy

        public ObjectNode deepCopy()
        Description copied from class: JsonNode
        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.

        Specified by:
        deepCopy in class JsonNode
        Returns:
        Node that is either a copy of this node (and all non-leaf children); or, for immutable leaf nodes, node itself.

      • isObject

        public final boolean isObject()
        Description copied from interface: TreeNode
        Method that returns true if this node is an Object node, false otherwise. Note that if true is returned, TreeNode.isContainerNode() must also return true.
        Specified by:
        isObject in interface TreeNode
        Overrides:
        isObject in class JsonNode
        Returns:
        True for Object nodes, false for everything else

      • asToken

        public JsonToken asToken()
        Description copied from class: BaseJsonNode
        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
        Specified by:
        asToken in class ContainerNode<ObjectNode>
        Returns:
        JsonToken that is most closely associated with the node type

      • size

        public int size()
        Description copied from interface: TreeNode
        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.
        Specified by:
        size in interface TreeNode
        Specified by:
        size in class ContainerNode<ObjectNode>
        Returns:
        For non-container nodes returns 0; for arrays number of contained elements, and for objects number of fields.

      • isEmpty

        public boolean isEmpty()
        Description copied from class: JsonNode
        Convenience method that is functionally same as: 
            size() == 0
        for all node types.
        Overrides:
        isEmpty in class JsonNode

      • elements

        public java.util.Iterator<JsonNode> elements()
        Description copied from class: JsonNode
        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.
        Overrides:
        elements in class JsonNode

      • get

        public JsonNode get​(int index)
        Description copied from class: JsonNode
        Method for accessing value of the specified element of an array node. For other nodes, null is always returned.

        For array nodes, index specifies exact location within array and allows for efficient iteration over child elements (underlying storage is guaranteed to be efficiently indexable, i.e. has random-access to elements). If index is less than 0, or equal-or-greater than node.size(), null is returned; no exception is thrown for any index.

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

        Specified by:
        get in interface TreeNode
        Specified by:
        get in class ContainerNode<ObjectNode>
        Parameters:
        index - Index of the Array node element to access
        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​(java.lang.String propertyName)
        Description copied from class: JsonNode
        Method for accessing value of the specified field of an object node. If this node is not an object (or it does not have a value for specified field name), or if there is no field with such name, null is returned.

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

        Specified by:
        get in interface TreeNode
        Specified by:
        get in class ContainerNode<ObjectNode>
        Parameters:
        propertyName - Name of the field (of Object node) to access
        Returns:
        Node that represent value of the specified field, if this node is an object and has value for the specified field. Null otherwise.

      • fieldNames

        public java.util.Iterator<java.lang.String> fieldNames()
        Description copied from interface: TreeNode
        Method for accessing names of all fields for this node, iff this node is an Object node. Number of field names accessible will be TreeNode.size().
        Specified by:
        fieldNames in interface TreeNode
        Overrides:
        fieldNames in class JsonNode
        Returns:
        An iterator for traversing names of all fields this Object node has (if Object node); empty Iterator otherwise (never null).

      • path

        public JsonNode path​(int index)
        Description copied from class: JsonNode
        This method is similar to JsonNode.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 JsonNode.isMissingNode()) will be returned. This allows for convenient and safe chained access via path calls.
        Specified by:
        path in interface TreeNode
        Specified by:
        path in class JsonNode
        Parameters:
        index - Index of the Array node element to access
        Returns:
        Node that represent value of the specified element, if this node is an array and has specified element; otherwise "missing node" is returned.

      • path

        public JsonNode path​(java.lang.String propertyName)
        Description copied from class: JsonNode
        This method is similar to JsonNode.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 JsonNode.isMissingNode()) will be returned. This allows for convenient and safe chained access via path calls.
        Specified by:
        path in interface TreeNode
        Specified by:
        path in class JsonNode
        Parameters:
        propertyName - Name of the field (of Object node) to access
        Returns:
        Node that represent value of the specified field, if this node is an object and has value for the specified field; otherwise "missing node" is returned.

      • required

        public JsonNode required​(java.lang.String propertyName)
        Description copied from class: JsonNode
        Method is functionally equivalent to path(fieldName).required() and can be used to check that this node is an ObjectNode (that is, represents JSON Object value) and has value for specified property with key fieldName (but note that value may be explicit JSON null value). If this node is Object Node and has value for specified property, matching value is returned; otherwise IllegalArgumentException is thrown.
        Overrides:
        required in class BaseJsonNode
        Parameters:
        propertyName - Name of property to access
        Returns:
        Value of the specified property of this Object node

      • fields

        public java.util.Iterator<java.util.Map.Entry<java.lang.String,​JsonNode>> fields()
        Method to use for accessing all properties (with both names and values) of this JSON Object.
        Overrides:
        fields in class JsonNode
        Returns:
        Iterator that can be used to traverse all key/value pairs for object nodes; empty iterator (no contents) for other types

      • with

        public ObjectNode with​(java.lang.String propertyName)
        Description copied from class: JsonNode
        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

        NOTE: since 2.10 has had co-variant return type

        Overrides:
        with in class JsonNode

      • withArray

        public ArrayNode withArray​(java.lang.String propertyName)
        Description copied from class: JsonNode
        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

        NOTE: since 2.10 has had co-variant return type

        Overrides:
        withArray in class JsonNode

      • equals

        public boolean equals​(java.util.Comparator<JsonNode> comparator,
                      JsonNode o)
        Description copied from class: JsonNode
        Entry method for invoking customizable comparison, using passed-in Comparator object. Nodes will handle traversal of structured types (arrays, objects), but defer to comparator for scalar value comparisons. If a "natural" Comparator is passed -- one that simply calls equals() on one of arguments, passing the other -- implementation is the same as directly calling equals() on node.

        Default implementation simply delegates to passed in comparator, with this as the first argument, and other as the second argument.

        Overrides:
        equals in class JsonNode
        Parameters:
        comparator - Object called to compare two scalar JsonNode instances, and return either 0 (are equals) or non-zero (not equal)

      • findValue

        public JsonNode findValue​(java.lang.String propertyName)
        Description copied from class: JsonNode
        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.
        Specified by:
        findValue in class JsonNode
        Parameters:
        propertyName - Name of field to look for
        Returns:
        Value of first matching node found, if any; null if none

      • findValues

        public java.util.List<JsonNode> findValues​(java.lang.String propertyName,
                                           java.util.List<JsonNode> foundSoFar)
        Specified by:
        findValues in class JsonNode

      • findValuesAsText

        public java.util.List<java.lang.String> findValuesAsText​(java.lang.String propertyName,
                                                         java.util.List<java.lang.String> foundSoFar)
        Specified by:
        findValuesAsText in class JsonNode

      • findParent

        public ObjectNode findParent​(java.lang.String propertyName)
        Description copied from class: JsonNode
        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.
        Specified by:
        findParent in class JsonNode
        Parameters:
        propertyName - Name of field to look for
        Returns:
        Value of first matching node found, if any; null if none

      • findParents

        public java.util.List<JsonNode> findParents​(java.lang.String propertyName,
                                            java.util.List<JsonNode> foundSoFar)
        Specified by:
        findParents in class JsonNode

      • set

        public <T extends JsonNode> T set​(java.lang.String propertyName,
                                  JsonNode value)
        Method that will set specified property, replacing old value, if any. Note that this is identical to replace(String, JsonNode), except for return value.

        NOTE: added to replace those uses of put(String, JsonNode) where chaining with 'this' is desired.

        NOTE: co-variant return type since 2.10

        Parameters:
        propertyName - Name of property to set
        value - Value to set property to; if null, will be converted to a NullNode first (to remove a property, call remove(java.lang.String) instead)
        Returns:
        This node after adding/replacing property value (to allow chaining)
        Since:
        2.1

      • setAll

        public <T extends JsonNode> T setAll​(java.util.Map<java.lang.String,​? extends JsonNode> properties)
        Method for adding given properties to this object node, overriding any existing values for those properties.

        NOTE: co-variant return type since 2.10

        Parameters:
        properties - Properties to add
        Returns:
        This node after adding/replacing property values (to allow chaining)
        Since:
        2.1

      • setAll

        public <T extends JsonNode> T setAll​(ObjectNode other)
        Method for adding all properties of the given Object, overriding any existing values for those properties.

        NOTE: co-variant return type since 2.10

        Parameters:
        other - Object of which properties to add to this object
        Returns:
        This node after addition (to allow chaining)
        Since:
        2.1

      • replace

        public JsonNode replace​(java.lang.String propertyName,
                        JsonNode value)
        Method for replacing value of specific property with passed value, and returning value (or null if none).
        Parameters:
        propertyName - Property of which value to replace
        value - Value to set property to, replacing old value if any
        Returns:
        Old value of the property; null if there was no such property with value
        Since:
        2.1

      • without

        public <T extends JsonNode> T without​(java.lang.String propertyName)
        Method for removing property from this ObjectNode, and returning instance after removal.

        NOTE: co-variant return type since 2.10

        Returns:
        This node after removing property (if any)
        Since:
        2.1

      • without

        public <T extends JsonNode> T without​(java.util.Collection<java.lang.String> propertyNames)
        Method for removing specified field properties out of this ObjectNode.

        NOTE: co-variant return type since 2.10

        Parameters:
        propertyNames - Names of properties to remove
        Returns:
        This node after removing entries
        Since:
        2.1

      • put

        @Deprecated
public JsonNode put​(java.lang.String propertyName,
                    JsonNode value)
        Deprecated.
        Since 2.4 use either set(String,JsonNode) or replace(String,JsonNode),
        Method that will set specified property, replacing old value, if any.
        Parameters:
        propertyName - Name of property to set
        value - Value to set to property; if null, will be converted to a NullNode first (to remove a property, call remove(java.lang.String) instead).
        Returns:
        Old value of the property, if any; null if there was no old value.

      • putIfAbsent

        public JsonNode putIfAbsent​(java.lang.String propertyName,
                            JsonNode value)
        Method that will set value of specified property if (and only if) it had no set value previously. Note that explicitly set null is a value. Functionally equivalent to: if (get(propertyName) == null) { set(propertyName, value); return null; } else { return get(propertyName); }
        Parameters:
        propertyName - Name of property to set
        value - Value to set to property (if and only if it had no value previously); if null, will be converted to a NullNode first.
        Returns:
        Old value of the property, if any (in which case value was not changed); null if there was no old value (in which case value is now set)
        Since:
        2.13

      • remove

        public JsonNode remove​(java.lang.String propertyName)
        Method for removing a property from this ObjectNode. Will return previous value of the property, if such property existed; null if not.
        Returns:
        Value of specified property, if it existed; null if not

      • remove

        public ObjectNode remove​(java.util.Collection<java.lang.String> propertyNames)
        Method for removing specified field properties out of this ObjectNode.
        Parameters:
        propertyNames - Names of fields to remove
        Returns:
        This node after removing entries

      • removeAll

        public ObjectNode removeAll()
        Method for removing all properties, such that this ObjectNode will contain no properties after call.
        Specified by:
        removeAll in class ContainerNode<ObjectNode>
        Returns:
        This node after removing all entries

      • putAll

        @Deprecated
public JsonNode putAll​(java.util.Map<java.lang.String,​? extends JsonNode> properties)
        Deprecated.
        Since 2.4 use setAll(Map),
        Method for adding given properties to this object node, overriding any existing values for those properties.
        Parameters:
        properties - Properties to add
        Returns:
        This node after adding/replacing property values (to allow chaining)

      • putAll

        @Deprecated
public JsonNode putAll​(ObjectNode other)
        Deprecated.
        Since 2.4 use setAll(ObjectNode),
        Method for adding all properties of the given Object, overriding any existing values for those properties.
        Parameters:
        other - Object of which properties to add to this object
        Returns:
        This node (to allow chaining)

      • retain

        public ObjectNode retain​(java.util.Collection<java.lang.String> propertyNames)
        Method for removing all properties out of this ObjectNode except for ones specified in argument.
        Parameters:
        propertyNames - Fields to retain in this ObjectNode
        Returns:
        This node (to allow call chaining)

      • retain

        public ObjectNode retain​(java.lang.String... propertyNames)
        Method for removing all properties out of this ObjectNode except for ones specified in argument.
        Parameters:
        propertyNames - Fields to retain in this ObjectNode
        Returns:
        This node (to allow call chaining)

      • putArray

        public ArrayNode putArray​(java.lang.String propertyName)
        Method that will construct an ArrayNode and add it as a property of this ObjectNode, replacing old value, if any.

        NOTE: Unlike all put(...) methods, return value is NOT this ObjectNode, but the newly created ArrayNode instance.

        Returns:
        Newly constructed ArrayNode (NOT the old value, which could be of any type)

      • putObject

        public ObjectNode putObject​(java.lang.String propertyName)
        Method that will construct an ObjectNode and add it as a property of this ObjectNode, replacing old value, if any.

        NOTE: Unlike all put(...) methods, return value is NOT this ObjectNode, but the newly created ObjectNode instance.

        Returns:
        Newly constructed ObjectNode (NOT the old value, which could be of any type)

      • putPOJO

        public ObjectNode putPOJO​(java.lang.String propertyName,
                          java.lang.Object pojo)
        Method for adding an opaque Java value as the value of specified property. Value can be serialized like any other property, as long as Jackson can serialize it. Despite term "POJO" this allows use of about any Java type, including Maps, Collections, as well as Beans (POJOs), primitives/wrappers and even JsonNodes. Method is most commonly useful when composing content to serialize from heterogenous sources.

        NOTE: if using JsonNode.toString() (or JsonNode.toPrettyString() support for serialization may be more limited, compared to serializing node with specifically configured ObjectMapper.

        Parameters:
        propertyName - Name of property to set.
        pojo - Java value to set as the property value
        Returns:
        This ObjectNode (to allow chaining)

      • putRawValue

        public ObjectNode putRawValue​(java.lang.String propertyName,
                              RawValue raw)
        Since:
        2.6

      • putNull

        public ObjectNode putNull​(java.lang.String propertyName)
        Method for setting value of a property to explicit null value.
        Parameters:
        propertyName - Name of property to set.
        Returns:
        This ObjectNode (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String propertyName,
                      short v)
        Method for setting value of a property to specified numeric value.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.lang.Short v)
        Alternative method that we need to avoid bumping into NPE issues with auto-unboxing.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      int v)
        Method for setting value of a field to specified numeric value. The underlying JsonNode that will be added is constructed using JsonNodeFactory.numberNode(int), and may be "smaller" (like ShortNode) in cases where value fits within range of a smaller integral numeric value.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.lang.Integer v)
        Alternative method that we need to avoid bumping into NPE issues with auto-unboxing.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      long v)
        Method for setting value of a field to specified numeric value. The underlying JsonNode that will be added is constructed using JsonNodeFactory.numberNode(long), and may be "smaller" (like IntNode) in cases where value fits within range of a smaller integral numeric value.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.lang.Long v)
        Method for setting value of a field to specified numeric value. The underlying JsonNode that will be added is constructed using JsonNodeFactory.numberNode(Long), and may be "smaller" (like IntNode) in cases where value fits within range of a smaller integral numeric value.

        Note that this is alternative to put(String, long) needed to avoid bumping into NPE issues with auto-unboxing.

        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      float v)
        Method for setting value of a field to specified numeric value.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.lang.Float v)
        Alternative method that we need to avoid bumping into NPE issues with auto-unboxing.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      double v)
        Method for setting value of a field to specified numeric value.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.lang.Double v)
        Alternative method that we need to avoid bumping into NPE issues with auto-unboxing.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.math.BigDecimal v)
        Method for setting value of a field to specified numeric value.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.math.BigInteger v)
        Method for setting value of a field to specified numeric value.
        Returns:
        This node (to allow chaining)
        Since:
        2.9

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.lang.String v)
        Method for setting value of a field to specified String value.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      boolean v)
        Method for setting value of a field to specified String value.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      java.lang.Boolean v)
        Alternative method that we need to avoid bumping into NPE issues with auto-unboxing.
        Returns:
        This node (to allow chaining)

      • put

        public ObjectNode put​(java.lang.String fieldName,
                      byte[] v)
        Method for setting value of a field to specified binary value
        Returns:
        This node (to allow chaining)

      • equals

        public boolean equals​(java.lang.Object o)
        Description copied from class: JsonNode
        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.

        Specified by:
        equals in class JsonNode