org.sakaiproject.entitybroker
Class EntityReference

java.lang.Object
  org.sakaiproject.entitybroker.EntityReference

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

IdEntityReference

public class EntityReference
extends Object
implements Cloneable, Serializable

The class of all Entity references handled by the EntityBroker system. This provides the entity prefix, which uniquely identifies the EntityProvider responsible for handling the Entity. It optionally provides the entity id which uniquely identifies an entity locally within the prefix space. It also provides for all parsing methods for entity references (always of the form /prefix or /prefix/id)

Author:

Aaron Zeckoski (aaronz@vt.edu)

See Also:

Serialized Form

Field Summary

protected String	originalReference
static char	PERIOD
String	prefix An entity prefix, should match with the prefix handled in an EntityProvider, uniquely identifies an entity space or entity type WARNING: use the getPrefix() method rather than referring to this directly
static char	SEPARATOR
static long	serialVersionUID

Constructor Summary

EntityReference()

EntityReference(String reference)
Constructor which takes an entity reference, this is the most common way to construct an entity reference object

EntityReference(String prefix, String id)
Convenience constructor for when you know the prefix and/or id

Method Summary

protected static void	checkPrefixId(String prefix, String id) Checks this prefix and id to see if they are valid format, throw exceptions if they aren't
protected static void	checkReference(String reference) Check if a reference is basically valid
protected Object	clone()
EntityReference	copy()
static EntityReference	copy(EntityReference ref) Creates a copy of an entity reference
protected static String	findId(String reference) Get the local entity id based on a full entity reference
protected static String	findPrefix(String reference) Get the entity prefix based on an entity reference
String	getId() A local entity id, represents an entity uniquely in a tool/webapp, could match with the actual id of a model data object, this will be null if this reference refers to an entity space only
static String	getIdFromRef(String reference) Will convert a reference into an id (even if it is not a reference)
static String	getIdFromRefByKey(String reference, String key) Get the id value out of a reference by the key that preceeds it
String	getOriginalReference() This is a special method and should not normally be used, use toString() or getReference()
String	getPrefix()
static String	getPrefix(String reference) Get the entity prefix based on an entity reference string, WARNING: this is meant for internal use, use EntityReference(String) and the methods in EntityBroker to parse references
String	getReference() Get the string reference for this entity reference object, same as calling toString()
protected static int	getSeparatorPos(String reference, int number)
String	getSpaceReference() Get the space reference for this entity reference, this ignored any id and only returns the reference to the entity space
boolean	isEmpty()
protected String	makeEntityId() Override this if you are making a new class to define your entity reference, called by public getId() method
protected String	makeEntityPrefix() Override this if you are making a new class to define your entity reference, called by public getPrefix() method
protected String	makeEntityReference(boolean spaceOnly) Override this if you are making a new class to define your entity reference
protected void	setOriginalReference(String reference)
String	toString()

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

public static final long serialVersionUID

See Also:

Constant Field Values

SEPARATOR

public static final transient char SEPARATOR

See Also:

Constant Field Values

PERIOD

public static final transient char PERIOD

See Also:

Constant Field Values

originalReference

protected transient String originalReference

prefix

public String prefix

An entity prefix, should match with the prefix handled in an EntityProvider, uniquely identifies an entity space or entity type
WARNING: use the getPrefix() method rather than referring to this directly

Constructor Detail

EntityReference

public EntityReference()

EntityReference

public EntityReference(String reference)

Constructor which takes an entity reference, this is the most common way to construct an entity reference object

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and optional path segments

EntityReference

public EntityReference(String prefix,
                       String id)

Convenience constructor for when you know the prefix and/or id

Parameters:

prefix - the entity prefix

id - the local entity id (can be empty string if there is no id)

Method Detail

getOriginalReference

public String getOriginalReference()

This is a special method and should not normally be used, use toString() or getReference()

Returns:

the reference string used to create this object or null if this was created using a constructor which does not supply a reference

setOriginalReference

protected void setOriginalReference(String reference)

getPrefix

public String getPrefix()

Returns:

the entity prefix (uniquely identifies an entity space or entity type), this should never be null

getId

public String getId()

A local entity id, represents an entity uniquely in a tool/webapp, could match with the actual id of a model data object, this will be null if this reference refers to an entity space only

Returns:

the entity id (locally unique id for an entity of this entity type) or null if this this reference refers to an entity space only

isEmpty

public boolean isEmpty()

Returns:

true if this object contains no reference data, false if it contains a valid reference

makeEntityReference

protected String makeEntityReference(boolean spaceOnly)

Override this if you are making a new class to define your entity reference

Parameters:

spaceOnly - if this is true then only return the entity space reference (e.g. /prefix), otherwise return the full reference (e.g. /prefix/id)

Returns:

an entity reference string

makeEntityPrefix

protected String makeEntityPrefix()

Override this if you are making a new class to define your entity reference, called by public getPrefix() method

Returns:

the prefix for the current entity reference

makeEntityId

protected String makeEntityId()

Override this if you are making a new class to define your entity reference, called by public getId() method

Returns:

the prefix for the current entity reference

getReference

public String getReference()

Get the string reference for this entity reference object, same as calling toString()

Returns:

the full entity reference

getSpaceReference

public String getSpaceReference()

Get the space reference for this entity reference, this ignored any id and only returns the reference to the entity space

Returns:

the entity space reference (e.g. /myPrefix)

toString

public String toString()

Overrides:

toString in class Object

Returns:

the string version of this entity reference, example: /prefix if there is no id or /prefix/id if there is an id

clone

protected Object clone()
                throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

copy

public EntityReference copy()

Returns:

a copy of this reference

See Also:

copy(EntityReference)

getPrefix

public static String getPrefix(String reference)

Get the entity prefix based on an entity reference string, WARNING: this is meant for internal use, use EntityReference(String) and the methods in EntityBroker to parse references

Parameters:

reference - an entity reference or entity URL

Returns:

the entity prefix

getIdFromRef

public static String getIdFromRef(String reference)

Will convert a reference into an id (even if it is not a reference)

Parameters:

reference - an entity reference (e.g. /user/aaronz)

Returns:

the id from the reference (e.g. aaronz), preserves null

getIdFromRefByKey

public static String getIdFromRefByKey(String reference,
                                       String key)

Get the id value out of a reference by the key that preceeds it

Parameters:

reference - an entity reference (e.g. /site/siteId/group/groupId)

key - the key to get the id from (e.g. 'group' yields groupId)

Returns:

the id value OR null if no key is found or no id is available

findPrefix

protected static String findPrefix(String reference)

Get the entity prefix based on an entity reference

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and optional id

Returns:

the entity prefix

findId

protected static String findId(String reference)

Get the local entity id based on a full entity reference

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and optional id

Returns:

the local entity id or null if none can be found

getSeparatorPos

protected static int getSeparatorPos(String reference,
                                     int number)

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and optional id

number - this is the separator to get, 0 would return the first one found, 1 would return the second

Returns:

the location of the separator between the entity and the id or -1 if none found

checkReference

protected static void checkReference(String reference)

Check if a reference is basically valid

Parameters:

reference -

Throws:

IllegalArgumentException - if the reference is not even basically valid

checkPrefixId

protected static void checkPrefixId(String prefix,
                                    String id)

Checks this prefix and id to see if they are valid format, throw exceptions if they aren't

copy

public static EntityReference copy(EntityReference ref)

Creates a copy of an entity reference

Parameters:

ref - an entity reference object

Returns:

the new copy of the ref

Throws:

IllegalArgumentException - if the ref is invalid OR null