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, 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: 2549da5be34d5d89493fcaf8e2aa6f5ee863039c $

See Also:

Serialized Form

Field Summary

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

	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

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)
boolean	equals(Object obj)
EntityReference	extractReference(EntityType type) Extract the entity of the given type from this one.
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()
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.
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.

extractReference

public EntityReference extractReference(EntityType type)

Extract the entity of the given type from this one. This entity may be returned if it has the type requested.

Parameters:

type - the type of the entity to be extracted

Returns:

the entity of the given type

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

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(EntityReference reference)

Specified by:

compareTo in interface Comparable<EntityReference>