org.sakaiproject.entitybroker.rest

Class EntityEncodingManager

java.lang.Object

org.sakaiproject.entitybroker.rest.EntityEncodingManager

public class EntityEncodingManager
extends Object

This handles the internal encoding (translation and formatting) of entity data, this can be used by various parts of the EB system
this is for internal use only currently but may be exposed later

Author:

Aaron Zeckoski (azeckoski @ gmail.com)

Field Summary

Fields

Modifier and Type	Field and Description
static String	BATCH_PREFIX
static String	COLLECTION
protected static String	DATA_KEY
static String	ENTITY_ID
static String	ENTITY_PREFIX
static String	ENTITY_REFERENCE
static String	ENTITY_TITLE
static String	ENTITY_URL
static String[]	HANDLED_INPUT_FORMATS
static String[]	HANDLED_OUTPUT_FORMATS
static String	JSON_CALLBACK_PARAM
static String	JSON_DEFAULT_CALLBACK
protected static String	XHTML_FOOTER
protected static String	XHTML_HEADER
protected static String	XML_HEADER
protected static String	XML_HEADER_PREFIX
protected static String	XML_HEADER_SUFFIX

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EntityEncodingManager()
	EntityEncodingManager(org.sakaiproject.entitybroker.entityprovider.EntityProviderManager entityProviderManager, org.sakaiproject.entitybroker.EntityBrokerManager entityBrokerManager)

Method Summary

Methods

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 Returned map can be fed into the ReflectUtils.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 ReflectUtils.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 will result in an exception
String	encodeEntity(String prefix, String format, org.sakaiproject.entitybroker.entityprovider.extension.EntityData entityData, org.sakaiproject.entitybroker.EntityView view) Encodes entity data
void	formatAndOutputEntity(org.sakaiproject.entitybroker.EntityReference ref, String format, List<org.sakaiproject.entitybroker.entityprovider.extension.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)
org.azeckoski.reflectutils.transcoders.Transcoder	getTranscoder(String format)
Object	internalInputTranslator(org.sakaiproject.entitybroker.EntityReference ref, String format, InputStream input, HttpServletRequest req) Handled the internal encoding of data into an entity object
void	internalOutputFormatter(org.sakaiproject.entitybroker.EntityReference ref, String format, List<org.sakaiproject.entitybroker.entityprovider.extension.EntityData> entities, Map<String,Object> params, OutputStream output, org.sakaiproject.entitybroker.EntityView view) Format entities for output based on the reference into a format, use the provided list or get the entities
protected String	makeFormViewUrl(String contextUrl, String viewKey, org.sakaiproject.entitybroker.EntityView view)
protected String	sanitizeJsonCallback(Object param) Clean the JSONP callback parameter to make sure it is sensible
void	setEntityBrokerManager(org.sakaiproject.entitybroker.EntityBrokerManager entityBrokerManager)
void	setEntityProviderManager(org.sakaiproject.entitybroker.entityprovider.EntityProviderManager entityProviderManager)
void	setTranscoder(org.azeckoski.reflectutils.transcoders.Transcoder transcoder) Override the transcoder used for a specific format
void	setTranscoders(Map<String,org.azeckoski.reflectutils.transcoders.Transcoder> transcoders)
Object	translateInputToEntity(org.sakaiproject.entitybroker.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 (This is basically a copy of the code in EntityHandlerImpl with stuff removed)
boolean	validateFormat(String data, String format) Will attempt to validate that string data is of a specific format

Methods inherited from class java.lang.Object

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

Field Detail

ENTITY_REFERENCE

public static final String ENTITY_REFERENCE

See Also:

Constant Field Values

ENTITY_ID

public static final String ENTITY_ID

See Also:

Constant Field Values

ENTITY_URL

public static final String ENTITY_URL

See Also:

Constant Field Values

ENTITY_TITLE

public static final String ENTITY_TITLE

See Also:

Constant Field Values

ENTITY_PREFIX

public static final String ENTITY_PREFIX

See Also:

Constant Field Values

COLLECTION

public static final String COLLECTION

See Also:

Constant Field Values

BATCH_PREFIX

public static final String BATCH_PREFIX

See Also:

Constant Field Values

HANDLED_INPUT_FORMATS

public static final String[] HANDLED_INPUT_FORMATS

HANDLED_OUTPUT_FORMATS

public static final String[] HANDLED_OUTPUT_FORMATS

JSON_CALLBACK_PARAM

public static final String JSON_CALLBACK_PARAM

See Also:

Constant Field Values

JSON_DEFAULT_CALLBACK

public static final String JSON_DEFAULT_CALLBACK

See Also:

Constant Field Values

XML_HEADER_PREFIX

protected static final String XML_HEADER_PREFIX

See Also:

Constant Field Values

XML_HEADER_SUFFIX

protected static final String XML_HEADER_SUFFIX

See Also:

Constant Field Values

XML_HEADER

protected static final String XML_HEADER

See Also:

Constant Field Values

XHTML_HEADER

protected static final String XHTML_HEADER

See Also:

Constant Field Values

XHTML_FOOTER

protected static final String XHTML_FOOTER

See Also:

Constant Field Values

DATA_KEY

protected static final String DATA_KEY

See Also:

Constant Field Values

Constructor Detail

EntityEncodingManager

protected EntityEncodingManager()

EntityEncodingManager

public EntityEncodingManager(org.sakaiproject.entitybroker.entityprovider.EntityProviderManager entityProviderManager,
                     org.sakaiproject.entitybroker.EntityBrokerManager entityBrokerManager)

Method Detail

setEntityProviderManager

public void setEntityProviderManager(org.sakaiproject.entitybroker.entityprovider.EntityProviderManager entityProviderManager)

setEntityBrokerManager

public void setEntityBrokerManager(org.sakaiproject.entitybroker.EntityBrokerManager entityBrokerManager)

formatAndOutputEntity

public void formatAndOutputEntity(org.sakaiproject.entitybroker.EntityReference ref,
                         String format,
                         List<org.sakaiproject.entitybroker.entityprovider.extension.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:

org.sakaiproject.entitybroker.exception.FormatUnsupportedException - if you do not handle this format type (passes control to the internal handlers)

org.sakaiproject.entitybroker.exception.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

public Object translateInputToEntity(org.sakaiproject.entitybroker.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 (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) 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:

org.sakaiproject.entitybroker.exception.FormatUnsupportedException - if you do not handle this format type (passes control to the internal handlers)

org.sakaiproject.entitybroker.exception.EntityEncodingException - if you cannot encode the received data into an entity

IllegalArgumentException - if any of the arguments are invalid

IllegalStateException - for all other failures

validateFormat

public boolean validateFormat(String data,
                     String format)

Will attempt to validate that string data is of a specific format

Parameters:

data - a chunk of data to validate

format - the format which the data is supposed encoded in

Returns:

true if the data appears valid for the given format, false otherwise

internalInputTranslator

public Object internalInputTranslator(org.sakaiproject.entitybroker.EntityReference ref,
                             String format,
                             InputStream input,
                             HttpServletRequest req)

Handled the internal encoding of data into an entity object

Parameters:

ref - the entity reference

format - the format which the input is encoded in

input - the data being input

Returns:

the entity object based on the data

Throws:

org.sakaiproject.entitybroker.exception.FormatUnsupportedException - if you do not handle this format type (passes control to the internal handlers)

org.sakaiproject.entitybroker.exception.EntityEncodingException - if you cannot encode the received data into an entity

IllegalArgumentException - if any of the arguments are invalid

IllegalStateException - for all other failures

internalOutputFormatter

public void internalOutputFormatter(org.sakaiproject.entitybroker.EntityReference ref,
                           String format,
                           List<org.sakaiproject.entitybroker.entityprovider.extension.EntityData> entities,
                           Map<String,Object> params,
                           OutputStream output,
                           org.sakaiproject.entitybroker.EntityView view)

Format entities for output based on the reference into a format, use the provided list or get the entities

Parameters:

ref - the entity reference for this, if this is a reference to a collection then this will be rendered as a collection of entities, if a reference to a single entity then only the matching one from the collection will be used

format - the format to use for the output data

entities - (optional) if this is null then the entities will be fetched

output - the outputstream to place the encoded data into

view - (optional)

Throws:

org.sakaiproject.entitybroker.exception.FormatUnsupportedException - if you do not handle this format type (passes control to the internal handlers)

org.sakaiproject.entitybroker.exception.EntityEncodingException - if you cannot encode the received data into an entity

IllegalArgumentException - if any of the arguments are invalid

IllegalStateException - for all other failures

encodeEntity

public String encodeEntity(String prefix,
                  String format,
                  org.sakaiproject.entitybroker.entityprovider.extension.EntityData entityData,
                  org.sakaiproject.entitybroker.EntityView view)

Encodes entity data

Parameters:

prefix - the entity prefix related to this data

format - the format to encode the data into

entityData - (optional) entity data to encode

view - (optional) used to generate links and determine the correct incoming view

Returns:

the encoded entity or "" if encoding fails

makeFormViewUrl

protected String makeFormViewUrl(String contextUrl,
                     String viewKey,
                     org.sakaiproject.entitybroker.EntityView view)

Returns:

the form view URLs which should be used with the forms

setTranscoders

public void setTranscoders(Map<String,org.azeckoski.reflectutils.transcoders.Transcoder> transcoders)

setTranscoder

public void setTranscoder(org.azeckoski.reflectutils.transcoders.Transcoder transcoder)

Override the transcoder used for a specific format

Parameters:

transcoder - a transcoder implementation

getTranscoder

public org.azeckoski.reflectutils.transcoders.Transcoder getTranscoder(String format)

encodeData

public 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 will result in an exception

Parameters:

data - the data to encode (can be a POJO or Map or pretty much any java object)

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

Throws:

UnsupportedOperationException - if the data cannot be encoded

sanitizeJsonCallback

protected String sanitizeJsonCallback(Object param)

Clean the JSONP callback parameter to make sure it is sensible

Parameters:

param - The parameter for the callback, should be a String

Returns:

The string version of the param or the default callback name

decodeData

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

Decode a string of a specified format into a java map
Returned map can be fed into the ReflectUtils.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 ReflectUtils.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