Package org.sakaiproject.entitybroker

Class 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

    • 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

      • 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

      • 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

      • 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

      • 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