Package com.atlassian.confluence.api.model.reference

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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object