org.sakaiproject.entitybroker.entityprovider.annotations

Annotation Type EntityCustomAction

@Retention(value=RUNTIME)
 @Target(value=METHOD)
public @interface EntityCustomAction

This annotation indicates that this method is a custom action from ActionsExecutable, this should not be placed on any methods defined by a capability but should be placed on methods which you want to be exposed as custom actions
By default the name of the method is used as the action key and this will work for read requests (viewKey is set to EntityView.VIEW_SHOW), you can add in action and viewKey annotation params to change those settings
You can describe this action using the key: .action. = description
The methods annotated by this can have the following argument (parameter) types:
(type => data which will be given to the method)
EntityView : the current entity view for this request (contains extension, url, segments)
EntityReference : the current entity reference (prefix and optional id)
String : entity prefix
Search : the search object based on the incoming params
OutputStream : stream to place outbound data (probably binary) into for transmission
Map (String => Object) : a map of the actions parameters (params from the action request)

These methods 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) an EntityData (this is a special object used to wrap the object and provide meta data)
4) a UTF-8 encoded OutputStream or String
5) a List of entity objects
6) an entity object
7) a boolean value (true indicates success and is the same as returning null, false indicates failure and causes an EntityNotFoundException

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
UnsupportedOperationException to indicate that the current action being requested is invalid (typically indicates bad combination of viewKey and action)
IllegalStateException to indicate a general failure has occurred

Author:

Aaron Zeckoski (azeckoski @ gmail.com)

See Also:

CustomAction, ActionsExecutable

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	action (optional) The action key which will be used to trigger the action (e.g. promote) By default the name of the method is used as the action key if this is not set, trigger this action using a URL like: /direct/{prefix}/{name}
String	viewKey (optional) Must match one of the VIEW constants from EntityView, if not set this will default to EntityView.VIEW_SHOW The view type which this action works with (i.e. allowed to trigger the action), this roughly translates to the GET/POST/PUT/DELETE in http e.g.

Element Detail

action

public abstract String action

(optional) The action key which will be used to trigger the action (e.g. promote)
By default the name of the method is used as the action key if this is not set, trigger this action using a URL like: /direct/{prefix}/{name}

Returns:

the name to use for this custom action

Default:

""

viewKey

public abstract String viewKey

(optional) Must match one of the VIEW constants from EntityView, if not set this will default to EntityView.VIEW_SHOW
The view type which this action works with (i.e. allowed to trigger the action), this roughly translates to the GET/POST/PUT/DELETE in http
e.g. GET /user/action would be EntityView.VIEW_LIST while POST /user/aaronz/action would be EntityView.VIEW_NEW, can be null or "" (empty string, for annotations you must use this since null is not a constant) to match all viewkeys (i.e. to allow this action from any http method type and on collections and entities)

Returns:

the view key constant from EntityView

Default:

"show"