org.sakaiproject.entitybroker.entityprovider.capabilities

Interface OutputFormattable

All Superinterfaces:

EntityProvider, Formats, Outputable

public interface OutputFormattable
extends Outputable

Allows this entity to define the output data format for a reference or a list of entity objects depending on the format requested, if you just want to use the internal methods to handle formatting the output then simply use Outputable
NOTE: throwing FormatUnsupportedException will pass control over to the internal handlers for formatting, if you want to stop the request for this format type entirely then throw an IllegalStateException and the processing will be halted

Author:

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

Field Summary

Fields inherited from interface org.sakaiproject.entitybroker.entityprovider.extension.Formats

ALL_KNOWN_FORMATS, ATOM, ATOM_EXTENSIONS, ATOM_MIME_TYPE, FORM, FORM_EXTENSIONS, FORM_MIME_TYPE, HTML, HTML_EXTENSIONS, HTML_MIME_TYPE, JSON, JSON_EXTENSIONS, JSON_MIME_TYPE, JSONP, JSONP_EXTENSIONS, JSONP_MIME_TYPE, RSS, RSS_EXTENSIONS, RSS_MIME_TYPE, TXT, TXT_EXTENSIONS, TXT_MIME_TYPE, UTF_8, XML, XML_EXTENSIONS, XML_MIME_TYPE

Method Summary

Modifier and Type

Method and Description

void

formatOutput(EntityReference ref, String format, List<EntityData> entities, Map<String,Object> params, OutputStream output) Formats the 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 NOTE: be careful to correctly handle the list of entities which are meant to be encoded, note that the EntityData objects include meta data and the data they contain can be of any object type (though all data will come from your provider so the types should not be surprising)

Methods inherited from interface org.sakaiproject.entitybroker.entityprovider.capabilities.Outputable

getHandledOutputFormats

Methods inherited from interface org.sakaiproject.entitybroker.entityprovider.EntityProvider

getEntityPrefix

Method Detail

formatOutput

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

Formats the 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
NOTE: be careful to correctly handle the list of entities which are meant to be encoded, note that the EntityData objects include meta data and the data they contain can be of any object type (though all data will come from your provider so the types should not be surprising)

Parameters:

ref - the parsed reference object which uniquely represents this entity

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

entities - (optional) a list of entity data objects 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 data object 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

params - (optional) incoming set of parameters which may be used to send data specific to this request, may be null

output - 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 format the entity data for some reason

IllegalArgumentException - if any of the arguments are invalid

IllegalStateException - for all other failures