com.fasterxml.jackson.core

Class JsonPointer

java.lang.Object

com.fasterxml.jackson.core.JsonPointer

public class JsonPointer
extends 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 shared, cached.

Since:

2.3

Author:

Tatu Saloranta

Property Summary

Properties

Type	Property and Description
boolean	mayMatch

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 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()).

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, String segment, int matchIndex, JsonPointer next)
protected	JsonPointer(String fullString, String segment, JsonPointer next) Constructor used for creating non-empty Segments

Method Summary

Methods

Modifier and Type	Method and Description
protected JsonPointer	_constructHead()
protected JsonPointer	_constructHead(int suffixLength, JsonPointer last)
protected static JsonPointer	_parseQuotedTail(String input, int i) Method called to parse tail of pointer path, when a potentially escaped character has been seen.
protected static JsonPointer	_parseTail(String input)
JsonPointer	append(JsonPointer tail)
static JsonPointer	compile(String input) Factory method that parses given input and construct matching pointer instance, if it represents a valid JSON Pointer: if not, a IllegalArgumentException is thrown.
boolean	equals(Object o)
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() Returns the leaf of current JSON Pointer expression.
JsonPointer	matchElement(int index)
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 would match property (of a JSON Object) with given name.
JsonPointer	matchProperty(String name)
boolean	mayMatchElement()
boolean	mayMatchProperty()
JsonPointer	tail() Accessor for getting a "sub-pointer", instance where current segment has been removed and pointer includes rest of segments.
String	toString()
static JsonPointer	valueOf(String input) 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

Property Detail

mayMatch

Field Detail

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.

_matchingPropertyName

protected final 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(String fullString,
           String segment,
           JsonPointer next)

Constructor used for creating non-empty Segments

JsonPointer

protected JsonPointer(String fullString,
           String segment,
           int matchIndex,
           JsonPointer next)

Since:

2.5

Method Detail

compile

public static JsonPointer compile(String input)
                           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.

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 input)

Alias for compile(java.lang.String); added to make instances automatically deserializable by Jackson databind.

matches

public boolean matches()

getMatchingProperty

public String getMatchingProperty()

getMatchingIndex

public int getMatchingIndex()

mayMatchProperty

public boolean mayMatchProperty()

mayMatchElement

public boolean mayMatchElement()

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)

matchesProperty

public boolean matchesProperty(String name)

Method that may be called to see if the pointer would match property (of a JSON Object) with given name.

Since:

2.5

matchProperty

public JsonPointer matchProperty(String name)

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.

Since:

2.5

matchElement

public JsonPointer matchElement(int index)

Since:

2.6

tail

public JsonPointer tail()

Accessor for getting a "sub-pointer", instance where current segment has been removed and pointer includes rest of segments. For matching state, will return null.

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 Point "/root/branch/leaf", this method would return pointer "/root/branch" (compared to tail() that would return "/branch/leaf"). For leaf

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

_parseTail

protected static JsonPointer _parseTail(String input)

_parseQuotedTail

protected static JsonPointer _parseQuotedTail(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

_constructHead

protected JsonPointer _constructHead()

_constructHead

protected JsonPointer _constructHead(int suffixLength,
                         JsonPointer last)