JsonPointer (jackson-core 2.18.0-rc1)

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

Author:

Tatu Saloranta

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`protected String`	`_asString` We will retain representation of the pointer, as a String, so that `toString()` should be as efficient as possible.
`protected int`	`_asStringOffset`
`protected int`	`_hashCode` Lazily-calculated hash code: need to retain hash code now that we can no longer rely on `_asString` being the exact full representation (it is often "more", including parent path).
`protected JsonPointer`	`_head` Reference from currently matching segment (if any) to node before leaf.
`protected int`	`_matchingElementIndex`
`protected 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`	`ESC` Escape character 126 per RFC6901.
`static String`	`ESC_SLASH` Escaped slash string "~0" per RFC6901.
`static String`	`ESC_TILDE` Escaped tilde string "~0" per RFC6901.
`static char`	`SEPARATOR` Character used to separate segments.

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected JsonPointer`	`_constructHead()`
`protected JsonPointer`	`_constructHead(int suffixLength, JsonPointer last)`
`protected static int`	`_extractEscapedSegment(String input, int firstCharOffset, int i, StringBuilder sb)` Method called to extract the next segment of the path, in case where we seem to have encountered a (tilde-)escaped character within segment.
`protected static JsonPointer`	`_parseTail(String fullPath)`
`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`.
`JsonPointer`	`appendIndex(int index)` ATTENTION!
`JsonPointer`	`appendProperty(String property)` ATTENTION!
`static JsonPointer`	`compile(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(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()`
`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()`
`int`	`length()` Functionally same as: `toString().length()` but more efficient as it avoids likely String allocation.
`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(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(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.
`String`	`toString()`
`protected StringBuilder`	`toStringBuilder(int slack)` Functionally equivalent to: new StringBuilder(toString()); but possibly more efficient
`static JsonPointer`	`valueOf(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
  - ESC
```
public static final char ESC
```
    Escape character 126 per RFC6901.
```
 escaped         = "~" ( "0" / "1" )
  ; representing '~' and '/', respectively
 
```
    Since:
    
    2.17
    
    See Also:
    
    Constant Field Values
  - 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:
    
    Constant Field Values
  - 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:
    
    Constant Field Values
  - SEPARATOR
```
public static final char SEPARATOR
```
    Character used to separate segments.
```
 json-pointer    = *( "/" reference-token )
 
```
    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 String _asString
```
    We will retain representation of the pointer, as a String, so that toString() should be as efficient as possible.
    NOTE: starting with 2.14, there is no accompanying _asStringOffset that MUST be considered with this String; this String may contain preceding path, as it is now full path of parent pointer, except for the outermost pointer instance.
  - _asStringOffset
```
protected final int _asStringOffset
```
    Since:
    
    2.14
  - _matchingPropertyName
```
protected final String _matchingPropertyName
```
  - _matchingElementIndex
```
protected final int _matchingElementIndex
```
  - _hashCode
```
protected int _hashCode
```
    Lazily-calculated hash code: need to retain hash code now that we can no longer rely on _asString being the exact full representation (it is often "more", including parent path).
    
    Since:
    
    2.14
- Constructor Detail
  - JsonPointer
```
protected JsonPointer()
```
    Constructor used for creating "empty" instance, used to represent state that matches current node.
  - JsonPointer
```
protected JsonPointer(String fullString,
                      int fullStringOffset,
                      String segment,
                      JsonPointer next)
```
  - JsonPointer
```
protected JsonPointer(String fullString,
                      int fullStringOffset,
                      String segment,
                      int matchIndex,
                      JsonPointer next)
```
- Method Detail
  - 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
  - toStringBuilder
```
protected StringBuilder toStringBuilder(int slack)
```
    Functionally equivalent to:
```
   new StringBuilder(toString());
```
    but possibly more efficient
    Parameters:
    
    slack - Number of characters to reserve in StringBuilder beyond minimum copied
    
    Returns:
    
    a new StringBuilder
    
    Since:
    
    2.17
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - _parseTail
```
protected static JsonPointer _parseTail(String fullPath)
```
  - _extractEscapedSegment
```
protected static int _extractEscapedSegment(String input,
                                            int firstCharOffset,
                                            int i,
                                            StringBuilder sb)
```
    Method called to extract the next segment of the path, in case where we seem to have encountered a (tilde-)escaped character within segment.
    
    Parameters:
    
    input - Full input for the tail being parsed
    
    firstCharOffset - Offset of the first character of segment (one after slash)
    
    i - Offset to character after tilde
    
    sb - StringBuilder into which unquoted segment is added
    
    Returns:
    
    Offset at which slash was encountered, if any, or -1 if expression ended without seeing unescaped slash
  - _constructHead
```
protected JsonPointer _constructHead()
```
  - _constructHead
```
protected JsonPointer _constructHead(int suffixLength,
                                     JsonPointer last)
```

Class JsonPointer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ESC

ESC_SLASH

ESC_TILDE

SEPARATOR

EMPTY

_nextSegment

_head

_asString

_asStringOffset

_matchingPropertyName

_matchingElementIndex

_hashCode

Constructor Detail

JsonPointer

JsonPointer

JsonPointer

Method Detail

compile

valueOf

empty

forPath

length

matches

getMatchingProperty

getMatchingIndex

mayMatchProperty

mayMatchElement

last

append

appendProperty

appendIndex

matchesProperty

matchProperty

matchesElement

matchElement

tail

head

toString

toStringBuilder

hashCode

equals

_parseTail

_extractEscapedSegment

_constructHead

_constructHead