Package org.apache.juneau.marshall.collections

Class MarshalledNode

java.lang.Object
org.apache.juneau.marshall.collections.MarshalledNode
public class MarshalledNode extends Object
Typed tree façade over the generic-collections model (MarshalledMap / MarshalledList and their JsonMap / JsonList subclasses).

This is a live, mutating view (a façade — not a parallel node hierarchy) wrapping a single backing value which is one of:

  • a Map (an object node),
  • a List (an array node),
  • a scalar value (String, Number, Boolean, etc.) (a value node), or
  • null (a null node).

It gives Jackson-migrants the ergonomics they expect (node-type introspection, typed value accessors, and fluent tree building) without replacing the underlying Map/List representation. Because it is a live view, mutating builders such as put(String,Object) and add(Object) mutate the backing container in place — callers holding the underlying map/list see the change. Use copy() for an independent deep-copy snapshot.

Example:

// Build a tree fluently (mutates a backing JsonMap/JsonList in place). MarshalledNode node = MarshalledNode.objectNode() .put("a", 1) .put("b", MarshalledNode.arrayNode().add("x").add("y").value()); String json = Json.of(node.value()); // {"a":1,"b":["x","y"]} // Navigate and read typed values. Integer a = node.get("a").asInt(); // 1 String x = node.get("b").get(0).asString(); // "x"

Notes:
  • This class is not thread safe.

Beta — API subject to change: This type is part of the next-generation typed tree model layered over the Marshalled* collections and may change incompatibly in a future release.

  • Method Details

    • of

      public static MarshalledNode of(Object value)
      Wraps any value as a node.

      The value is stored as-is (no copy): a Map becomes an object node, a List becomes an array node, a non-null non-container value becomes a value node, and null becomes a null node. For navigation and fluent building to work the value should be (or contain) the MarshalledMap/MarshalledList family, but any Map/List is accepted.

      Parameters:
      value - The value to wrap. Can be null (creates a null node).
      Returns:
      A new node wrapping the value, never null.

    • objectNode

      public static MarshalledNode objectNode()
      Creates a new object node backed by a new empty JsonMap.
      Returns:
      A new object node, never null.

    • arrayNode

      public static MarshalledNode arrayNode()
      Creates a new array node backed by a new empty JsonList.
      Returns:
      A new array node, never null.

    • isObject

      public boolean isObject()
      Returns true if this node wraps a Map (an object node).
      Returns:
      true if this is an object node.

    • isArray

      public boolean isArray()
      Returns true if this node wraps a List (an array node).
      Returns:
      true if this is an array node.

    • isValue

      public boolean isValue()
      Returns true if this node wraps a non-null scalar (not a Map or List).
      Returns:
      true if this is a value node.

    • isNull

      public boolean isNull()
      Returns true if this node wraps null.
      Returns:
      true if this is a null node.

    • asString

      public String asString()
      Returns the backing value converted to a String.
      Returns:
      The converted value, or null if this is not a value node or the value cannot be converted.

    • asInt

      public Integer asInt()
      Returns the backing value converted to an Integer.
      Returns:
      The converted value, or null if this is not a value node or the value cannot be converted.

    • asLong

      public Long asLong()
      Returns the backing value converted to a Long.
      Returns:
      The converted value, or null if this is not a value node or the value cannot be converted.

    • asDouble

      public Double asDouble()
      Returns the backing value converted to a Double.
      Returns:
      The converted value, or null if this is not a value node or the value cannot be converted.

    • asBoolean

      public Boolean asBoolean()
      Returns the backing value converted to a Boolean.
      Returns:
      The converted value, or null if this is not a value node or the value cannot be converted.

    • as

      public <T> T as(Class<T> type)
      Converts the raw backing value to the specified type.

      Unlike the scalar accessors, this works on object nodes too (e.g. converting a Map object node to a bean). Routes through the same conversion machinery used by MarshalledMap.get(String,Class).

      Type Parameters:
      T - The type to convert to.
      Parameters:
      type - The type to convert to.
      Returns:
      The converted value, or null if the backing value is null or cannot be converted.

    • value

      public Object value()
      Returns the raw backing value wrapped by this node.
      Returns:
      The raw backing value, or null if this is a null node.

    • get

      public MarshalledNode get(String name)
      Returns the child node for the specified key on an object node.
      Parameters:
      name - The key.
      Returns:
      The child node, or null if this is not an object node or the key is absent.

    • get

      public MarshalledNode get(int index)
      Returns the element node at the specified index on an array node.
      Parameters:
      index - The zero-based index.
      Returns:
      The element node, or null if this is not an array node or the index is out of range.

    • size

      public int size()
      Returns the number of entries (object) or elements (array) in this node.
      Returns:
      The size, or 0 if this is a value or null node.

    • put

      public MarshalledNode put(String name, Object value)
      Adds or replaces an entry on an object node, mutating the backing Map in place.
      Parameters:
      name - The key.
      value - The value.
      Returns:
      This object.
      Throws:
      IllegalStateException - If this is not an object node.

    • add

      public MarshalledNode add(Object value)
      Appends a value on an array node, mutating the backing List in place.
      Parameters:
      value - The value to append.
      Returns:
      This object.
      Throws:
      IllegalStateException - If this is not an array node.

    • copy

      public MarshalledNode copy()
      Returns a new node backed by a deep copy of this node's backing value.

      Maps are copied into new JsonMap instances and lists into new JsonList instances (recursively); scalars and null are returned as-is (they are immutable). Mutating the copy does not affect the original and vice versa.

      Returns:
      A new independent node, never null.

    • at

      public MarshalledNode at(String pointer)
      Returns the node addressed by the specified RFC 6901 JSON Pointer relative to this node's backing value.

      A read-miss (missing key, out-of-range index, or type mismatch) returns null so callers can null-check. If the addressed value exists and is JSON null, a null node is returned (use isNull() to test it). The empty pointer addresses this node's whole backing value.

      Parameters:
      pointer - The RFC 6901 JSON Pointer.
      Returns:
      A node wrapping the addressed value, or null if the addressed value is absent.

    • find

      public Optional<MarshalledNode> find(String pointer)
      Optional read variant of at(String).
      Parameters:
      pointer - The RFC 6901 JSON Pointer.
      Returns:
      The addressed node (present, possibly a null node), or an empty Optional if the addressed value is absent.

    • set

      public MarshalledNode set(String pointer, Object value)
      Writes the specified value at the location addressed by the specified RFC 6901 JSON Pointer, mutating the backing container in place and auto-vivifying missing intermediate containers.

      Intermediate containers are created based on the next token (a numeric or - token implies a JsonList, otherwise a JsonMap); the - token on a list appends. Because the backing value is final, the empty (root) pointer cannot replace this node's whole document in place and is therefore rejected.

      Parameters:
      pointer - The RFC 6901 JSON Pointer. Must not be the root pointer.
      value - The value to set.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If pointer is the empty/root pointer.

    • remove

      public Object remove(String pointer)
      Removes the member or element addressed by the specified RFC 6901 JSON Pointer.
      Parameters:
      pointer - The RFC 6901 JSON Pointer.
      Returns:
      The removed value, or null if the addressed member/element was absent.