com.atlassian.confluence.api.model.reference

Class Reference<T>

java.lang.Object

com.atlassian.confluence.api.model.reference.Reference<T>

Type Parameters:

T - - the type of the Referent object

All Implemented Interfaces:

Iterable<T>

Direct Known Subclasses:

ExpandedReference

@ExperimentalApi
public abstract class Reference<T>
extends Object
implements Iterable<T>

A reference to a model object. References can be either expanded or collapsed. The object that a reference points to can either exist or not. If a reference both exists and is expanded then call to get() will return the referenced object. Collapsed References provide id properties that give just enough information to identify the referenced object.

Model object that wish to be able to have references generated for them need to provide an enum named IdProperties. This enum must have values that match the name of the fields in the object that comprise it's ID.

Constructor Summary

Constructors

Constructor and Description
Reference() Deprecated. since 5.6 use @{link Reference#Reference(boolean)}

Method Summary

Modifier and Type	Method and Description
static <T> Reference<T>	collapsed(Class<T> objClass)
static <T> Reference<T>	collapsed(Class<T> objClass, Map idProperties)
static <T> Reference<T>	collapsed(T obj) Create a collapse reference to the given object.
static <T> Reference<T>	empty(Class<T> referrentClass) Create an empty reference to the given class.
boolean	equals(Object o)
abstract boolean	exists()
boolean	existsAndExpanded()
abstract T	get()
abstract Map<Object,Object>	getIdProperties() A map of properties key by the idProperty enum in the model class for the referent object.
Object	getIdProperty(Enum key)
int	hashCode()
abstract boolean	isExpanded() indicates a reference is expanded and can be resolved to an object by calling get, or whether the reference is collapsed and calling get will throw an exception.
static <T> Reference<T>	orEmpty(Reference<T> reference, Class<T> referentClass)
static <T> Reference<T>	orEmpty(T entity, Class<T> referentClass)
abstract Class<? extends T>	referentClass()
static <T> Reference<T>	to(T value) Create an expanded reference to the referent value.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Constructor Detail

Reference

@Deprecated
public Reference()

Deprecated. since 5.6 use @{link Reference#Reference(boolean)}

This constructor still exists to allow the api build to pass, even though this class is abstract and use of this constructor would imply treating this class as an SPI.

Method Detail

get

public abstract T get()
               throws IllegalStateException

Returns:

the reference object or null if the object does not exist. It is Illegal to call get() on a reference that has not been expanded

Throws:

IllegalStateException

exists

public abstract boolean exists()

Returns:

true if the object is expanded and exists, or is collapsed and has enough information to identify itself, false if the object does not exist (is empty)

isExpanded

public abstract boolean isExpanded()

indicates a reference is expanded and can be resolved to an object by calling get, or whether the reference is collapsed and calling get will throw an exception.

Returns:

true if the reference is expanded, false otherwise

getIdProperties

public abstract Map<Object,Object> getIdProperties()

A map of properties key by the idProperty enum in the model class for the referent object. The map contains properties sufficient to identify the referent object.

Returns:

a map of id properties keyed by idProperty enum

getIdProperty

public Object getIdProperty(Enum key)

existsAndExpanded

public boolean existsAndExpanded()

referentClass

public abstract Class<? extends T> referentClass()

Returns:

the class of the referent object.

empty

public static <T> Reference<T> empty(Class<T> referrentClass)

Create an empty reference to the given class.

Type Parameters:

T - the type to create a reference to

Parameters:

referrentClass - the class of type of object to create a reference to.

Returns:

the new reference

orEmpty

public static <T> Reference<T> orEmpty(Reference<T> reference,
                                       Class<T> referentClass)

Parameters:

reference - - the reference to return if it exists

referentClass - - the class to create an empty reference to if reference doesn't exist

Returns:

the reference parameter or an empty reference if the reference is null or does not exist

orEmpty

public static <T> Reference<T> orEmpty(T entity,
                                       Class<T> referentClass)

collapsed

public static <T> Reference<T> collapsed(T obj)

Create a collapse reference to the given object. A collapsed object cannot have it's value dereferenced and calls to get() will throw an exception. It does have it's id properties recorded so it can be looked up.

Parameters:

obj - - the object to create a collapsed reference to

Returns:

a collapsed reference to the object

collapsed

public static <T> Reference<T> collapsed(Class<T> objClass)

collapsed

public static <T> Reference<T> collapsed(Class<T> objClass,
                                         Map idProperties)

to

public static <T> Reference<T> to(T value)

Create an expanded reference to the referent value. An expanded reference exists and can be dereferenced to the value parameter

Parameters:

value - - the object to create a reference to

Returns:

an expanded reference to the value.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object