Package org.apache.juneau.marshall.collections

Class JsonPointer

java.lang.Object
org.apache.juneau.marshall.collections.JsonPointer
public class JsonPointer extends Object
An RFC 6901 JSON Pointer that addresses a single value within a Map/List tree (such as the MarshalledMap/MarshalledList family).

A JSON Pointer is a string of zero or more /-prefixed reference tokens. The empty string "" references the whole document (the root). A non-empty pointer must begin with /; each token is the text between / separators with ~1 decoded to / and ~0 decoded to ~. For arrays a token is either a base-10 non-negative integer index or the single character - (which references the nonexistent element after the last element, used to append on writes); for objects the decoded token is the member name.

Example:

JsonMap doc = JsonMap.of("foo", JsonList.of("bar", "baz")); // Read. Object v = JsonPointer.of("/foo/0").eval(doc); // "bar" // Auto-vivifying write (creates intermediate containers). JsonPointer.of("/foo/-").set(doc, "qux"); // appends "qux"

Notes:
  • This class is not thread safe.
  • Read-miss (missing key, out-of-range index, or type mismatch) resolves to null via eval(Object).

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 JsonPointer of(String pointer)
      Parses and validates the specified RFC 6901 JSON Pointer string.
      Parameters:
      pointer - The pointer string. The empty string references the whole document; a non-empty pointer must begin with /.
      Returns:
      A new JsonPointer, never null.
      Throws:
      IllegalArgumentException - If the pointer is null or malformed (non-empty and not beginning with /).

    • encodeToken

      public static String encodeToken(String rawMemberName)
      Encodes a raw object member name into an RFC 6901 reference token (escapes ~ to ~0 and / to ~1).
      Parameters:
      rawMemberName - The raw member name. Must not be null.
      Returns:
      The encoded reference token.

    • decodeToken

      public static String decodeToken(String token)
      Decodes an RFC 6901 reference token into a raw object member name (unescapes ~1 to / then ~0 to ~).
      Parameters:
      token - The reference token. Must not be null.
      Returns:
      The decoded member name.

    • eval

      public Object eval(Object root)
      Reads the value addressed by this pointer from the specified root.

      Walks the tokens from root (which may be a Map/List such as the MarshalledMap/ MarshalledList family). The empty pointer returns root.

      Parameters:
      root - The root document. Can be null (treated as an empty document; the addressed value evaluates to null).
      Returns:
      The addressed value, or null on any missing key, out-of-range index, or type mismatch.

    • set

      public Object set(Object root, Object value)
      Writes the specified value at the location addressed by this pointer, 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. The empty pointer cannot mutate root in place for the whole-document case, so it simply returns value as the new root.

      Parameters:
      root - The root document. For a non-empty pointer, must be a mutable Map/List tree.
      value - The value to set.
      Returns:
      The (possibly newly-created) effective root.

    • remove

      public Object remove(Object root)
      Removes the member or element addressed by this pointer.
      Parameters:
      root - The root document. Can be null (treated as an empty document — nothing is found to remove).
      Returns:
      The removed value, or null if the addressed member/element was absent (or the pointer is the root pointer).

    • toString

      public String toString()
      Overrides:
      toString in class Object