Package jakarta.json

Interface JsonPointer

public interface JsonPointer

This interface represents an immutable implementation of a JSON Pointer as defined by RFC 6901.

A JSON Pointer, when applied to a target JsonValue, defines a reference location in the target.

An empty JSON Pointer string defines a reference to the target itself.

If the JSON Pointer string is non-empty, it must be a sequence of '/' prefixed tokens, and the target must either be a JsonArray or JsonObject. If the target is a JsonArray, the pointer defines a reference to an array element, and the last token specifies the index. If the target is a JsonObject, the pointer defines a reference to a name/value pair, and the last token specifies the name.

The method getValue() returns the referenced value. Methods add(), replace(), and remove() execute operations specified in RFC 6902.

Since:
1.1
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    <T extends JsonStructure>
    T
    add(T target, JsonValue value)
    Adds or replaces a value at the referenced location in the specified target with the specified value.
    boolean
    containsValue(JsonStructure target)
    Returns true if there is a value at the referenced location in the specified target.
    JsonValue
    getValue(JsonStructure target)
    Returns the value at the referenced location in the specified target.
    <T extends JsonStructure>
    T
    remove(T target)
    Removes the value at the reference location in the specified target.
    <T extends JsonStructure>
    T
    replace(T target, JsonValue value)
    Replaces the value at the referenced location in the specified target with the specified value.
    String
    toString()
    Returns the string representation of this JSON Pointer.

  • Method Details

    • add

      <T extends JsonStructure> T add(T target, JsonValue value)
      Adds or replaces a value at the referenced location in the specified target with the specified value.
      1. If the reference is the target (empty JSON Pointer string), the specified value, which must be the same type as specified target, is returned.
      2. If the reference is an array element, the specified value is inserted into the array, at the referenced index. The value currently at that location, and any subsequent values, are shifted to the right (adds one to the indices). Index starts with 0. If the reference is specified with a "-", or if the index is equal to the size of the array, the value is appended to the array.
      3. If the reference is a name/value pair of a JsonObject, and the referenced value exists, the value is replaced by the specified value. If the value does not exist, a new name/value pair is added to the object.
      Type Parameters:
      T - the target type, must be a subtype of JsonValue
      Parameters:
      target - the target referenced by this JsonPointer
      value - the value to be added
      Returns:
      the transformed target after the value is added.
      Throws:
      NullPointerException - if target is null
      JsonException - if the reference is an array element and the index is out of range (index < 0 || index > array size), or if the pointer contains references to non-existing objects or arrays.

    • remove

      <T extends JsonStructure> T remove(T target)
      Removes the value at the reference location in the specified target.
      Type Parameters:
      T - the target type, must be a subtype of JsonValue
      Parameters:
      target - the target referenced by this JsonPointer
      Returns:
      the transformed target after the value is removed.
      Throws:
      NullPointerException - if target is null
      JsonException - if the referenced value does not exist, or if the reference is the target.

    • replace

      <T extends JsonStructure> T replace(T target, JsonValue value)
      Replaces the value at the referenced location in the specified target with the specified value.
      Type Parameters:
      T - the target type, must be a subtype of JsonValue
      Parameters:
      target - the target referenced by this JsonPointer
      value - the value to be stored at the referenced location
      Returns:
      the transformed target after the value is replaced.
      Throws:
      NullPointerException - if target is null
      JsonException - if the referenced value does not exist, or if the reference is the target.

    • containsValue

      boolean containsValue(JsonStructure target)
      Returns true if there is a value at the referenced location in the specified target.
      Parameters:
      target - the target referenced by this JsonPointer
      Returns:
      true if this pointer points to a value in a specified target.

    • getValue

      JsonValue getValue(JsonStructure target)
      Returns the value at the referenced location in the specified target.
      Parameters:
      target - the target referenced by this JsonPointer
      Returns:
      the referenced value in the target.
      Throws:
      NullPointerException - if target is null
      JsonException - if the referenced value does not exist

    • toString

      String toString()
      Returns the string representation of this JSON Pointer. The value to be returned is an empty string or a sequence of '/' prefixed tokens.
      Overrides:
      toString in class Object
      Returns:
      the valid escaped JSON Pointer string.