org.eel.kitchen.util
Class JsonPointer

java.lang.Object
  org.eel.kitchen.util.JsonPointer

public final class JsonPointer
extends Object

Implementation of IETF JSON Pointer draft, version 1

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.

Field Summary

static JsonPointer

ROOT

Constructor Summary

JsonPointer(String input)
Constructor

Method Summary

JsonPointer	append(int index) Append an array index to this pointer.
JsonPointer	append(String element) Append a path element to this pointer.
boolean	equals(Object obj)
List<String>	getElements() Return the reference tokens of this JSON Pointer, in order.
JsonNode	getPath(JsonNode node) Resolve this JSON Pointer against a JSON instance
int	hashCode()
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROOT

public static final JsonPointer ROOT

Constructor Detail

JsonPointer

public JsonPointer(String input)
            throws JsonSchemaException

Constructor

FIXME: unclear whether we should only accept #-prefixed inputs, therefore both are accepted

Parameters:

input - The input string, guaranteed not to be JSON encoded

Throws:

JsonSchemaException - Illegal JSON Pointer

Method Detail

getElements

public List<String> getElements()

Return the reference tokens of this JSON Pointer, in order.

Returns:

a List

append

public JsonPointer append(String element)

Append a path element to this pointer. Returns a new instance.

Parameters:

element - the element to append

Returns:

a new instance with the element appended

append

public JsonPointer append(int index)

Append an array index to this pointer. Returns a new instance.

Note that the index validity is NOT checked for (ie, you can append -1 if you want to -- don't do that)

Parameters:

index - the index to add

Returns:

a new instance with the index appended

getPath

public JsonNode getPath(JsonNode node)

Resolve this JSON Pointer against a JSON instance

Parameters:

node - the node to resolve against

Returns:

the result document, which may be a MissingNode

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object