org.xwiki.model.reference
Class EntityReference

java.lang.Object
  extended by org.xwiki.model.reference.EntityReference
All Implemented Interfaces:
Serializable, Cloneable, Comparable<EntityReference>
Direct Known Subclasses:
AttachmentReference, ClassPropertyReference, DocumentReference, ObjectPropertyReference, ObjectReference, RegexEntityReference, SecurityReference, 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
See Also:
Serialized Form

Field Summary
protected static 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 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>