Package net.pwall.json.pointer

Class JSONReference

  • public class JSONReference
extends JSONPointer
    A JSON Reference - a combination of a JSON Pointer and the JSON value to which it refers. This allows for a single object to be used (and passed as a parameter between functions) in the common case of a pointer being employed to navigate a tree of JSON values. The class is implemented as a derived class from JSONPointer - this is an optimisation to reduce object allocation.
    Author:
    Peter Wall

    • Constructor Detail

      • JSONReference

        public JSONReference​(net.pwall.json.JSONValue base,
                     JSONPointer pointer)
        Create a JSON Reference using the given base JSON value and pointer.
        Parameters:
        base - the base JSONValue
        pointer - a JSONPointer to a node within the base value

      • JSONReference

        public JSONReference​(net.pwall.json.JSONValue base,
                     String string)
        Create a JSON Reference using the given base JSON value and a pointer in string form.
        Parameters:
        base - the base JSONValue
        string - a string representing a JSON Pointer
        Throws:
        JSONPointerException - if the string is not either an empty string, or starts with "/"

      • JSONReference

        public JSONReference​(net.pwall.json.JSONValue base)
        Create a JSON Reference using the given base JSON value and a root pointer.
        Parameters:
        base - the base JSONValue

    • Method Detail

      • getPointer

        public JSONPointer getPointer()
        Get the pointer component of the reference. Note that since this class derives from JSONPointer, then provided the virtual functions (e.g. toString()) are not required, the object may simply be cast to a JSONPointer.
        Overrides:
        getPointer in class JSONPointer
        Returns:
        the pointer

      • getBase

        public net.pwall.json.JSONValue getBase()
        Get the base JSONValue.
        Returns:
        the JSONValue

      • isValid

        public boolean isValid()
        Test whether the reference is valid, i.e. the pointer points to a valid location within the base.
        Returns:
        true iff the reference is valid

      • getValue

        public net.pwall.json.JSONValue getValue()
        Get the value referred to by this reference.
        Returns:
        the value, or null if the reference is not valid

      • hasChild

        public boolean hasChild​(String name)
        Test whether the reference has the nominated child (by name).
        Parameters:
        name - the name of the child
        Returns:
        true iff that child exists

      • hasChild

        public boolean hasChild​(int index)
        Test whether the reference has the nominated child (by index).
        Parameters:
        index - the index of the child
        Returns:
        true iff that child exists

      • parent

        public JSONReference parent()
        Navigate to the parent of the currently-addressed element.
        Overrides:
        parent in class JSONPointer
        Returns:
        a reference that refers to the parent element
        Throws:
        JSONPointerException - on any attempt to get the parent of the root element

      • child

        public JSONReference child​(String name)
        Navigate to the named child of the currently-addressed element.
        Overrides:
        child in class JSONPointer
        Parameters:
        name - the name of the child
        Returns:
        a reference that refers to the child element (possibly not valid)

      • child

        public JSONReference child​(int index)
        Navigate to the numbered child of the currently-addressed element (must be an array).
        Overrides:
        child in class JSONPointer
        Parameters:
        index - the index of the child
        Returns:
        a reference that refers to the child element (possibly not valid)
        Throws:
        JSONPointerException - if the index is negative

      • locateChild

        public JSONReference locateChild​(net.pwall.json.JSONValue target)
        Attempt to locate the specified child JSONValue within a nested structure. The function will return a JSONReference 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:
        target - the target of the search
        Returns:
        a JSONReference referring to the base value and the target

      • equals

        public boolean equals​(Object other)
        Compare two JSON references for equality. The references are equal only if the pointers are equal and the base values refer to the same object.
        Overrides:
        equals in class JSONPointer
        Parameters:
        other - the other object for comparison
        Returns:
        true iff the objects are equal

      • hashCode

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

      • toString

        public String toString()
        Get a string representation of the reference.
        Overrides:
        toString in class JSONPointer
        Returns:
        a string representation of the value (or "invalid" if the reference is not valid)