org.sakaiproject.entitybroker.providers

Interface EntityRESTProvider

public interface EntityRESTProvider

Handles anything REST based that is not part of the core EB registration piece

Author:

Aaron Zeckoski (azeckoski @ gmail.com)

Method Summary

Modifier and Type	Method and Description
Map<String,Object>	decodeData(String data, String format) Decode a string of a specified format into a java map of simple objects Returned map can be fed into #populate(Object, Map) if you want to convert it into a known object type Types are likely to require conversion as guesses are made about the right formats, use of the #convert(Object, Class) method is recommended
String	encodeData(Object data, String format, String name, Map<String,Object> properties) Encode data into a given format, can handle any java object, note that unsupported formats and invalid data will result in an exception
void	formatAndOutputEntity(EntityReference ref, String format, List<EntityData> entities, OutputStream outputStream, Map<String,Object> params) Format and output an entity or collection included or referred to by this entity ref object into output according to the format string provided, Should take into account the reference when determining what the entities are and how to encode them (This is basically a copy of the code in EntityHandlerImpl with stuff removed)
ActionReturn	handleCustomActionExecution(ActionsExecutable actionProvider, EntityReference ref, String action, Map<String,Object> actionParams, OutputStream outputStream, EntityView view, Map<String,Object> searchParams) This will execute a custom action for an entity or space/collection of entities This is meant for specialized usage as custom actions are typically meant to be executed by REST calls only
EntityResponse	handleEntityRequest(String reference, String viewKey, String format, Map<String,String> params, Object entity) Processes and handles an entity request without requiring servlet processing and a request/response round trip
Object	translateInputToEntity(EntityReference ref, String format, InputStream inputStream, Map<String,Object> params) Translates the input data stream in the supplied format into an entity object for this reference

Method Detail

handleEntityRequest

EntityResponse handleEntityRequest(String reference,
                                   String viewKey,
                                   String format,
                                   Map<String,String> params,
                                   Object entity)

Processes and handles an entity request without requiring servlet processing and a request/response round trip

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and optionally the local id, cannot be null or empty

viewKey - specifies what kind of request this is (create, read/show, etc.), must correspond to the VIEW constants in EntityView, example: EntityView.VIEW_SHOW

format - (optional) this is the format for this request (from Formats, e.g. XML), if nothing is specified then the default will be used: Formats.HTML

params - (optional) any params you want to send along with the request should be included here, they will be placed into the query string or the request body depending on the type of request this is

entity - (optional) leave this null in most cases, if you supply an entity object here it will be encoded based on the supplied format (only if the entity supports output formatting) and then decoded on the other end (only if the entity supports input translation), in most cases it is better to supply the entity values in the params

Returns:

the response information encoded in an object, you must check this to see what the results of the request were (getting a response back does not mean the request succeeded)

Throws:

IllegalArgumentException - if the inputs are invalid

RuntimeException - if the http request has an unrecoverable failure or an encoding failure occurs

formatAndOutputEntity

void formatAndOutputEntity(EntityReference ref,
                           String format,
                           List<EntityData> entities,
                           OutputStream outputStream,
                           Map<String,Object> params)

Format and output an entity or collection included or referred to by this entity ref object into output according to the format string provided, Should take into account the reference when determining what the entities are and how to encode them (This is basically a copy of the code in EntityHandlerImpl with stuff removed)

Parameters:

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

format - a string constant indicating the format (from Formats) for output, (example: #XML)

entities - (optional) a list of entities to create formatted output for, if this is null then the entities should be retrieved based on the reference, if this contains only a single item AND the ref refers to a single entity then the entity should be extracted from the list and encoded without the indication that it is a collection, for all other cases the encoding should include an indication that this is a list of entities

outputStream - the output stream to place the formatted data in, should be UTF-8 encoded if there is char data

Throws:

FormatUnsupportedException - if you do not handle this format type (passes control to the internal handlers)

EntityEncodingException - if you cannot encode the received data into an entity

IllegalArgumentException - if any of the arguments are invalid

IllegalStateException - for all other failures

translateInputToEntity

Object translateInputToEntity(EntityReference ref,
                              String format,
                              InputStream inputStream,
                              Map<String,Object> params)

Translates the input data stream in the supplied format into an entity object for this reference

Parameters:

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

format - a string constant indicating the format (from Formats) of the input, (example: #XML)

input - a stream which contains the data to make up this entity, you may assume this is UTF-8 encoded if you don't know anything else about it

Returns:

an entity object of the type used for the given reference

Throws:

FormatUnsupportedException - if you do not handle this format type (passes control to the internal handlers)

EntityEncodingException - if you cannot encode the received data into an entity

IllegalArgumentException - if any of the arguments are invalid

IllegalStateException - for all other failures

handleCustomActionExecution

ActionReturn handleCustomActionExecution(ActionsExecutable actionProvider,
                                         EntityReference ref,
                                         String action,
                                         Map<String,Object> actionParams,
                                         OutputStream outputStream,
                                         EntityView view,
                                         Map<String,Object> searchParams)

This will execute a custom action for an entity or space/collection of entities
This is meant for specialized usage as custom actions are typically meant to be executed by REST calls only

Parameters:

actionProvider - the action provider which has declared itself as the handler for this action and prefix

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

action - key which will be used to trigger the action (e.g. promote, double, photo), can be triggered by a URL like so: /user/aaronz/promote

actionParams - (optional) an optional set of params to pass along with this custom action request, typically used to provide information about the request, may be left null if not needed

outputStream - (optional) an OutputStream to place binary or long text data into, if this is used for binary data then the ActionReturn should be returned with the correct encoding information and the output variable set to the OutputStream, may be left null if this custom action does not deal with binary streams

view - the entity view corresponding to all data sent in the URL for this action view

searchParams - any search params which were included in the request

Returns:

an ActionReturn which contains entity data or binary/string data OR null if there is no return for this action

Throws:

UnsupportedOperationException - if there is no action with this key for this entity

IllegalArgumentException - if there are required params that are missing or invalid

IllegalStateException - if the action cannot be performed for some reason

encodeData

String encodeData(Object data,
                  String format,
                  String name,
                  Map<String,Object> properties)

Encode data into a given format, can handle any java object, note that unsupported formats and invalid data will result in an exception

Parameters:

data - the data to encode

format - the format to use for output (from Formats)

name - (optional) the name to use for the encoded data (e.g. root node for XML)

properties - (optional) extra properties to add into the encoding, ignored if encoded object is not a map or bean

Returns:

the encoded string in the requested format

Throws:

UnsupportedOperationException - if the data cannot be encoded

IllegalArgumentException - if the format requested cannot be encoded because there is no encoder

decodeData

Map<String,Object> decodeData(String data,
                              String format)

Decode a string of a specified format into a java map of simple objects
Returned map can be fed into #populate(Object, Map) if you want to convert it into a known object type
Types are likely to require conversion as guesses are made about the right formats, use of the #convert(Object, Class) method is recommended

Parameters:

data - encoded data

format - the format of the encoded data (from Formats)

Returns:

a map containing all the data derived from the encoded data

Throws:

UnsupportedOperationException - if the data cannot be decoded

IllegalArgumentException - if the data cannot be decoded because there is no decoder for that format