Package net.pwall.json.pointer

Class JSONPointer

  • Direct Known Subclasses:
    JSONReference
    public class JSONPointer
extends Object
    JSON Pointer.
    Author:
    Peter Wall

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static String[] emptyArray  
      static net.pwall.util.CharMapper mapper
      A CharMapper to assist with escaping JSON Pointers.
      static JSONPointer root  
      static net.pwall.util.CharUnmapper unmapper
      A CharUnmapper to assist with unescaping JSON Pointers.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected static <T> T checkNotNull​(T value)
      Check that a user-supplied parameter is not null.
      JSONPointer child​(int index)
      Get a pointer to the numbered child of the currently-addressed element (must be an array).
      JSONPointer child​(String string)
      Get a pointer to the named child of the currently-addressed element.
      static String encodeURI​(String str)
      Encode a string for use in a URI.
      boolean equals​(Object obj)
      Compare two pointers for equality.
      static String escapeToken​(String token)
      Escape a token using the JSON Pointer escaping rules.
      net.pwall.json.JSONValue eval​(net.pwall.json.JSONValue base)
      Evaluate a JSON Pointer against a given JSON value.
      static boolean exists​(String string, net.pwall.json.JSONValue base)
      Test whether a value exists at a given path (as a String).
      boolean exists​(net.pwall.json.JSONValue base)
      Test whether a value exists at a given path.
      static net.pwall.json.JSONValue find​(String string, net.pwall.json.JSONValue base)
      Find the value corresponding to the pointer (as a String) in the given JSON value.
      net.pwall.json.JSONValue find​(net.pwall.json.JSONValue base)
      Find the value corresponding to the pointer in the given JSON value.
      static JSONPointer fromURIFragment​(String fragment)
      Create a JSONPointer from a URI fragment.
      String getCurrent()
      Get the current token, i.e.
      JSONPointer getPointer()
      Get this pointer as a simple JSONPointer.
      String[] getTokens()
      Get the array of tokens for this pointer.
      int hashCode()
      Get the hash code for the pointer.
      JSONPointer locateChild​(net.pwall.json.JSONValue value, net.pwall.json.JSONValue target)
      Attempt to locate the specified child JSONValue within a nested structure.
      JSONPointer parent()
      Get a pointer to the parent of the currently-addressed element.
      protected static String[] parse​(String string)
      Parse a pointer string into an array of pointer elements.
      String toString()
      Get a string representation of the pointer.
      String toURIFragment()
      Convert the pointer to a URI fragment.
      static String unescapeToken​(String str)
      Unescape a token using the JSON Pointer escaping rules.

    • Field Detail

      • emptyArray

        protected static final String[] emptyArray

      • mapper

        public static final net.pwall.util.CharMapper mapper
        A CharMapper to assist with escaping JSON Pointers.

      • unmapper

        public static final net.pwall.util.CharUnmapper unmapper
        A CharUnmapper to assist with unescaping JSON Pointers.

    • Constructor Detail

      • JSONPointer

        public JSONPointer​(String string)
        Main constructor - creates a JSONPointer using the specified path.
        Parameters:
        string - the path
        Throws:
        JSONPointerException - if the string is not either an empty string, or starts with "/"

    • Method Detail

      • eval

        public net.pwall.json.JSONValue eval​(net.pwall.json.JSONValue base)
        Evaluate a JSON Pointer against a given JSON value.
        Parameters:
        base - the base value (path elements will be used to navigate from this point)
        Returns:
        the value at that point (may be null)
        Throws:
        JSONPointerException - if there are any errors in navigation

      • find

        public net.pwall.json.JSONValue find​(net.pwall.json.JSONValue base)
        Find the value corresponding to the pointer in the given JSON value.
        Parameters:
        base - the base value (path elements will be used to navigate from this point)
        Returns:
        the value at that point (may be null)
        Throws:
        JSONPointerException - if there are any errors in navigation

      • exists

        public boolean exists​(net.pwall.json.JSONValue base)
        Test whether a value exists at a given path.
        Parameters:
        base - the base value (path elements will be used to navigate from this point)
        Returns:
        true if the value exists (including if it is null)

      • parent

        public JSONPointer parent()
        Get a pointer to the parent of the currently-addressed element.
        Returns:
        a pointer to the parent element
        Throws:
        JSONPointerException - on any attempt to get the parent of the root element

      • child

        public JSONPointer child​(String string)
        Get a pointer to the named child of the currently-addressed element.
        Parameters:
        string - the name of the child
        Returns:
        a pointer to the child element

      • child

        public JSONPointer child​(int index)
        Get a pointer to the numbered child of the currently-addressed element (must be an array).
        Parameters:
        index - the index of the child
        Returns:
        a pointer to the child element
        Throws:
        JSONPointerException - if the index is negative

      • getPointer

        public JSONPointer getPointer()
        Get this pointer as a simple JSONPointer. Classes that derive from this class (notably JSONReference may override this function to return a simple JSONPointer.
        Returns:
        this pointer

      • getCurrent

        public String getCurrent()
        Get the current token, i.e. the property name or index that this pointer points to at the lowest level. Returns null in the case of the root pointer.
        Returns:
        the property name or array item index, or null if this is the root pointer

      • toURIFragment

        public String toURIFragment()
        Convert the pointer to a URI fragment.
        Returns:
        the URI fragment

      • getTokens

        public String[] getTokens()
        Get the array of tokens for this pointer.
        Returns:
        the array of tokens

      • equals

        public boolean equals​(Object obj)
        Compare two pointers for equality.
        Overrides:
        equals in class Object
        Parameters:
        obj - the other pointer
        Returns:
        true if the pointers are equal

      • hashCode

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

      • toString

        public String toString()
        Get a string representation of the pointer.
        Overrides:
        toString in class Object
        Returns:
        the pointer as a string

      • find

        public static net.pwall.json.JSONValue find​(String string,
                                            net.pwall.json.JSONValue base)
        Find the value corresponding to the pointer (as a String) in the given JSON value.
        Parameters:
        string - the pointer as a string
        base - the base value (path elements will be used to navigate from this point)
        Returns:
        the value at that point (may be null)
        Throws:
        JSONPointerException - if there are any errors in navigation

      • exists

        public static boolean exists​(String string,
                             net.pwall.json.JSONValue base)
        Test whether a value exists at a given path (as a String).
        Parameters:
        string - the pointer as a string
        base - the base value (path elements will be used to navigate from this point)
        Returns:
        true if the value exists (including if it is null)

      • checkNotNull

        protected static <T> T checkNotNull​(T value)
        Check that a user-supplied parameter is not null.
        Type Parameters:
        T - the type of the parameter
        Parameters:
        value - the parameter
        Returns:
        the value, if it is not null
        Throws:
        NullPointerException - if the value is null

      • parse

        protected static String[] parse​(String string)
        Parse a pointer string into an array of pointer elements.
        Parameters:
        string - the original string
        Returns:
        the array of elements
        Throws:
        JSONPointerException - if the string is not either an empty string, or starts with "/"

      • locateChild

        public JSONPointer locateChild​(net.pwall.json.JSONValue value,
                               net.pwall.json.JSONValue target)
        Attempt to locate the specified child JSONValue within a nested structure. The function will return a JSONPointer to the target, or null if the target can not be located. Note that this will perform a depth-first search of the entire structure, comparing on object identity, not equality.
        Parameters:
        value - the base JSONValue within which to search
        target - the target of the search
        Returns:
        a JSONPointer to locate the target in the base value

      • encodeURI

        public static String encodeURI​(String str)
        Encode a string for use in a URI. This conversion uses "%20" to encode spaces rather than "+", because that is the form used in the JSON Pointer specification.
        Parameters:
        str - the input string
        Returns:
        the encoded string

      • fromURIFragment

        public static JSONPointer fromURIFragment​(String fragment)
        Create a JSONPointer from a URI fragment.
        Parameters:
        fragment - the URI fragment
        Returns:
        the pointer
        Throws:
        JSONPointerException - if the fragment is illegal (does not start with "#/")

      • escapeToken

        public static String escapeToken​(String token)
        Escape a token using the JSON Pointer escaping rules.
        Parameters:
        token - the token
        Returns:
        the escaped token

      • unescapeToken

        public static String unescapeToken​(String str)
        Unescape a token using the JSON Pointer escaping rules.
        Parameters:
        str - the escaped token
        Returns:
        the unescaped token