Package com.fasterxml.jackson.core

Class JsonPointer

java.lang.Object
com.fasterxml.jackson.core.JsonPointer
All Implemented Interfaces:
Serializable
public class JsonPointer extends Object implements Serializable
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).

Note that the implementation was largely rewritten for Jackson 2.14 to reduce memory usage by sharing backing "full path" representation for nested instances.

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

Since:
2.3
See Also:

  • Field Details

    • ESC

      public static final char ESC
      Escape character '~' per RFC6901. 
       escaped         = "~" ( "0" / "1" )
  ; representing '~' and '/', respectively
      Since:
      2.17
      See Also:

    • ESC_SLASH

      public static final String ESC_SLASH
      Escaped slash string "~0" per RFC6901. 
       escaped         = "~" ( "0" / "1" )
  ; representing '~' and '/', respectively
      Since:
      2.17
      See Also:

    • ESC_TILDE

      public static final String ESC_TILDE
      Escaped tilde string "~0" per RFC6901. 
       escaped         = "~" ( "0" / "1" )
  ; representing '~' and '/', respectively
      Since:
      2.17
      See Also:

    • SEPARATOR

      public static final char SEPARATOR
      Character used to separate segments. 
       json-pointer    = *( "/" reference-token )
      Since:
      2.9
      See Also:

  • Method Details

    • compile

      public static JsonPointer compile(String expr) throws 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:
      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(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

    • length

      public int length()
      Functionally same as: toString().length() but more efficient as it avoids likely String allocation.
      Returns:
      Length of String representation of this pointer instance
      Since:
      2.14

    • matches

      public boolean matches()

    • getMatchingProperty

      public 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.

    • appendProperty

      public JsonPointer appendProperty(String property)
      ATTENTION! JsonPointer is head-centric, tail appending is much costlier than head appending. It is recommended that this method is used sparingly due to possible sub-par performance. Mutant factory method that will return:
      • `this` instance if `property` is null, OR
      • Newly constructed JsonPointer instance that starts with all segments of `this`, followed by new segment of 'property' name.
      'property' is name to match: value is escaped as necessary (for any contained slashes or tildes).

      NOTE! Before Jackson 2.17, no escaping was performed, and leading slash was dropped if passed. This was incorrect implementation. Empty property was also ignored (similar to null).

      Parameters:
      property - new segment property name
      Returns:
      Either `this` instance, or a newly created combination, as per description above.

    • appendIndex

      public JsonPointer appendIndex(int index)
      ATTENTION! JsonPointer is head-centric, tail appending is much costlier than head appending. It is recommended that this method is used sparingly due to possible sub-par performance. Mutant factory method that will return newly constructed JsonPointer instance that starts with all segments of `this`, followed by new segment of element 'index'. Element 'index' should be non-negative.
      Parameters:
      index - new segment element index
      Returns:
      Newly created combination, as per description above.
      Throws:
      IllegalArgumentException - if element index is negative

    • matchesProperty

      public boolean matchesProperty(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(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 String toString()
      Overrides:
      toString in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object