org.sakaiproject.entitybroker.providers
Interface ExternalIntegrationProvider

public interface ExternalIntegrationProvider

Field Summary

static String

SESSION_ID The recommended param key to use for sending in session ids in requests

Method Summary

Object	fetchEntity(String reference) Fetches a concrete object representing this entity reference from an external system Note that this object 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 should return null if the entity exists but has no available object
<T> T	findService(Class<T> type) Allows services in the external system to be located (this is used to find external providers for overriding the default internal services)
void	fireEvent(String eventName, String reference) Fires events from EB using an external event system You can assume the eventName is not null and the reference has been validated and normalized NOTE: if you have no way to handle external events then throw UnsupportedOperationException
<T> T	getConfigurationSetting(String settingName, T defaultValue) Retrieves settings from the configuration service (sakai.properties)
String	getMaxJSONLevel() Gets the entitybroker.maxJSONLevel config string from sakai.properties via ServerConfigurationService.
String	getServerUrl() Gets the full server URL for the server which this is being used on
String	handleEntityError(javax.servlet.http.HttpServletRequest req, Throwable error) Handles an error which occurs while processing an entity request, e.g. by sending an email and logging extra info about the failure
void	handleUserSessionKey(javax.servlet.http.HttpServletRequest req) Allows the external system to create a session based on a passed in session key (or other data in the request), no returns are necessary and this method can simple be left unimplemented if it is not used Most likely all requests will not include session keys so you should not fail if one is not set in most cases

Field Detail

SESSION_ID

static final String SESSION_ID

The recommended param key to use for sending in session ids in requests

See Also:

Constant Field Values

Method Detail

findService

<T> T findService(Class<T> type)

Allows services in the external system to be located (this is used to find external providers for overriding the default internal services)

Type Parameters:

T -

Parameters:

type - the service API class

Returns:

the service OR null if it does not exist

fireEvent

void fireEvent(String eventName,
               String reference)

Fires events from EB using an external event system
You can assume the eventName is not null and the reference has been validated and normalized
NOTE: if you have no way to handle external events then throw UnsupportedOperationException

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

Throws:

IllegalArgumentException - if the event arguments are invalid or the event cannot be thrown

UnsupportedOperationException - if the external system does not handle events

getServerUrl

String getServerUrl()

Gets the full server URL for the server which this is being used on

Returns:

the full server URL (default: http://localhost:8080), should not include a trailing slash

Throws:

UnsupportedOperationException - if the external system cannot handle this

getMaxJSONLevel

String getMaxJSONLevel()

Gets the entitybroker.maxJSONLevel config string from sakai.properties via ServerConfigurationService. Defaults to 5.

fetchEntity

Object fetchEntity(String reference)

Fetches a concrete object representing this entity reference from an external system
Note that this object 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 should return null if the entity exists but has no available object

Parameters:

reference - a string representing a unique reference to an entity (e.g. /type/id/extra)

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

UnsupportedOperationException - if the external system cannot handle this

IllegalStateException - if any other error occurs

handleEntityError

String handleEntityError(javax.servlet.http.HttpServletRequest req,
                         Throwable error)

Handles an error which occurs while processing an entity request, e.g. by sending an email and logging extra info about the failure

Parameters:

req - the current request

error - the current error that occurred

Returns:

the comprehensive error message to send back to the requester

Throws:

UnsupportedOperationException - if the external system cannot handle this

handleUserSessionKey

void handleUserSessionKey(javax.servlet.http.HttpServletRequest req)

Allows the external system to create a session based on a passed in session key (or other data in the request), no returns are necessary and this method can simple be left unimplemented if it is not used
Most likely all requests will not include session keys so you should not fail if one is not set in most cases

Parameters:

req - the request as it is coming in (before any other processing has occurred)

Throws:

IllegalArgumentException - if this request is invalid in some way

SecurityException - if this request is not allowed for security reasons

getConfigurationSetting

<T> T getConfigurationSetting(String settingName,
                              T defaultValue)

Retrieves settings from the configuration service (sakai.properties)

Parameters:

settingName - the name of the setting to retrieve, Should be a string name: e.g. auto.ddl, mystuff.config, etc.

defaultValue - a specified default value to return if this setting cannot be found, NOTE: You can set the default value to null but you must specify the class type in parens

Returns:

the value of the configuration setting OR the default value if none can be found