Package org.xwiki.model.reference

Class EntityReference

    • Field Detail

      • TOSTRING_SERIALIZER

        protected static final org.xwiki.model.internal.reference.LocalizedStringEntityReferenceSerializer TOSTRING_SERIALIZER
        Used to provide a nice and readable pretty name for the toString() method.

    • Constructor Detail

      • EntityReference

        public EntityReference​(EntityReference reference)
        Clone an EntityReference.
        Parameters:
        reference - the reference to clone
        Since:
        3.3M2

      • EntityReference

        public EntityReference​(EntityReference reference,
                       EntityReference parent)
        Clone an EntityReference, but use the specified parent for its new parent.
        Parameters:
        reference - the reference to clone
        parent - the new parent to use
        Since:
        3.3M2

      • EntityReference

        protected EntityReference​(EntityReference reference,
                          EntityReference oldReference,
                          EntityReference newReference)
        Clone an EntityReference, but replace one of the parent in the chain by an other one.
        Parameters:
        reference - the reference that is cloned
        oldReference - the old parent that will be replaced
        newReference - the new parent that will replace oldReference in the chain
        Since:
        3.3M2

      • EntityReference

        public EntityReference​(String name,
                       EntityType type)
        Create a new root EntityReference. Note: Entity reference are immutable since 3.3M2.
        Parameters:
        name - name for the newly created entity reference, could not be null.
        type - type for the newly created entity reference, could not be null.

      • EntityReference

        public EntityReference​(String name,
                       EntityType type,
                       EntityReference parent)
        Create a new EntityReference. Note: Entity reference are immutable since 3.3M2.
        Parameters:
        name - name for the newly created entity reference, could not be null.
        type - type for the newly created entity reference, could not be null.
        parent - parent reference for the newly created entity reference, may be null.

      • EntityReference

        public EntityReference​(String name,
                       EntityType type,
                       Map<String,​Serializable> parameters)
        Create a new EntityReference. Note: Entity reference are immutable since 3.3M2.
        Parameters:
        name - name for the newly created entity, could not be null.
        type - type for the newly created entity, could not be null.
        parameters - parameters for this reference, may be null
        Since:
        10.6RC1

      • EntityReference

        public EntityReference​(String name,
                       EntityType type,
                       EntityReference parent,
                       Map<String,​Serializable> parameters)
        Create a new EntityReference. Note: Entity reference are immutable since 3.3M2.
        Parameters:
        name - name for the newly created entity, could not be null.
        type - type for the newly created entity, could not be null.
        parent - parent reference for the newly created entity reference, may be null.
        parameters - parameters for this reference, may be null
        Since:
        3.3M2

      • EntityReference

        public EntityReference​(EntityReference reference,
                       Map<String,​Serializable> parameters)
        Clone an EntityReference, but use the specified paramaters.
        Parameters:
        reference - the reference to clone
        parameters - parameters for this reference, may be null
        Since:
        10.6RC1

    • Method Detail

      • setName

        protected void setName​(String name)
        Entity reference are immutable since 3.3M2, so this method is now protected.
        Parameters:
        name - the name for this entity
        Throws:
        IllegalArgumentException - if the passed name is null or empty

      • getName

        public final String getName()
        Returns the name of this entity. This method is final to ensure that name is never null and we use the private field in all other methods of this implementation (faster).
        Returns:
        the name of this entity.

      • setParent

        protected void setParent​(EntityReference parent)
        Entity reference are immutable since 3.3M2, so this method is now protected.
        Parameters:
        parent - the parent for this entity, may be null for a root entity.

      • getParent

        public final EntityReference getParent()
        Returns:
        the parent of this entity, may be null for a root entity.

      • setType

        protected void setType​(EntityType type)
        Entity reference are immutable since 3.3M2, so this method is now protected.
        Parameters:
        type - the type for this entity
        Throws:
        IllegalArgumentException - if the passed type is null

      • getType

        public final EntityType getType()
        Returns the type of this entity. This method is final to ensure that type is never null and we use the private field in all other methods of this implementation (faster).
        Returns:
        the type of this entity

      • setParameters

        protected void setParameters​(Map<String,​Serializable> parameters)
        Set multiple parameters at once.
        Parameters:
        parameters - the map of parameter to set
        Since:
        3.3M2

      • setParameter

        protected void setParameter​(String name,
                            Serializable value)
        Add or set a parameter value. Parameters should be immutable objects to prevent any weird behavior.
        Parameters:
        name - the name of the parameter
        value - the value of the parameter
        Since:
        3.3M2

      • getParameter

        protected final <T> T getParameter​(String name)
        Get the value of a parameter. Return null if the parameter is not set. This method is final so there is no way to override the map, and the private field in all other methods of this implementation (faster).
        Type Parameters:
        T - the type of the value of the requested parameter
        Parameters:
        name - the name of the parameter to get
        Returns:
        the value of the parameter
        Since:
        3.3M2

      • getParameters

        public final Map<String,​Serializable> getParameters()
        Get the parameters. This method is final so there is no way to override the map, and the private field in all other methods of this implementation (faster).
        Returns:
        the value of the parameter
        Since:
        5.3RC1

      • getRoot

        public EntityReference getRoot()
        Returns:
        the root parent of this entity

      • getReversedReferenceChain

        public List<EntityReference> getReversedReferenceChain()
        Returns:
        a list of references in the parents chain of this reference, ordered from root to this reference.

      • size

        public int size()
        Returns:
        the number of elements in the EntityReference
        Since:
        7.2M1

      • extractReference

        public EntityReference extractReference​(EntityType type)
        Extract the last entity of the given type from this one by traversing the current entity to the root.
        Parameters:
        type - the type of the entity to be extracted
        Returns:
        the last entity of the given type in the current entity when traversing to the root (the current entity will be returned if it's of the passed type) or null if no entity of the passed type exist

      • extractFirstReference

        public EntityReference extractFirstReference​(EntityType type)
        Extract the first entity of the given type from this one by traversing the current entity to the root.
        Parameters:
        type - the type of the entity to be extracted
        Returns:
        the first entity of the given type in the current entity when traversing to the root or null if no entity of the passed type exist
        Since:
        7.4M1

      • replaceParent

        public EntityReference replaceParent​(EntityReference oldParent,
                                     EntityReference newParent)
        Return a clone of this reference, but with one of its parent replaced by another one.
        Parameters:
        oldParent - the old parent that will be replaced
        newParent - the new parent that will replace oldParent in the chain. If the same as oldParent, this is returned.
        Returns:
        a new reference with a amended parent chain
        Since:
        3.3M2

      • replaceParent

        public EntityReference replaceParent​(EntityReference newParent)
        Return a clone of this reference, but with its parent replaced by the passed one.
        Parameters:
        newParent - the new parent that will replace the parent
        Returns:
        a new reference with a amended parent chain
        Since:
        10.8RC1

      • appendParent

        public EntityReference appendParent​(EntityReference newParent)
        Return a clone of this reference with a parent appended at the root of its parents chain.
        Parameters:
        newParent - the parent that became the root parent of this reference (and its parent). If null, this is returned.
        Returns:
        a new reference with newParent added to its parent chain

      • removeParent

        public EntityReference removeParent​(EntityReference oldParent)
        Return a clone of this reference truncated to a null parent when it reach the given parent. It is very similar to replaceParent(parent, null), except that it is not overridden.
        Parameters:
        oldParent - the parent that will be replaced by a null. If null, this is returned.
        Returns:
        a new reference with oldParent and its descendant removed from its parent chain
        Since:
        4.0M2

      • hasParent

        public boolean hasParent​(EntityReference expectedParent)
        Checks if a given reference is a parent of this reference.
        Parameters:
        expectedParent - the parent reference to check
        Returns:
        true if the given reference is a parent of this reference, false otherwise
        Since:
        7.3RC1

      • equals

        public boolean equals​(EntityReference otherReference,
                      EntityType to)
        Compared the two reference between the first reference and the last (including) to type of entity.

        For example if you want to make sure some local document matches some complete document reference you can so it with localDocumentReference.equals(documentReference, EntityType.SPACE).

        Parameters:
        otherReference - the reference to compare
        to - the type of the the last (including) entity reference to compare
        Returns:
        true if the two references are equals between the passes entity types references
        Since:
        7.2M1

      • equals

        public boolean equals​(EntityReference otherReference,
                      EntityType from,
                      EntityType to)
        Compared the two reference between the first (including) from type of entity and the last (including) to type of entity.
        Parameters:
        otherReference - the reference to compare
        from - the type of the first (including) entity reference to compare
        to - the type of the the last (including) entity reference to compare
        Returns:
        true if the two references are equals between the passes entity types references
        Since:
        7.2M1

      • equalsNonRecursive

        public boolean equalsNonRecursive​(EntityReference otherReference)
        Same as equals(Object) but only the first level of the references (ignore parents).
        Parameters:
        otherReference - the reference to compare
        Returns:
        true if the two references are equals
        Since:
        7.2M1

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • compareTo

        public int compareTo​(EntityReference reference)

        Note: The default implementation relies on comparing the string serialization of the 2 entities. It is the caller's responsibility to make sure that the entities are either first resolved or at least of the same type, in order for the comparison to actually make sense.

        Specified by:
        compareTo in interface Comparable<EntityReference>
        See Also:
        Comparable.compareTo(java.lang.Object)