org.sakaiproject.entitybroker
Interface EntityBroker

All Superinterfaces:

PropertiesProvider, SearchProvider, TagProvider

public interface EntityBroker
extends PropertiesProvider, TagProvider, SearchProvider

This service interface defines the capabilities of the entity broker system
It allows Sakai system methods, developers, etc. to access Sakai entity information (new and old)

Author:

Aaron Zeckoski (aaronz@vt.edu), Antranig Basman (antranig@caret.cam.ac.uk)

Method Summary

List<EntityData>	browseEntities(String prefix, Search search, String userReference, String associatedReference, String parentReference, Map<String,Object> params) Returns the list of entity information (and possibly entities) for a user to view while browsing an entity space, this is specially designed to support browsing and picking entities, not all entities support browsing If the entity type indicated by the prefix does not support browsing then this will return an empty list
boolean	entityExists(String reference) Check if an entity exists by the globally unique reference string, (the global reference string will consist of the entity prefix and any local ID).
ActionReturn	executeCustomAction(String reference, String action, Map<String,Object> params, OutputStream outputStream) 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
List<?>	fetchEntities(String prefix, Search search, Map<String,Object> params) Allows these entities to be fetched based on search parameters, this should never return null and if there are no entities then the list should be empty Note: The entity class types in the list need to be able to be resolved from the ClassLoader of the EntityBrokerManager (currently this means deployed into shared) These do not have to be model objects and may simply be something created (e.g.
Object	fetchEntity(String reference) Fetches a concrete object representing this entity reference; either one from the Resolvable capability if implemented by the responsible EntityProvider, or else from the underlying legacy Sakai entity system Note that this may be a String or Map and does not have to be a POJO, the type of object should be determined out of band This will return null if the entity exists but is not Resolvable or available in the legacy entity system
List<EntityData>	findEntitesByTags(String[] tags, String[] prefixes, boolean matchAll, Search search, Map<String,Object> params) Search for all entities which have the given tags, can limit the return using the search object
EntityResponse	fireEntityRequest(String reference, String viewKey, String format, Map<String,String> params, Object entity)
void	fireEvent(String eventName, String reference) Fire an event to Sakai with the specified name, targeted at the supplied reference, which should be a reference to an existing entity managed by this broker NOTE: This will allow events to be fired for references without a broker or invalid references
void	formatAndOutputEntity(String reference, String format, List<?> entities, OutputStream output, 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
List<BrowseEntity>	getBrowseableEntities(String parentPrefix) For authors of entity browsing systems, this provides a list of all the meta data related to the entities in the system which are Browseable, this provides the root entities when there is no parent prefix provided
List<EntityData>	getEntities(String prefix, Search search, Map<String,Object> params) Gets entity data (and possibly entities) for a specific entity prefix, entity data contains the reference, URL, display title and optionally the concrete entity and properties If the entity type indicated by the prefix does not support collections then this will return an empty list
EntityData	getEntity(String reference) Gets the data related to an entity as long as it exists, always includes at least the entity reference information and the URL, may also include a concrete entity object and entity properties
String	getEntityURL(String reference) Get the full absolute URL to the entity defined by this entity reference, this will fail-safe to a direct URL to an entity space URL if that is all that is available
String	getEntityURL(String reference, String viewKey, String extension) Get the full absolute URL to the entity view defined by these params, this will fail-safe to a direct URL to an entity space URL if that is all that is available, this will use the default entity URL template associated with the viewKey and include an optional extension if specified (these will be inferred if they are missing)
EntityView	getEntityView(String reference, String viewKey, String extension) Get the EntityView object which represents a specific view of an entity or entity collection, this is similar to getEntityURL(String, String, String) but allows the developer to deal with the EntityView object if desired
Set<String>	getRegisteredPrefixes() Retrieve a complete set of all currently registered EntityProvider prefixes
Set<String>	getTags(String reference) Deprecated. use TagProvider.getTagsForEntity(String)
boolean	isPrefixRegistered(String prefix) Check if a prefix is currently registered
EntityReference	parseReference(String reference) Parses an entity reference into a concrete object, of type EntityReference, or some class derived from it, for example IdEntityReference or some other class of object which is returned from ParseSpecParseable.
void	setTags(String reference, String[] tags) Deprecated. use TagProvider.setTagsForEntity(String, String[])
Object	translateInputToEntity(String reference, String format, InputStream input, Map<String,Object> params) Translates the input data stream in the supplied format into an entity object for this reference

Methods inherited from interface org.sakaiproject.entitybroker.entityprovider.extension.PropertiesProvider

findEntityRefs, getProperties, getPropertyValue, setPropertyValue

Methods inherited from interface org.sakaiproject.entitybroker.entityprovider.extension.TagProvider

addTagsToEntity, getTagsForEntity, removeTagsFromEntity, setTagsForEntity

Methods inherited from interface org.sakaiproject.entitybroker.entityprovider.extension.SearchProvider

add, remove, resetSearchIndexes, search

Method Detail

entityExists

boolean entityExists(String reference)

Check if an entity exists by the globally unique reference string, (the global reference string will consist of the entity prefix and any local ID). If no EntityProvider for the reference is found which implements CoreEntityProvider, this method will return true by default, in other words, this cannot determine if a legacy entity exists, only a new entity

Parameters:

reference - a globally unique reference to an entity (e.g. /myprefix/myid), consists of the entity prefix and optional segments (normally the id at least)

Returns:

true if the entity exists, false otherwise

Throws:

IllegalArgumentException - if the reference is invalid

isPrefixRegistered

boolean isPrefixRegistered(String prefix)

Check if a prefix is currently registered

Parameters:

prefix - the string which represents a type of entity handled by an entity provider

Returns:

true if the prefix is registered OR false if not

getRegisteredPrefixes

Set<String> getRegisteredPrefixes()

Retrieve a complete set of all currently registered EntityProvider prefixes

Returns:

all currently registered entity prefixes

getEntityURL

String getEntityURL(String reference)

Get the full absolute URL to the entity defined by this entity reference, this will fail-safe to a direct URL to an entity space URL if that is all that is available

Parameters:

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

Returns:

a full URL string (e.g. http://server/direct/prefix/id)

Throws:

IllegalArgumentException - if the reference or other inputs are invalid

getEntityURL

String getEntityURL(String reference,
                    String viewKey,
                    String extension)

Get the full absolute URL to the entity view defined by these params, this will fail-safe to a direct URL to an entity space URL if that is all that is available, this will use the default entity URL template associated with the viewKey and include an optional extension if specified (these will be inferred if they are missing)

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and optionally the local id

viewKey - the specific view type to get the URL for, use the VIEW_* constants from EntityView (e.g. EntityView.VIEW_LIST), can be null to determine the key automatically

extension - the optional extension to add to the end which defines the expected data which is returned, use constants in Formats (e.g. Formats.XML), can be null to use no extension, default is assumed to be html if none is set

Returns:

the full URL string to a specific entity or space, (e.g. http://server/direct/prefix/id)

Throws:

IllegalArgumentException - if the reference or other inputs are invalid

getEntityView

EntityView getEntityView(String reference,
                         String viewKey,
                         String extension)

Get the EntityView object which represents a specific view of an entity or entity collection, this is similar to getEntityURL(String, String, String) but allows the developer to deal with the EntityView object if desired

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and optionally the local id

viewKey - the specific view type to get the URL for, use the VIEW_* constants from EntityView (e.g. EntityView.VIEW_LIST), can be null to determine the key automatically

extension - the optional extension to add to the end which defines the expected data which is returned, use constants in Formats (e.g. Formats.XML), can be null to use no extension, default is assumed to be html if none is set

Returns:

an EntityView object if one can be formed

Throws:

IllegalArgumentException - if the params cannot be made into an EntityView

fireEvent

void fireEvent(String eventName,
               String reference)

Fire an event to Sakai with the specified name, targeted at the supplied reference, which should be a reference to an existing entity managed by this broker
NOTE: This will allow events to be fired for references without a broker or invalid references

Parameters:

eventName - a string which represents the name of the event (e.g. announcement.create), cannot be null or empty

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

fireEntityRequest

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

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

parseReference

EntityReference parseReference(String reference)

Parses an entity reference into a concrete object, of type EntityReference, or some class derived from it, for example IdEntityReference or some other class of object which is returned from ParseSpecParseable.

Parameters:

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

Returns:

an entity reference object which will contain the entity prefix and any optional segments, or null if the reference was not recognized as a valid entity handled by the broker (will be an IdEntityReference if there is an id set)

Throws:

IllegalArgumentException - if the reference is invalid and cannot be parsed

fetchEntity

Object fetchEntity(String reference)

Fetches a concrete object representing this entity reference; either one from the Resolvable capability if implemented by the responsible EntityProvider, or else from the underlying legacy Sakai entity system
Note that this may be a String or Map and does not have to be a POJO, the type of object should be determined out of band
This will return null if the entity exists but is not Resolvable or available in the legacy entity system

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and local id

Returns:

an object which represents the entity OR null if none can be found or this type does not support fetching

Throws:

SecurityException - if the entity cannot be accessed by the current user or is not publicly accessible

IllegalArgumentException - if the reference is invalid

IllegalStateException - if any other error occurs

fetchEntities

List<?> fetchEntities(String prefix,
                      Search search,
                      Map<String,Object> params)

Allows these entities to be fetched based on search parameters, this should never return null and if there are no entities then the list should be empty
Note: The entity class types in the list need to be able to be resolved from the ClassLoader of the EntityBrokerManager (currently this means deployed into shared)

These do not have to be model objects and may simply be something created (e.g. String, Map, etc.) to give to anyone calling this method

Parameters:

prefix - the string which represents a type of entity handled by an entity provider, if the prefix does not support fetching collections then no entities will be returned

search - a search object which can define the order to return entities, search filters, and total number of entities returned,
NOTE: There are some predefined search keys which you may optionally use, provider are encourage to support the SEARCH_* search keys listed in this interface

Returns:

a list of entity objects (POJOs, Map, etc.) of the type handled by this provider OR empty if none found, will not return null

Throws:

SecurityException - if the data cannot be accessed by the current user or is not publicly accessible

IllegalArgumentException - if the reference is invalid or the search is invalid

IllegalStateException - if any other error occurs

getEntity

EntityData getEntity(String reference)

Gets the data related to an entity as long as it exists, always includes at least the entity reference information and the URL, may also include a concrete entity object and entity properties

Parameters:

reference - a globally unique reference to an entity, consists of the entity prefix and local id

Returns:

an entity data object which contains data about the entity OR null if the entity does not exist

Throws:

SecurityException - if the entity cannot be accessed by the current user or is not publicly accessible

IllegalArgumentException - if the reference is invalid

IllegalStateException - if any other error occurs

getEntities

List<EntityData> getEntities(String prefix,
                             Search search,
                             Map<String,Object> params)

Gets entity data (and possibly entities) for a specific entity prefix, entity data contains the reference, URL, display title and optionally the concrete entity and properties
If the entity type indicated by the prefix does not support collections then this will return an empty list

Parameters:

prefix - the string which represents a type of entity handled by an entity provider, the entity prefix to search for the collection of entities in, if the prefix does not support browsing then no entities will be returned

search - a search object which can define the order to return entities, search filters, and total number of entities returned, may be left empty

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

Returns:

a list of entity data objects OR an empty list if none found

Throws:

SecurityException - if the data cannot be accessed by the current user or is not publicly accessible

IllegalArgumentException - if the prefix is invalid or the search is invalid

IllegalStateException - if any other error occurs

formatAndOutputEntity

void formatAndOutputEntity(String reference,
                           String format,
                           List<?> entities,
                           OutputStream output,
                           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

Parameters:

reference - 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 or EntityData objects to create formatted output for, if this is null then the entities will be retrieved based on the reference, if this contains only a single item AND the ref refers to a single entity then the entity will be extracted from the list and encoded without the indication that it is a collection, for all other cases the encoding will include an indication that this is a list of entities

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

params - (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

Throws:

FormatUnsupportedException - if entity cannot handle this format type

IllegalArgumentException - if any of the arguments are invalid

EntityEncodingException - is there is failure encoding the output

IllegalStateException - for all other failures

translateInputToEntity

Object translateInputToEntity(String reference,
                              String format,
                              InputStream input,
                              Map<String,Object> params)

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

Parameters:

reference - 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

params - (optional) set of parameters which may be used to control this request, may be left null if not needed

Returns:

an entity object of the type used for the given reference

Throws:

FormatUnsupportedException - if entity cannot handle this format type

IllegalArgumentException - if any of the arguments are invalid

EntityEncodingException - is there is failure translating the input

IllegalStateException - for all other failures

executeCustomAction

ActionReturn executeCustomAction(String reference,
                                 String action,
                                 Map<String,Object> params,
                                 OutputStream outputStream)

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:

reference - 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

params - (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

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

getTags

Set<String> getTags(String reference)

Deprecated. use TagProvider.getTagsForEntity(String)

setTags

void setTags(String reference,
             String[] tags)

Deprecated. use TagProvider.setTagsForEntity(String, String[])

findEntitesByTags

List<EntityData> findEntitesByTags(String[] tags,
                                   String[] prefixes,
                                   boolean matchAll,
                                   Search search,
                                   Map<String,Object> params)

Search for all entities which have the given tags, can limit the return using the search object

Parameters:

tags - a set of tags associated with entities

prefixes - (optional) a set of unique entity prefixes, limits the search to only include entities in these prefixes, if this is null then all entities and prefixes are searched
NOTE: It is much more efficient to specify prefixes

matchAll - if true then all tags must exist on the entity for it to be matched, if false then the entity just has to have one or more of the given tags

search - (optional) a search object, used to order or limit the number of returned results, restrictions will be typically ignored

params - (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

Returns:

a list of entity search results (contains the ref, url, displayname of the matching entities)

Throws:

IllegalArgumentException - if the tags set is empty or null

browseEntities

List<EntityData> browseEntities(String prefix,
                                Search search,
                                String userReference,
                                String associatedReference,
                                String parentReference,
                                Map<String,Object> params)

Returns the list of entity information (and possibly entities) for a user to view while browsing an entity space, this is specially designed to support browsing and picking entities, not all entities support browsing
If the entity type indicated by the prefix does not support browsing then this will return an empty list

Parameters:

prefix - the string which represents a type of entity handled by an entity provider, the entity prefix to search for browseable entities in, if the prefix does not support browsing then no entities will be returned

search - a search object which can define the order to return entities, search filters, and total number of entities returned, may be left empty

userReference - (optional) the unique entity reference for a user which is browsing the results, this may be null to indicate that only items which are visible to all users should be shown

associatedReference - (optional) a globally unique reference to an entity, this is the entity that the returned browseable data must be associated with (e.g. limited by reference to a location or associated entity), this may be null to indicate there is no association limit

parentReference - (optional) if not null then only the entities which have the referenced entity as a parent will be searched, if null then the parent/child relationship would be ignored when searching browseable entities

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

Returns:

a list of entity data objects which contain the reference, URL, display title and optionally other entity data

Throws:

SecurityException - if the data cannot be accessed by the current user or is not publicly accessible

IllegalArgumentException - if the prefix is invalid or the search is invalid

IllegalStateException - if any other error occurs

getBrowseableEntities

List<BrowseEntity> getBrowseableEntities(String parentPrefix)

For authors of entity browsing systems, this provides a list of all the meta data related to the entities in the system which are Browseable, this provides the root entities when there is no parent prefix provided

Parameters:

parentPrefix - (optional) the parent prefix to get the browseable entities for, if this is null then all the root browseable entities are returned

Returns:

the list of meta data for all entity prefixes that are Browseable