Class NodeReference

  • Direct Known Subclasses:
    NodeReference.ArrayReference, NodeReference.ObjectReference, NodeReference.RootReference

    abstract class NodeReference
    extends java.lang.Object
    This class is a helper class for JsonPointer implementation, and is not part of the API. This class encapsulates a reference to a JSON node. There are three types of references.
    1. a reference to the root of a JSON tree.
    2. a reference to a name/value (possibly non-existing) pair of a JSON object, identified by a name.
    3. a reference to a member value of a JSON array, identified by an index.
    Static factory methods are provided for creating these references.

    A referenced value can be retrieved or replaced. The value of a JSON object or JSON array can be removed. A new value can be added to a JSON object or inserted into a JSON array

    Since a JsonObject or JsonArray is immutable, these operations must not modify the referenced JSON object or array. The methods add(jakarta.json.JsonValue), replace(jakarta.json.JsonValue), and remove() returns a new JSON object or array after the execution of the operation.

    • Constructor Summary

      Constructors 
      Constructor Description
      NodeReference()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract jakarta.json.JsonStructure add​(jakarta.json.JsonValue value)
      Add or replace a value at the referenced location.
      abstract boolean contains()
      Return true if a reference points to a valid value, false otherwise.
      abstract jakarta.json.JsonValue get()
      Get the value at the referenced location.
      (package private) static NodeReference of​(jakarta.json.JsonArray array, int index, JsonContext jsonContext)
      Returns a NodeReference for a member value in a JSON array.
      (package private) static NodeReference of​(jakarta.json.JsonObject object, java.lang.String name, JsonContext jsonContext)
      Returns a NodeReference for a name/value pair in a JSON object.
      (package private) static NodeReference of​(jakarta.json.JsonStructure structure)
      Returns a NodeReference for a JsonStructure.
      abstract jakarta.json.JsonStructure remove()
      Remove the name/value pair from the JSON object, or the value in a JSON array, as specified by the reference
      abstract jakarta.json.JsonStructure replace​(jakarta.json.JsonValue value)
      Replace the referenced value with the specified value.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • NodeReference

        NodeReference()
    • Method Detail

      • contains

        public abstract boolean contains()
        Return true if a reference points to a valid value, false otherwise.
        Returns:
        true if a reference points to a value
      • get

        public abstract jakarta.json.JsonValue get()
        Get the value at the referenced location.
        Returns:
        the JSON value referenced
        Throws:
        jakarta.json.JsonException - if the referenced value does not exist
      • add

        public abstract jakarta.json.JsonStructure add​(jakarta.json.JsonValue value)
        Add or replace a value at the referenced location. If the reference is the root of a JSON tree, the added value must be a JSON object or array, which becomes the referenced JSON value. If the reference is an index of a JSON array, the value is inserted into the array at the index. If the index is -1, the value is appended to the array. If the reference is a name of a JSON object, the name/value pair is added to the object, replacing any pair with the same name.
        Parameters:
        value - the value to be added
        Returns:
        the JsonStructure after the operation
        Throws:
        jakarta.json.JsonException - if the index to the array is not -1 or is out of range
      • remove

        public abstract jakarta.json.JsonStructure remove()
        Remove the name/value pair from the JSON object, or the value in a JSON array, as specified by the reference
        Returns:
        the JsonStructure after the operation
        Throws:
        jakarta.json.JsonException - if the name/value pair of the referenced JSON object does not exist, or if the index of the referenced JSON array is out of range, or if the reference is a root reference
      • replace

        public abstract jakarta.json.JsonStructure replace​(jakarta.json.JsonValue value)
        Replace the referenced value with the specified value.
        Parameters:
        value - the JSON value to be stored at the referenced location
        Returns:
        the JsonStructure after the operation
        Throws:
        jakarta.json.JsonException - if the name/value pair of the referenced JSON object does not exist, or if the index of the referenced JSON array is out of range, or if the reference is a root reference
      • of

        static NodeReference of​(jakarta.json.JsonStructure structure)
        Returns a NodeReference for a JsonStructure.
        Parameters:
        structure - the JsonStructure referenced
        Returns:
        the NodeReference
      • of

        static NodeReference of​(jakarta.json.JsonObject object,
                                java.lang.String name,
                                JsonContext jsonContext)
        Returns a NodeReference for a name/value pair in a JSON object.
        Parameters:
        object - the referenced JSON object
        name - the name of the name/pair
        Returns:
        the NodeReference
      • of

        static NodeReference of​(jakarta.json.JsonArray array,
                                int index,
                                JsonContext jsonContext)
        Returns a NodeReference for a member value in a JSON array.
        Parameters:
        array - the referenced JSON array
        index - the index of the member value in the JSON array
        Returns:
        the NodeReference