org.sakaiproject.entitybroker.entityprovider.capabilities
Interface ActionsExecutionControllable

All Superinterfaces:

ActionsDefineable, ActionsExecutable, EntityProvider

public interface ActionsExecutionControllable
extends ActionsDefineable

This entity supports custom actions (as defined by RoR and REST microformat: http://microformats.org/wiki/rest/urls)
This is the most complex interface for implementing custom actions but allows the most control also, use ActionsExecutable or ActionsDefineable in most circumstance
This means that there are custom actions which can be invoked on entities or entity spaces, custom actions can augment the current entity operation or they can completely change the behavior and skip the current operation entirely
You can describe the actions using the Describeable key: .action. = description
You can create methods in your entity provider which either end with or use the EntityCustomAction suffix to define the custom actions

Author:

Aaron Zeckoski (azeckoski @ gmail.com)

See Also:

for more details

Field Summary

Fields inherited from interface org.sakaiproject.entitybroker.entityprovider.capabilities.ActionsExecutable

ACTION_METHOD_SUFFIX

Method Summary

Object

executeActions(EntityView entityView, String action, Map<String,Object> actionParams, OutputStream outputStream) This allows the developer to define how to execute custom actions on entities, this method will be called every time a custom action execution is requested, the incoming data provides the context for the action to be executed NOTE: The return data can be complex so please read carefully, entity data is returned as the default for the request if no format is specified

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

defineActions

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

getEntityPrefix

Method Detail

executeActions

Object executeActions(EntityView entityView,
                      String action,
                      Map<String,Object> actionParams,
                      OutputStream outputStream)

This allows the developer to define how to execute custom actions on entities, this method will be called every time a custom action execution is requested, the incoming data provides the context for the action to be executed
NOTE: The return data can be complex so please read carefully, entity data is returned as the default for the request if no format is specified

Parameters:

entityView - an entity view, should contain all the information related to the incoming entity request or URL, includes the entity reference and the requested format information

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

requestValues - this is an array which contains passed in action params, if this is running as a result of an http request this will include all the request variables, otherwise this will just return any custom values needed to execute this action

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

Returns:

this should return one of the following:
1) null (this is ok in most circumstances to indicate the method is done, use an exception to indicate failure)
2) an ActionReturn (this is a special object used to indicate return states and handle binary data)
3) a UTF-8 encoded OutputStream or String
4) a List of entity objects
5) an entity object
6) a boolean value (true indicates success and is the same as returning null, false indicates failure and causes an EntityNotFoundException

Note: Can throw the indicated exceptions and have them translated and handled, all others will pass through Can throw the following exceptions and have them translated and handled, all others will pass through:
EntityNotFoundException to indicate the entity request could not find the data that was requested
IllegalArgumentException to indicate that the incoming params or the request was invalid
FormatUnsupportedException to indicate that the requested format is not supported for this entity request
EntityException to indicate a specific entity failure occurred, can include a response code and error message
SecurityException to indicate that the the current user is no allowed to perform this action
IllegalStateException to indicate a general failure has occurred