public final class JsonPointer extends JsonFragment implements Comparable<JsonPointer>
JSON Pointer is a draft standard defining a way to address paths within JSON documents. Paths apply to container objects, ie arrays or nodes. For objects, path elements are property names. For arrays, they are the index in the array.
The general syntax is #/path/elements/here. A path element is
referred to as a "reference token" in the specification.
JSON Pointers are always absolute: it is perfectly legal, for
instance, to have properties named . and .. in a JSON
object.
Even / is a valid property name. For this reason,
the caret (^) has been chosen as an escape character, but only if
followed by itself or /. Therefore:
^/ becomes /,^^ becomes ^,^<anythingelse> is illegal.There are two pending traps with JSON Pointer which one must be aware of:
The initial input string MAY be JSON escaped (FIXME: pointer to spec)
; it means that, for instance,"#\/" and "#/" are the same string, since the first
version is "merely" the JSON escaped version of the first.The empty string is a valid property name in a JSON
object, which means # and #/ are different. The second
refers to property "" inside an object while the first refers
to the JSON document itself. Implied: implementations must handle
the case where the document is not an object (leading to a
"dangling" JSON Pointer).
Fortunately, Jackson makes both points easy to handle.
Final note: please note that all instances of this class are immutable.
| Modifier and Type | Field and Description |
|---|---|
private static CharMatcher |
CARET |
private List<String> |
elements
The list of individual elements in the pointer.
|
private String |
fullPointer
The pointer in a raw, but JSON Pointer-escaped, string.
|
private static CharMatcher |
SLASH |
private static CharMatcher |
SPECIAL |
| Modifier | Constructor and Description |
|---|---|
|
JsonPointer(String input)
Constructor
|
private |
JsonPointer(String fullPointer,
List<String> elements) |
| Modifier and Type | Method and Description |
|---|---|
JsonPointer |
append(int index)
Append an array index to this pointer.
|
JsonPointer |
append(String element)
Append a path element to this pointer.
|
int |
compareTo(JsonPointer other) |
boolean |
equals(Object obj) |
List<String> |
getElements()
Return the reference tokens of this JSON Pointer, in order.
|
private static String |
getNextRefToken(String input)
Grab a (cooked) reference token from an input string
|
int |
hashCode() |
private static void |
process(String input,
ImmutableList.Builder<String> builder)
Initialize the object -- FIXME: misnamed
|
private static String |
refTokenDecode(String cooked)
Turn a cooked reference token into a raw reference token
|
private static String |
refTokenEncode(String raw)
Make a cooked reference token out of a raw element token
|
JsonNode |
resolve(JsonNode node)
Resolve this fragment against a given node
|
String |
toString() |
fromFragment, isEmptyprivate static final CharMatcher SPECIAL
private static final CharMatcher SLASH
private static final CharMatcher CARET
private final String fullPointer
public JsonPointer(String input) throws JsonSchemaException
FIXME: unclear whether we should only accept #-prefixed inputs, therefore both are accepted
input - The input string, guaranteed not to be JSON encodedJsonSchemaException - Illegal JSON Pointerpublic List<String> getElements()
Listpublic JsonPointer append(String element)
element - the element to appendpublic JsonPointer append(int index)
Note that the index validity is NOT checked for (ie,
you can append -1 if you want to -- don't do that)
index - the index to addpublic JsonNode resolve(JsonNode node)
JsonFragmentresolve in class JsonFragmentnode - the nodeMissingNode if the fragment is not
found)private static void process(String input, ImmutableList.Builder<String> builder) throws JsonSchemaException
We read the string sequentially, a slash, then a reference token, then a slash, etc. Bail out if the string is malformed.
input - Input string, guaranteed not to be JSON encodedbuilder - the list builderJsonSchemaException - the input is not a valid JSON Pointerprivate static String getNextRefToken(String input) throws JsonSchemaException
This method is only called from
process(String, ImmutableList.Builder), after a delimiter
(/) has been swallowed up. The input string is therefore
guaranteed to start with a reference token, which may be empty.
input - the input stringJsonSchemaException - the string is malformedprivate static String refTokenDecode(String cooked)
This means unescaping all slashes and carets. This function MUST be called with a valid cooked reference token.
It is called from process(String, ImmutableList.Builder),
in order to push a token into elements.
cooked - the cooked tokenprivate static String refTokenEncode(String raw)
Used to build new pointer instances when called from (String) or append(int), in order to build fullPointer.
raw - the raw tokenpublic int compareTo(JsonPointer other)
compareTo in interface Comparable<JsonPointer>public String toString()
toString in class JsonFragmentCopyright © 2012. All Rights Reserved.