Package com.fasterxml.jackson.core

Class JsonPointer

  • public class JsonPointer
extends java.lang.Object
    Implementation of JSON Pointer specification. Pointer instances can be used to locate logical JSON nodes for things like tree traversal (see TreeNode.at(com.fasterxml.jackson.core.JsonPointer)). It may be used in future for filtering of streaming JSON content as well (not implemented yet for 2.3).

    Instances are fully immutable and can be cached, shared between threads.

    Since:
    2.3
    Author:
    Tatu Saloranta

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String _asString
      We will retain representation of the pointer, as a String, so that toString() should be as efficient as possible.
      protected JsonPointer _head
      Reference from currently matching segment (if any) to node before leaf.
      protected int _matchingElementIndex  
      protected java.lang.String _matchingPropertyName  
      protected JsonPointer _nextSegment
      Reference to rest of the pointer beyond currently matching segment (if any); null if this pointer refers to the matching segment.
      protected static JsonPointer EMPTY
      Marker instance used to represent segment that matches current node or position (that is, returns true for matches()).
      static char SEPARATOR
      Character used to separate segments.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected JsonPointer()
      Constructor used for creating "empty" instance, used to represent state that matches current node.
      protected JsonPointer​(java.lang.String fullString, java.lang.String segment, int matchIndex, JsonPointer next)  
      protected JsonPointer​(java.lang.String fullString, java.lang.String segment, JsonPointer next)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected JsonPointer _constructHead()  
      protected JsonPointer _constructHead​(int suffixLength, JsonPointer last)  
      protected static JsonPointer _parseQuotedTail​(java.lang.String input, int i)
      Method called to parse tail of pointer path, when a potentially escaped character has been seen.
      protected static JsonPointer _parseTail​(java.lang.String input)  
      JsonPointer append​(JsonPointer tail)
      Mutant factory method that will return `tail` if `this` instance is "empty" pointer, OR `this` instance if `tail` is "empty" pointer, OR Newly constructed JsonPointer instance that starts with all segments of `this`, followed by all segments of `tail`.
      static JsonPointer compile​(java.lang.String expr)
      Factory method that parses given input and construct matching pointer instance, if it represents a valid JSON Pointer: if not, a IllegalArgumentException is thrown.
      static JsonPointer empty()
      Accessor for an "empty" expression, that is, one you can get by calling compile(java.lang.String) with "" (empty String).
      boolean equals​(java.lang.Object o)  
      static JsonPointer forPath​(JsonStreamContext context, boolean includeRoot)
      Factory method that will construct a pointer instance that describes path to location given JsonStreamContext points to.
      int getMatchingIndex()  
      java.lang.String getMatchingProperty()  
      int hashCode()  
      JsonPointer head()
      Accessor for getting a pointer instance that is identical to this instance except that the last segment has been dropped.
      JsonPointer last()  
      JsonPointer matchElement​(int index)
      Method that may be called to check whether the pointer head (first segment) matches specified Array index and if so, return JsonPointer that represents rest of the path after match.
      boolean matches()  
      boolean matchesElement​(int index)
      Method that may be called to see if the pointer would match Array element (of a JSON Array) with given index.
      boolean matchesProperty​(java.lang.String name)
      Method that may be called to see if the pointer head (first segment) would match property (of a JSON Object) with given name.
      JsonPointer matchProperty​(java.lang.String name)
      Method that may be called to check whether the pointer head (first segment) matches specified Object property (by name) and if so, return JsonPointer that represents rest of the path after match.
      boolean mayMatchElement()  
      boolean mayMatchProperty()  
      JsonPointer tail()
      Accessor for getting a "sub-pointer" (or sub-path), instance where current segment has been removed and pointer includes rest of the segments.
      java.lang.String toString()  
      static JsonPointer valueOf​(java.lang.String expr)
      Alias for compile(java.lang.String); added to make instances automatically deserializable by Jackson databind.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • SEPARATOR

        public static final char SEPARATOR
        Character used to separate segments.
        Since:
        2.9
        See Also:
        Constant Field Values

      • EMPTY

        protected static final JsonPointer EMPTY
        Marker instance used to represent segment that matches current node or position (that is, returns true for matches()).

      • _nextSegment

        protected final JsonPointer _nextSegment
        Reference to rest of the pointer beyond currently matching segment (if any); null if this pointer refers to the matching segment.

      • _head

        protected volatile JsonPointer _head
        Reference from currently matching segment (if any) to node before leaf. Lazily constructed if/as needed.

        NOTE: we'll use `volatile` here assuming that this is unlikely to become a performance bottleneck. If it becomes one we can probably just drop it and things still should work (despite warnings as per JMM regarding visibility (and lack thereof) of unguarded changes).

        Since:
        2.5

      • _asString

        protected final java.lang.String _asString
        We will retain representation of the pointer, as a String, so that toString() should be as efficient as possible.

      • _matchingPropertyName

        protected final java.lang.String _matchingPropertyName

      • _matchingElementIndex

        protected final int _matchingElementIndex

    • Constructor Detail

      • JsonPointer

        protected JsonPointer()
        Constructor used for creating "empty" instance, used to represent state that matches current node.

      • JsonPointer

        protected JsonPointer​(java.lang.String fullString,
                      java.lang.String segment,
                      JsonPointer next)

      • JsonPointer

        protected JsonPointer​(java.lang.String fullString,
                      java.lang.String segment,
                      int matchIndex,
                      JsonPointer next)

    • Method Detail

      • compile

        public static JsonPointer compile​(java.lang.String expr)
                           throws java.lang.IllegalArgumentException
        Factory method that parses given input and construct matching pointer instance, if it represents a valid JSON Pointer: if not, a IllegalArgumentException is thrown.
        Parameters:
        expr - Pointer expression to compile
        Returns:
        Compiled JsonPointer path expression
        Throws:
        java.lang.IllegalArgumentException - Thrown if the input does not present a valid JSON Pointer expression: currently the only such expression is one that does NOT start with a slash ('/').

      • valueOf

        public static JsonPointer valueOf​(java.lang.String expr)
        Alias for compile(java.lang.String); added to make instances automatically deserializable by Jackson databind.
        Parameters:
        expr - Pointer expression to compile
        Returns:
        Compiled JsonPointer path expression

      • empty

        public static JsonPointer empty()
        Accessor for an "empty" expression, that is, one you can get by calling compile(java.lang.String) with "" (empty String).

        NOTE: this is different from expression for "/" which would instead match Object node property with empty String ("") as name.

        Returns:
        "Empty" pointer expression instance that matches given root value
        Since:
        2.10

      • forPath

        public static JsonPointer forPath​(JsonStreamContext context,
                                  boolean includeRoot)
        Factory method that will construct a pointer instance that describes path to location given JsonStreamContext points to.
        Parameters:
        context - Context to build pointer expression for
        includeRoot - Whether to include number offset for virtual "root context" or not.
        Returns:
        JsonPointer path to location of given context
        Since:
        2.9

      • matches

        public boolean matches()

      • getMatchingProperty

        public java.lang.String getMatchingProperty()

      • getMatchingIndex

        public int getMatchingIndex()

      • mayMatchProperty

        public boolean mayMatchProperty()
        Returns:
        True if the root selector matches property name (that is, could match field value of JSON Object node)

      • mayMatchElement

        public boolean mayMatchElement()
        Returns:
        True if the root selector matches element index (that is, could match an element of JSON Array node)

      • last

        public JsonPointer last()
        Returns:
        the leaf of current JSON Pointer expression: leaf is the last non-null segment of current JSON Pointer.
        Since:
        2.5

      • append

        public JsonPointer append​(JsonPointer tail)
        Mutant factory method that will return
        • `tail` if `this` instance is "empty" pointer, OR
        • `this` instance if `tail` is "empty" pointer, OR
        • Newly constructed JsonPointer instance that starts with all segments of `this`, followed by all segments of `tail`.
        Parameters:
        tail - JsonPointer instance to append to this one, to create a new pointer instance
        Returns:
        Either `this` instance, `tail`, or a newly created combination, as per description above.

      • matchesProperty

        public boolean matchesProperty​(java.lang.String name)
        Method that may be called to see if the pointer head (first segment) would match property (of a JSON Object) with given name.
        Parameters:
        name - Name of Object property to match
        Returns:
        True if the pointer head matches specified property name
        Since:
        2.5

      • matchProperty

        public JsonPointer matchProperty​(java.lang.String name)
        Method that may be called to check whether the pointer head (first segment) matches specified Object property (by name) and if so, return JsonPointer that represents rest of the path after match. If there is no match, null is returned.
        Parameters:
        name - Name of Object property to match
        Returns:
        Remaining path after matching specified property, if there is match; null otherwise

      • matchesElement

        public boolean matchesElement​(int index)
        Method that may be called to see if the pointer would match Array element (of a JSON Array) with given index.
        Parameters:
        index - Index of Array element to match
        Returns:
        True if the pointer head matches specified Array index
        Since:
        2.5

      • matchElement

        public JsonPointer matchElement​(int index)
        Method that may be called to check whether the pointer head (first segment) matches specified Array index and if so, return JsonPointer that represents rest of the path after match. If there is no match, null is returned.
        Parameters:
        index - Index of Array element to match
        Returns:
        Remaining path after matching specified index, if there is match; null otherwise
        Since:
        2.6

      • tail

        public JsonPointer tail()
        Accessor for getting a "sub-pointer" (or sub-path), instance where current segment has been removed and pointer includes rest of the segments. For example, for JSON Pointer "/root/branch/leaf", this method would return pointer "/branch/leaf". For matching state (last segment), will return null.

        Note that this is a very cheap method to call as it simply returns "next" segment (which has been constructed when pointer instance was constructed).

        Returns:
        Tail of this pointer, if it has any; null if this pointer only has the current segment

      • head

        public JsonPointer head()
        Accessor for getting a pointer instance that is identical to this instance except that the last segment has been dropped. For example, for JSON Pointer "/root/branch/leaf", this method would return pointer "/root/branch" (compared to tail() that would return "/branch/leaf").

        Note that whereas tail() is a very cheap operation to call (as "tail" already exists for single-linked forward direction), this method has to fully construct a new instance by traversing the chain of segments.

        Returns:
        Pointer expression that contains same segments as this one, except for the last segment.
        Since:
        2.5

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • _parseTail

        protected static JsonPointer _parseTail​(java.lang.String input)

      • _parseQuotedTail

        protected static JsonPointer _parseQuotedTail​(java.lang.String input,
                                              int i)
        Method called to parse tail of pointer path, when a potentially escaped character has been seen.
        Parameters:
        input - Full input for the tail being parsed
        i - Offset to character after tilde
        Returns:
        Pointer instance constructed

      • _constructHead

        protected JsonPointer _constructHead()