Package org.forgerock.json

Class JsonPointer

java.lang.Object
org.forgerock.json.JsonPointer
All Implemented Interfaces:
Iterable<String>
public class JsonPointer extends Object implements Iterable<String>
Identifies a specific value within a JSON structure. Conforms with draft-pbryan-zip-json-pointer-02.

This class is immutable.

  • Constructor Summary

    Constructors
    Constructor
    Description
    JsonPointer()
    Deprecated.
    Use rootPtr() instead.
    JsonPointer(Iterable<String> iterable)
    Constructs a JSON pointer from an iterable collection of reference tokens.
    JsonPointer(String pointer)
    Constructs a JSON pointer, identifying the specified pointer value.
    JsonPointer(String... tokens)
    Constructs a JSON pointer from an array of reference tokens.

  • Method Summary

    Modifier and Type
    Method
    Description
    JsonPointer
    child(int child)
    Returns a new JSON pointer, which identifies a specified child element of the array identified by this pointer.
    JsonPointer
    child(String child)
    Returns a new JSON pointer, which identifies a specified child member of the object identified by this pointer.
    JsonPointer
    concat(JsonPointer suffix)
    Creates a new JSON pointer which is a descendant of this JSON pointer.
    boolean
    equals(Object o)
    Compares the specified object with this pointer for equality.
    String
    get(int index)
    Returns the reference token at the specified position.
    String
    getValue()
    Returns the JSON pointer string value.
    int
    hashCode()
    Returns the hash code value for this pointer.
    JsonPointer
    head(int endIndex)
    Returns a pointer which is a subsequence of the path elements contained in this pointer beginning with the first element (0) and ending with the element at position endIndex-1.
    boolean
    isEmpty()
    Returns true if this pointer identifies the root value of a JSON structure.
    boolean
    isPrefixOf(JsonPointer candidate)
    Checks whether candidate is an extension of this JSON Pointer.
    Iterator<String>
    iterator()
    Returns an iterator over the pointer's reference tokens.
    String
    leaf()
    Returns the last (leaf) reference token of the JSON pointer, or null if the pointer contains no reference tokens (i.e.
    JsonPointer
    parent()
    Returns a pointer to the parent of the JSON value identified by this JSON pointer, or null if the pointer has no parent JSON value (i.e.
    static JsonPointer
    ptr(Iterable<String> iterable)
    Constructs a JSON pointer from an iterable collection of reference tokens.
    static JsonPointer
    ptr(String pointer)
    Constructs a JSON pointer, identifying the specified pointer value.
    static JsonPointer
    ptr(String... tokens)
    Constructs a JSON pointer from an array of reference tokens.
    JsonPointer
    relativePointer()
    Returns a pointer containing all but the first reference token contained in this pointer, or / if this pointer contains less than 2 reference tokens.
    JsonPointer
    relativePointer(int sz)
    Returns a pointer containing the last sz reference tokens contained in this pointer.
    static JsonPointer
    rootPtr()
    Returns a JSON pointer identifying the root value of a JSON structure.
    int
    size()
    Returns the number of reference tokens in the pointer.
    String[]
    toArray()
    Returns a newly allocated array of strings, containing the pointer's reference tokens.
    String
    toString()
    Returns the JSON pointer string value.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Constructor Details

    • JsonPointer

      @Deprecated public JsonPointer()
      Deprecated.
      Use rootPtr() instead.
      Constructs a JSON pointer, identifying the root value of a JSON structure.

    • JsonPointer

      public JsonPointer(String pointer)
      Constructs a JSON pointer, identifying the specified pointer value.
      Parameters:
      pointer - a string containing the JSON pointer of the value to identify.
      Throws:
      JsonException - if the pointer is malformed.

    • JsonPointer

      public JsonPointer(String... tokens)
      Constructs a JSON pointer from an array of reference tokens.
      Parameters:
      tokens - an array of string reference tokens.

    • JsonPointer

      public JsonPointer(Iterable<String> iterable)
      Constructs a JSON pointer from an iterable collection of reference tokens.
      Parameters:
      iterable - an iterable collection of reference tokens.

  • Method Details

    • rootPtr

      public static JsonPointer rootPtr()
      Returns a JSON pointer identifying the root value of a JSON structure.
      Returns:
      A JSON pointer identifying the root value of a JSON structure.

    • ptr

      public static JsonPointer ptr(String pointer)
      Constructs a JSON pointer, identifying the specified pointer value.
      Parameters:
      pointer - a string containing the JSON pointer of the value to identify.
      Returns:
      The new JSON pointer
      Throws:
      JsonException - if the pointer is malformed.

    • ptr

      public static JsonPointer ptr(String... tokens)
      Constructs a JSON pointer from an array of reference tokens.
      Parameters:
      tokens - an array of string reference tokens.
      Returns:
      The new json pointer

    • ptr

      public static JsonPointer ptr(Iterable<String> iterable)
      Constructs a JSON pointer from an iterable collection of reference tokens.
      Parameters:
      iterable - an iterable collection of reference tokens.
      Returns:
      The new json pointer

    • size

      public int size()
      Returns the number of reference tokens in the pointer.
      Returns:
      the number of reference tokens in the pointer.

    • get

      public String get(int index)
      Returns the reference token at the specified position.
      Parameters:
      index - the index of the reference token to return.
      Returns:
      the reference token at the specified position.
      Throws:
      IndexOutOfBoundsException - if the index is out of range.

    • toArray

      public String[] toArray()
      Returns a newly allocated array of strings, containing the pointer's reference tokens. No references to the array are maintained by the pointer. Hence, the caller is free to modify it.
      Returns:
      a newly allocated array of strings, containing the pointer's reference tokens.

    • parent

      public JsonPointer parent()
      Returns a pointer to the parent of the JSON value identified by this JSON pointer, or null if the pointer has no parent JSON value (i.e. references document root).
      Returns:
      a pointer to the parent of of this JSON pointer. Can be null.

    • head

      public JsonPointer head(int endIndex)
      Returns a pointer which is a subsequence of the path elements contained in this pointer beginning with the first element (0) and ending with the element at position endIndex-1. The returned pointer will therefore have the size endIndex.
      Parameters:
      endIndex - The end index, exclusive.
      Returns:
      A pointer which is a subsequence of the path elements contained in this resource path.
      Throws:
      IndexOutOfBoundsException - If endIndex is bigger than size().

    • isPrefixOf

      public boolean isPrefixOf(JsonPointer candidate)
      Checks whether candidate is an extension of this JSON Pointer.
      Parameters:
      candidate - The JSON Pointer to test.
      Returns:
      true if this JSON Pointer is a prefix for the candidate JSON Pointer.

    • relativePointer

      public JsonPointer relativePointer()
      Returns a pointer containing all but the first reference token contained in this pointer, or / if this pointer contains less than 2 reference tokens.

      This method yields the following results:

      Examples illustrating usage of relativePointer
      Input Output
      / /
      /a /
      /a/b /b
      /a/b/c /b/c
      Returns:
      A pointer containing all but the first reference token contained in this pointer.

    • relativePointer

      public JsonPointer relativePointer(int sz)
      Returns a pointer containing the last sz reference tokens contained in this pointer.

      This method yields the following results:

      Examples illustrating usage of relativePointer
      Input sz Output
      /a/b/c 0 /
      /a/b/c 1 /c
      /a/b/c 2 /b/c
      /a/b/c 3 /a/b/c
      Parameters:
      sz - The number of trailing reference tokens to retain.
      Returns:
      A pointer containing the last sz reference tokens contained in this pointer.
      Throws:
      IndexOutOfBoundsException - If sz is negative or greater than size().

    • leaf

      public String leaf()
      Returns the last (leaf) reference token of the JSON pointer, or null if the pointer contains no reference tokens (i.e. references document root).
      Returns:
      the last (leaf) reference token of the JSON pointer if it exists, null otherwise

    • child

      public JsonPointer child(String child)
      Returns a new JSON pointer, which identifies a specified child member of the object identified by this pointer.
      Parameters:
      child - the name of the child member to identify.
      Returns:
      the child JSON pointer.
      Throws:
      NullPointerException - if child is null.

    • child

      public JsonPointer child(int child)
      Returns a new JSON pointer, which identifies a specified child element of the array identified by this pointer.
      Parameters:
      child - the index of the child element to identify.
      Returns:
      the child JSON pointer.
      Throws:
      IndexOutOfBoundsException - if child is less than zero.

    • concat

      public JsonPointer concat(JsonPointer suffix)
      Creates a new JSON pointer which is a descendant of this JSON pointer. The returned JSON pointer will have been formed of the concatenation of this JSON pointer and the provided JSON pointer.
      Parameters:
      suffix - the JSON pointer to be appended to this JSON pointer.
      Returns:
      A new JSON pointer which is a descendant of this JSON pointer.

    • isEmpty

      public boolean isEmpty()
      Returns true if this pointer identifies the root value of a JSON structure. More specifically, it returns true if this pointer does not contain any reference tokens (i.e. size() == 0).
      Returns:
      true if this pointer identifies the root value of a JSON structure.

    • iterator

      public Iterator<String> iterator()
      Returns an iterator over the pointer's reference tokens.
      Specified by:
      iterator in interface Iterable<String>
      Returns:
      an iterator over the pointer's reference tokens.

    • toString

      public String toString()
      Returns the JSON pointer string value.
      Overrides:
      toString in class Object
      Returns:
      the JSON pointer string value.

    • getValue

      public String getValue()
      Returns the JSON pointer string value.
      Returns:
      the JSON pointer string value.

    • equals

      public boolean equals(Object o)
      Compares the specified object with this pointer for equality. Returns true if and only if the specified object is also a JSON pointer, both pointers have the same size, and all corresponding pairs of reference tokens in the two pointers are equal.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to be compared for equality with this pointer.
      Returns:
      true if the specified object is equal to this pointer.

    • hashCode

      public int hashCode()
      Returns the hash code value for this pointer.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value for this pointer.