com.github.fge.jsonschema.ref

Class JsonRef

java.lang.Object

com.github.fge.jsonschema.ref.JsonRef

@Immutable
public abstract 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 differs from the JSON Reference draft in that it accepts to process illegal references, in the sense that they are URIs, but their fragment parts are not JSON Pointers (in which case isLegal() returns false.

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

• 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, as required by the draft;
• a reference is taken to be absolute if the underlying URI is absolute and it has no fragment, or an empty fragment.

It also special cases the following:

• an empty reference (for instance, used in anonymouns schemas);
• URIs with the jar scheme (the resolving algorithm differs -- please note that this breaks URI resolution rules).

Field Summary

Fields

Modifier and Type	Field and Description
protected static URI	HASHONLY_URI A "hash only" URI -- used by EmptyJsonRef
protected boolean	legal Whether this JSON Reference is legal
protected URI	locator The locator of this reference.
protected JsonPointer	pointer The pointer of this reference, if any
protected 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
protected	JsonRef(URI uri) Main constructor, protected 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	fromString(String s) Build a JSON Reference from a string input
static JsonRef	fromURI(URI uri) Build a JSON Reference from a URI
URI	getLocator() Return this JSON Reference's locator
JsonPointer	getPointer() Return the fragment part of this JSON Reference as a JSON Pointer
int	hashCode()
abstract boolean	isAbsolute() Tell whether this reference is an absolute reference
boolean	isLegal() Tell whether this JSON Reference is legal
abstract JsonRef	resolve(JsonRef other) Resolve this reference against another reference
String	toString()
URI	toURI() Return the underlying URI for this JSON Reference

Methods inherited from class java.lang.Object

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

Field Detail

HASHONLY_URI

protected static final URI HASHONLY_URI

A "hash only" URI -- used by EmptyJsonRef

legal

protected final boolean legal

Whether this JSON Reference is legal

uri

protected final URI uri

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

locator

protected final URI locator

The locator of this reference. This is the URI with an empty fragment part.

pointer

protected final JsonPointer pointer

The pointer of this reference, if any

Initialized to null if the fragment part is not a JSON Pointer.

See Also:

isLegal()

Constructor Detail

JsonRef

protected JsonRef(URI uri)

Main constructor, protected by design

Parameters:

uri - the URI to build that reference

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

fromString

public static JsonRef fromString(String s)
                          throws JsonReferenceException

Build a JSON Reference from a string input

Parameters:

s - the string

Returns:

the reference

Throws:

JsonReferenceException - string is not a valid URI

NullPointerException - provided string is null

emptyRef

public static JsonRef emptyRef()

Return an empty reference

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

Returns:

a statically allocated empty reference

toURI

public final URI toURI()

Return the underlying URI for this JSON Reference

Returns:

the URI

isAbsolute

public abstract boolean isAbsolute()

Tell whether this reference is an absolute reference

See description.

Returns:

true if the JSON Reference is absolute

resolve

public abstract JsonRef resolve(JsonRef other)

Resolve this reference against another reference

Parameters:

other - the reference to resolve

Returns:

the resolved reference

getLocator

public final URI getLocator()

Return this JSON Reference's locator

This returns the reference with an empty fragment, ie the URI of the document itself.

Returns:

an URI

isLegal

public final boolean isLegal()

Tell whether this JSON Reference is legal

Recall: it is legal if and only if its fragment part is a JSON pointer.

Returns:

true if legal

See Also:

JsonPointer

getPointer

public final JsonPointer getPointer()

Return the fragment part of this JSON Reference as a JSON Pointer

If the reference is not legal, this returns null without further notice, so beware!

Returns:

a JSON Pointer

See Also:

JsonPointer

contains

public final 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 final int hashCode()

Overrides:

hashCode in class Object

equals

public final boolean equals(Object obj)

Overrides:

equals in class Object

toString

public final String toString()

Overrides:

toString in class Object