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(javax.json.JsonValue), replace(javax.json.JsonValue), and remove() returns a new JSON object or array after the execution of the operation.

    • 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 JsonValue get()
        Get the value at the referenced location.
        Returns:
        the JSON value referenced
        Throws:
        JsonException - if the referenced value does not exist
      • add

        public abstract JsonStructure add​(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:
        JsonException - if the index to the array is not -1 or is out of range
      • remove

        public abstract 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:
        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 JsonStructure replace​(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:
        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

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

        public static NodeReference of​(JsonObject object,
                                       java.lang.String name)
        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

        public static NodeReference of​(JsonArray array,
                                       int index)
        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