Class JsonPointer
- java.lang.Object
-
- com.fasterxml.jackson.core.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 (seeTreeNode.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 thattoString()
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 formatches()
).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 constructedJsonPointer
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, aIllegalArgumentException
is thrown.static JsonPointer
empty()
Accessor for an "empty" expression, that is, one you can get by callingcompile(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 givenJsonStreamContext
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, returnJsonPointer
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, returnJsonPointer
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 forcompile(java.lang.String)
; added to make instances automatically deserializable by Jackson databind.
-
-
-
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 formatches()
).
-
_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 thattoString()
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, aIllegalArgumentException
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 forcompile(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 callingcompile(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 givenJsonStreamContext
points to.- Parameters:
context
- Context to build pointer expression forincludeRoot
- 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, returnJsonPointer
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, returnJsonPointer
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 returnnull
.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 totail()
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 classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.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 parsedi
- Offset to character after tilde- Returns:
- Pointer instance constructed
-
_constructHead
protected JsonPointer _constructHead()
-
_constructHead
protected JsonPointer _constructHead(int suffixLength, JsonPointer last)
-
-