org.eel.kitchen.jsonschema.ref

Class JsonRef

java.lang.Object

org.eel.kitchen.jsonschema.ref.JsonRef

public final class JsonRef
extends Object

Representation of a JSON Reference

JSON Reference, currently a draft, is a way to define a path within a JSON document.

To quote the draft, "A JSON Reference is a JSON object, which contains a member named "$ref", which has a JSON string value." This string value must be a URI. Example:

     {
         "$ref": "http://example.com/example.json#/foo/bar"
     }
 

This class is used in a more general way than the draft. It is also used as a backing class for schema identifiers.

The implementation is a wrapper over Java's URI, with the following differences:

• all URIs are normalized from the get go;
• an empty fragment is equivalent to no fragment at all, and stands for a root JSON Pointer;
• a reference is taken to be absolute if the underlying URI is absolute and it has no fragment, or an empty fragment.

This class is thread safe and immutable.

Field Summary

Fields

Modifier and Type	Field and Description
private static JsonRef	EMPTY An empty JSON Reference
private static URI	EMPTY_URI Empty URI
private JsonFragment	fragment The fragment of this JSON Reference
private int	hashCode
private static URI	HASHONLY_URI URI with only an empty fragment part
private URI	locator The locator for this fragment
private URI	uri The URI, as provided by the input, with an appended empty fragment if no fragment was provided

Constructor Summary

Constructors

Modifier	Constructor and Description
private	JsonRef(URI uri) The main constructor, which is private by design

Method Summary

Methods

Modifier and Type	Method and Description
boolean	contains(JsonRef other) Tell whether the current JSON Reference contains another
static JsonRef	emptyRef() Return an empty reference
boolean	equals(Object obj)
static JsonRef	fromNode(JsonNode node) Build a JSON Reference from a JsonNode
static JsonRef	fromString(String s) Build a JSON Reference from a string input
static JsonRef	fromURI(URI uri) Build a JSON Reference from a URI
JsonFragment	getFragment() Return this JSON Reference's fragment
URI	getRootAsURI() Return this JSON Reference's locator
int	hashCode()
boolean	isAbsolute() Tell whether this reference is an absolute reference
JsonRef	resolve(JsonRef other) Resolve this reference against another reference
private URI	resolveJarURI(JsonRef other) Resolve a relative reference against a jar URI
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

HASHONLY_URI

private static final URI HASHONLY_URI

URI with only an empty fragment part

EMPTY_URI

private static final URI EMPTY_URI

Empty URI

EMPTY

private static final JsonRef EMPTY

An empty JSON Reference

uri

private final URI uri

The URI, as provided by the input, with an appended empty fragment if no fragment was provided

locator

private final URI locator

The locator for this fragment

fragment

private final JsonFragment fragment

The fragment of this JSON Reference

hashCode

private final int hashCode

Constructor Detail

JsonRef

private JsonRef(URI uri)

The main constructor, which is private by design

If the provided URI has no fragment, then an empty one is appended.

Parameters:

uri - Input URI

Method Detail

fromURI

public static JsonRef fromURI(URI uri)

Build a JSON Reference from a URI

Parameters:

uri - the provided URI

Returns:

the JSON Reference

Throws:

NullPointerException - the provided URI is null

See Also:

JsonRef(URI)

fromString

public static JsonRef fromString(String s)
                          throws JsonSchemaException

Build a JSON Reference from a string input

Parameters:

s - the string

Returns:

the reference

Throws:

JsonSchemaException - string is not a valid URI

NullPointerException - provided string is null

fromNode

public static JsonRef fromNode(JsonNode node)
                        throws JsonSchemaException

Build a JSON Reference from a JsonNode

If the node is not textual, this returns an empty reference. Otherwise, it calls fromString(String) with this node's text value.

Parameters:

node - the node

Returns:

the reference

Throws:

JsonSchemaException - see fromString(String)

NullPointerException - provided node is null

emptyRef

public static JsonRef emptyRef()

Return an empty reference

An empty reference is a reference which only has an empty fragment.

Returns:

see above

isAbsolute

public boolean isAbsolute()

Tell whether this reference is an absolute reference

A JSON Reference is considered absolute iif the underlying URI is itself absolute and it has an empty, or no, fragment part.

Returns:

see above

resolve

public JsonRef resolve(JsonRef other)

Resolve this reference against another reference

Note: jar URIs need to be special cased, see resolveJarURI(JsonRef).

Parameters:

other - the reference to resolve

Returns:

the resolved reference

getRootAsURI

public URI getRootAsURI()

Return this JSON Reference's locator

The locator of a fragment is the URI with an empty fragment.

Returns:

an URI

getFragment

public JsonFragment getFragment()

Return this JSON Reference's fragment

Returns:

the fragment

contains

public boolean contains(JsonRef other)

Tell whether the current JSON Reference contains another

This is considered true iif both references have the same locator, in other words, if they differ only by their fragment part.

Parameters:

other - the other reference

Returns:

see above

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object

resolveJarURI

private URI resolveJarURI(JsonRef other)

Resolve a relative reference against a jar URI

Unfortunately, URI.resolve(URI) does not work for these, because of the way JAR URIs are built. An example JAR URI is:

     jar:file:/path/to/my.jar!/jar/entry.json#fragmentHere
 

As per URI rules, this URI has no host and no path, just a "scheme specific part" containing everyting after the scheme. Which means that using .resolve(x) on such a URI for whatever URI x will return... Yes, x. This is how URI resolution is supposed to work.

We therefore handle these specially in this method:

• we are guaranteed that if we enter here, the other URI is relative: it has no scheme part, it is therefore a path followed by a fragment (if any);
• we therefore extract whatever is after the ! (we are guaranteed that there is one: we cannot enter this whole class if the URI did not resolve successfully in the first place), make a URI out of it and use classic URI resolution rules to resolve that extracted path against the other URI;
• we then rebuild the URI with this new path.

This means that, for instance, resolving ../x.json# against the URI above will lead to jar:file:/path/to/my.jar!/x.json#.

Sick. That's the price to pay for supporting the jar scheme in the first place :(

Parameters:

other - the URI to resolve against

Returns:

the newly, specially crafted URI