com.github.fge.jsonschema.ref

Class JsonRef

java.lang.Object

com.github.fge.jsonschema.ref.JsonRef

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 one important way: normally, the fragment part of a JSON Reference must be a JSON Pointer; however, this means you cannot use a reference for addressing inner schemas when inline addressing mode is used. We therefore choose to accept all possible fragment parts.

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.

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).

This class is thread safe and immutable.

See Also:

AddressingMode.INLINE, InlineSchemaContainer

Field Summary

Fields

Modifier and Type	Field and Description
protected JsonFragment	fragment The fragment of this reference.
protected static URI	HASHONLY_URI
protected URI	locator The locator of this reference.
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
JsonFragment	getFragment() Return this JSON Reference's fragment
URI	getLocator() Return this JSON Reference's locator
int	hashCode()
abstract boolean	isAbsolute() Tell whether this reference is an absolute reference
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

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.

fragment

protected final JsonFragment fragment

The fragment of this reference.

See Also:

JsonFragment

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 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

emptyRef

public static JsonRef emptyRef()

Return an empty reference

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

Returns:

see above

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

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 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.

Returns:

an URI

getFragment

public final JsonFragment getFragment()

Return this JSON Reference's fragment

Returns:

the fragment

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