org.xwiki.model.reference

Class EntityReference

java.lang.Object

org.xwiki.model.reference.EntityReference

All Implemented Interfaces:

Serializable, Cloneable, Comparable<EntityReference>

Direct Known Subclasses:

AttachmentReference, BlockReference, ClassPropertyReference, DocumentReference, LocalDocumentReference, ObjectPropertyReference, ObjectReference, PartialEntityReference, SpaceReference, WikiReference

public class EntityReference
extends Object
implements Serializable, Cloneable, Comparable<EntityReference>

Represents a reference to an Entity (Document, Attachment, Space, Wiki, etc).

Since:

2.2M1

Version:

$Id: 403e222ca71785b5958595297a40e31814ef187a $

See Also:

Serialized Form

Field Summary

Fields

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

Constructor Summary

Constructors

Modifier	Constructor and Description
	EntityReference(EntityReference reference) Clone an EntityReference.
	EntityReference(EntityReference reference, EntityReference parent) Clone an EntityReference, but use the specified parent for its new parent.
protected	EntityReference(EntityReference reference, EntityReference oldReference, EntityReference newReference) Clone an EntityReference, but replace one of the parent in the chain by an other one.
	EntityReference(String name, EntityType type) Create a new root EntityReference.
	EntityReference(String name, EntityType type, EntityReference parent) Create a new EntityReference.
protected	EntityReference(String name, EntityType type, EntityReference parent, Map<String,Serializable> parameters) Create a new EntityReference.

Method Summary

Methods

Modifier and Type	Method and Description
EntityReference	appendParent(EntityReference newParent) Return a clone of this reference with a parent appended at the root of its parents chain.
int	compareTo(EntityReference reference) Note: The default implementation relies on comparing the string serialization of the 2 entities.
boolean	equals(EntityReference otherReference, EntityType to) Compared the two reference between the first reference and the last (including) to type of entity.
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.
boolean	equals(Object obj)
boolean	equalsNonRecursive(EntityReference otherReference) Same as equals(Object) but only the first level of the references (ignore parents).
EntityReference	extractFirstReference(EntityType type) Extract the first entity of the given type from this one by traversing the current entity to the root.
EntityReference	extractReference(EntityType type) Extract the last entity of the given type from this one by traversing the current entity to the root.
String	getName() Returns the name of this entity.
protected <T> T	getParameter(String name) Get the value of a parameter.
EntityReference	getParent()
List<EntityReference>	getReversedReferenceChain()
EntityReference	getRoot()
EntityType	getType() Returns the type of this entity.
int	hashCode()
boolean	hasParent(EntityReference expectedParent) Checks if a given reference is a parent of this reference.
EntityReference	removeParent(EntityReference oldParent) Return a clone of this reference truncated to a null parent when it reach the given parent.
EntityReference	replaceParent(EntityReference oldParent, EntityReference newParent) Return a clone of this reference, but with one of its parent replaced by another one.
protected void	setName(String name) Entity reference are immutable since 3.3M2, so this method is now protected.
protected void	setParameter(String name, Serializable value) Add or set a parameter value.
protected void	setParameters(Map<String,Serializable> parameters) Set multiple parameters at once.
protected void	setParent(EntityReference parent) Entity reference are immutable since 3.3M2, so this method is now protected.
protected void	setType(EntityType type) Entity reference are immutable since 3.3M2, so this method is now protected.
int	size()
String	toString()

Methods inherited from class java.lang.Object

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

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

protected 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

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

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

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

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

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

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)