org.sakaiproject.entitybroker
Class EntityView

java.lang.Object
  org.sakaiproject.entitybroker.EntityView

All Implemented Interfaces:

Serializable, Cloneable

public class EntityView
extends Object
implements Cloneable, Serializable

Defines an entity view (a specific way to looking at entity data, e.g. LIST of entities, SHOW a single entity, UPDATE an entity, DELETE an entity, create a NEW entity), each view has a unique view key constant related to it (e.g. VIEW_LIST)
The view contains all the known information about a view request including the entity prefix, reference, full path and segments, format (extension), method (POST, GET, etc.), and view key (type). The Entity View can generate the URL for this view based on the data it contains.
Views use URL templates which can be controlled via custom templates if desired.
NOTE: For those using custom actions, the view is typically LIST if you are returning data of an unspecified size. If you want to perform write operations (POST, UPDATE, DELETE), you will need to use the appropriate view constant. See the docs on each constant for more detail.

Author:

Aaron Zeckoski (aaron@caret.cam.ac.uk)

See Also:

Serialized Form

Nested Class Summary

static class

EntityView.Method Represents HTTP methods (GET, POST, etc.)

Field Summary

static String	DIRECT
static String	DIRECT_PREFIX
static String	ID
static char	PERIOD
static String	PREFIX
static char	SEPARATOR
static long	serialVersionUID
static String	VIEW_DELETE Defines the view for the "delete" (destroy) operation, remove an entity or access a form for removing an entity, represents a EntityView.Method.DELETE to a specific entity
static String	VIEW_EDIT Defines the view for the "edit" (update) operation, update an entity or access a form for updating an entity, represents a EntityView.Method.PUT (or POST) to a specific entity, also indicates an action related to writing a specific entity
static String	VIEW_LIST Defines the view for the "list" (index) or collection operation, access a list/collection of all entities of a type (possibly filtered by search params), represents a EntityView.Method.GET to the entity space/collection, also indicates an action related to reading a collection of entities
static String	VIEW_NEW Defines the view for the "new" (create) operation, create a new record or access a form for creating a new record, represents a EntityView.Method.POST (or PUT) to the entity space/collection, also indicates an action related to writing a collection of entities
static String	VIEW_SHOW Defines the view for the "show" (read) operation, access data or a view of an entity, represents a EntityView.Method.GET to a specific entity, also indicates an action related to reading a specific entity

Constructor Summary

EntityView()

EntityView(EntityReference ref, String viewKey, String extension)
Construct an entity view based on a reference, view, and format extension

EntityView(String entityURL)
Constructor which takes an entity URL path, (should not include anything but the path, for example: http://server/webapp/myprefix/edit/3/stuff.xml?

EntityView(String viewKey, Map<String,String> segments, String extension)
Turn this viewKey and map of segments (key -> value pairs) into an entity view object

Method Summary

protected static void	checkEntityURL(String entityURL) Check if an entityUrl is basically valid
Object	clone()
EntityView	copy()
static EntityView	copy(EntityView ev) Makes a copy of an EntityView which can be changed independently
List<TemplateParseUtil.PreProcessedTemplate>	getAnazlyzedTemplates()
EntityReference	getEntityReference()
String	getEntityURL()
String	getEntityURL(String viewKey, String extension) Get an entityUrl by merging a specific template with the data in this EB object
String	getExtension() The extension for this view which defines the type of data that will be returned for this view, examples: html, xml, json NOTE: you should assume html return format when this is null
String	getFormat()
String	getMethod()
String	getOriginalEntityUrl() Special use only, normally you should use toString() or getEntityURL(String, String)
String	getParseTemplate(String templateKey)
List<TemplateParseUtil.Template>	getParseTemplates()
String	getPathSegment(int position) Get a segment value by position from the encoded URL for this view Position 0 is always the prefix Example: /user/aaronz/promote/stuff.xml position 0: 'user' position 1: 'aaronz' position 2: 'promote' position 3: 'stuff' position 4: null
String	getPathSegment(String parseVariable) Gets the parsed values of path segment variables
String[]	getPathSegments() Get all the path segments for the encoded URL for this view Example: /user/aaronz/promote/stuff.xml segments = {"user","aaronz","promote","stuff"}
String	getViewKey()
void	loadParseTemplates(List<TemplateParseUtil.Template> templates) Override this method if creating a custom EntityView object
void	parseEntityURL(String entityURL) Used to build this object after it has already been created (typically so custom templates can be inserted)
protected void	populateInternals(String viewKey, Map<String,String> segments, String extension) Populates the internal values based on the view key, map of segments, and extension
void	preloadParseTemplates(List<TemplateParseUtil.PreProcessedTemplate> preprocessedTemplates) Special efficiency method to reduce reloading of custom templates, do not use this unless you wrote it or REALLY know what you are doing
EntityView	setEntityReference(EntityReference ref) Allows for easy chained construction of EntityViews by setting an EntityReference, does not set the viewkey or extension unless they are unset, maintains current extension
void	setExtension(String extension)
void	setMethod(EntityView.Method method)
protected void	setOriginalEntityURL(String entityUrl)
void	setViewKey(String viewKey)
String	toString()
static EntityView.Method	translateViewKeyToMethod(String viewKey) Translate a viewkey into an http method

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 char SEPARATOR

See Also:

Constant Field Values

PERIOD

public static final char PERIOD

See Also:

Constant Field Values

PREFIX

public static final String PREFIX

See Also:

Constant Field Values

ID

public static final String ID

See Also:

Constant Field Values

DIRECT

public static final String DIRECT

See Also:

Constant Field Values

DIRECT_PREFIX

public static final String DIRECT_PREFIX

See Also:

Constant Field Values

VIEW_LIST

public static final String VIEW_LIST

Defines the view for the "list" (index) or collection operation, access a list/collection of all entities of a type (possibly filtered by search params), represents a EntityView.Method.GET to the entity space/collection, also indicates an action related to reading a collection of entities

See Also:

Constant Field Values

VIEW_SHOW

public static final String VIEW_SHOW

Defines the view for the "show" (read) operation, access data or a view of an entity, represents a EntityView.Method.GET to a specific entity, also indicates an action related to reading a specific entity

See Also:

Constant Field Values

VIEW_NEW

public static final String VIEW_NEW

Defines the view for the "new" (create) operation, create a new record or access a form for creating a new record, represents a EntityView.Method.POST (or PUT) to the entity space/collection, also indicates an action related to writing a collection of entities

See Also:

Constant Field Values

VIEW_EDIT

public static final String VIEW_EDIT

Defines the view for the "edit" (update) operation, update an entity or access a form for updating an entity, represents a EntityView.Method.PUT (or POST) to a specific entity, also indicates an action related to writing a specific entity

See Also:

Constant Field Values

VIEW_DELETE

public static final String VIEW_DELETE

Defines the view for the "delete" (destroy) operation, remove an entity or access a form for removing an entity, represents a EntityView.Method.DELETE to a specific entity

See Also:

Constant Field Values

Constructor Detail

EntityView

public EntityView()

EntityView

public EntityView(String entityURL)

Constructor which takes an entity URL path, (should not include anything but the path, for example: http://server/webapp/myprefix/edit/3/stuff.xml?system=down would yield the path: /myprefix/edit/3/stuff.xml
NOTE: this is the most common way to construct an entity view object

Parameters:

entityURL - a URL path which goes to a specific entity view, consists of path segments defined by path templates and includes an option extension

EntityView

public EntityView(String viewKey,
                  Map<String,String> segments,
                  String extension)

Turn this viewKey and map of segments (key -> value pairs) into an entity view object

Parameters:

viewKey - a key which uniquely identifies a view, from the set of template keys #PARSE_TEMPLATE_KEYS

segments - a map of replaceable keys (e.g. PREFIX) to values, the replaceable variable names -> values (e.g. "prefix" -> "myPrefix"), must contain at LEAST a key for the prefix (use constant PREFIX) which is not set to null

extension - (optional) format extension related to this view (e.g. xml), do not include the period, leave this null for no extension

EntityView

public EntityView(EntityReference ref,
                  String viewKey,
                  String extension)

Construct an entity view based on a reference, view, and format extension

Parameters:

ref - an EntityReference object which represents a unique entity reference

viewKey - (optional) a key which uniquely identifies a view, from the set of template keys #PARSE_TEMPLATE_KEYS

extension - (optional) format extension related to this view (e.g. xml), do not include the period, leave this null for no extension

Method Detail

getOriginalEntityUrl

public String getOriginalEntityUrl()

Special use only, normally you should use toString() or getEntityURL(String, String)

Returns:

the original entity URL which was used to create this entity view, includes the optional pieces from the URL, will be null if this was created without using a constructor that takes an entityUrl

setOriginalEntityURL

protected void setOriginalEntityURL(String entityUrl)

getExtension

public String getExtension()

The extension for this view which defines the type of data that will be returned for this view, examples: html, xml, json NOTE: you should assume html return format when this is null

Returns:

the extension for this view if there is one, this will be null if there was no extension in the original entityUrl

setExtension

public void setExtension(String extension)

getFormat

public String getFormat()

Returns:

the format (from Formats) that is being used for this view, will return Formats.HTML if none set

getMethod

public String getMethod()

Returns:

the method (GET, POST, etc.) (from EntityView.Method) being used for this view, defaults to GET if none was set explicitly

setMethod

public void setMethod(EntityView.Method method)

getViewKey

public String getViewKey()

Returns:

the key which uniquely identifies the view we are associated with, uses the constants like VIEW_LIST and VIEW_NEW

setViewKey

public void setViewKey(String viewKey)

getEntityReference

public EntityReference getEntityReference()

Returns:

the entity reference object which indicates which entity this view related to

setEntityReference

public EntityView setEntityReference(EntityReference ref)

Allows for easy chained construction of EntityViews by setting an EntityReference, does not set the viewkey or extension unless they are unset, maintains current extension

getParseTemplates

public List<TemplateParseUtil.Template> getParseTemplates()

getAnazlyzedTemplates

public List<TemplateParseUtil.PreProcessedTemplate> getAnazlyzedTemplates()

populateInternals

protected void populateInternals(String viewKey,
                                 Map<String,String> segments,
                                 String extension)

Populates the internal values based on the view key, map of segments, and extension

parseEntityURL

public void parseEntityURL(String entityURL)

Used to build this object after it has already been created (typically so custom templates can be inserted)

Parameters:

entityURL - a URL path which goes to a specific entity view, consists of path segments defined by path templates and includes an option extension

loadParseTemplates

public void loadParseTemplates(List<TemplateParseUtil.Template> templates)

Override this method if creating a custom EntityView object

Parameters:

templates - a list of template constants -> parse templates, the array which defines the set of template keys is #PARSE_TEMPLATE_KEYS
Rules for parse templates: 1) "{","}", and SEPARATOR are special characters and must be used as indicated only 2) Must begin with a SEPARATOR, must not end with a SEPARATOR 3) must begin with "/{prefix}" (use the SEPARATOR and PREFIX constants) 3) each {var} can only be used once in a template 4) {var} can never touch each other (i.e /{var1}{var2}/{id} is invalid) 5) each {var} can only have the chars from TemplateParseUtil.VALID_VAR_CHARS 6) parse templates can only have the chars from TemplateParseUtil.VALID_TEMPLATE_CHARS 7) Empty braces ({}) cannot appear in the template

preloadParseTemplates

public void preloadParseTemplates(List<TemplateParseUtil.PreProcessedTemplate> preprocessedTemplates)

Special efficiency method to reduce reloading of custom templates, do not use this unless you wrote it or REALLY know what you are doing

toString

public String toString()

Overrides:

toString in class Object

Returns:

the entity URL of the internal reference based on the internal viewKey and extension, defaults to TemplateParseUtil.TEMPLATE_SHOW or the TemplateParseUtil.TEMPLATE_LIST one if there is no id, example: /prefix if there is no id or /prefix/id if there is an id

Throws:

IllegalArgumentException - if there is not enough information to generate a URL

getEntityURL

public String getEntityURL()

Returns:

the entity URL of the internal reference based on the internal viewKey and extension, defaults to TemplateParseUtil.TEMPLATE_SHOW or the TemplateParseUtil.TEMPLATE_LIST one if there is no id, example: /prefix if there is no id or /prefix/id if there is an id

Throws:

IllegalArgumentException - if there is not enough information to generate a URL

getEntityURL

public String getEntityURL(String viewKey,
                           String extension)

Get an entityUrl by merging a specific template with the data in this EB object

Parameters:

viewKey - a key which uniquely identifies a view, from the set of template keys #PARSE_TEMPLATE_KEYS

extension - an optional extension related to this view (e.g. xml), do not include the period, leave this null for no extension

Returns:

the entityUrl which goes to this view

Throws:

IllegalArgumentException - if the viewKey is invalid OR there is not enough information in the path segments to generate the requested URL

getPathSegment

public String getPathSegment(String parseVariable)

Gets the parsed values of path segment variables

Parameters:

parseVariable - a path segment variable (the thing that gets replaced in the parse template)

Returns:

the value of this parse variable or null if no value exists

getPathSegment

public String getPathSegment(int position)

Get a segment value by position from the encoded URL for this view
Position 0 is always the prefix
Example: /user/aaronz/promote/stuff.xml
position 0: 'user'
position 1: 'aaronz'
position 2: 'promote'
position 3: 'stuff'
position 4: null

Parameters:

position - the position number in the path segments, 0 is always the prefix

Returns:

the value at the given path position OR null if there is nothing at that position

getPathSegments

public String[] getPathSegments()

Get all the path segments for the encoded URL for this view
Example: /user/aaronz/promote/stuff.xml
segments = {"user","aaronz","promote","stuff"}

Returns:

an array of path segments

getParseTemplate

public String getParseTemplate(String templateKey)

Parameters:

templateKey - a key from the set of template keys #PARSE_TEMPLATE_KEYS, should match with the viewKey

Returns:

the template being used by this entity view for this key or null if none found

clone

public Object clone()
             throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

copy

public EntityView copy()

Returns:

a copy of this object

See Also:

copy(EntityView)

checkEntityURL

protected static void checkEntityURL(String entityURL)

Check if an entityUrl is basically valid

Parameters:

entityURL -

Throws:

IllegalArgumentException - if the entityUrl is not even basically valid

copy

public static EntityView copy(EntityView ev)

Makes a copy of an EntityView which can be changed independently

Parameters:

ev - any EntityView

Returns:

the copy

Throws:

IllegalArgumentException - if the input is null OR not completely constructed

translateViewKeyToMethod

public static EntityView.Method translateViewKeyToMethod(String viewKey)

Translate a viewkey into an http method

Parameters:

viewKey -

Returns:

the method which matches this viewkey