EntityView (Sakai Entity Broker API 10.0 API)

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

Nested Classes
Modifier and Type Class and Description

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

Nested Classes
Modifier and Type	Class and Description
`static class`	`EntityView.Method` Represents HTTP methods (GET, POST, etc.)

Field Summary

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`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

Methods
Modifier and Type	Method and Description
`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

Class EntityView

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

serialVersionUID

SEPARATOR

PERIOD

PREFIX

ID

DIRECT

DIRECT_PREFIX

VIEW_LIST

VIEW_SHOW

VIEW_NEW

VIEW_EDIT

VIEW_DELETE

Constructor Detail

EntityView

EntityView

EntityView

EntityView

Method Detail

getOriginalEntityUrl

setOriginalEntityURL

getExtension

setExtension

getFormat

getMethod

setMethod

getViewKey

setViewKey

getEntityReference

setEntityReference

getParseTemplates

getAnazlyzedTemplates

populateInternals

parseEntityURL

loadParseTemplates

preloadParseTemplates

toString

getEntityURL

getEntityURL

getPathSegment

getPathSegment

getPathSegments

getParseTemplate

clone

copy

checkEntityURL

copy

translateViewKeyToMethod