Package org.sakaiproject.entitybroker.providers

Interface ExternalIntegrationProvider

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static String SESSION_ID
      The recommended param key to use for sending in session ids in requests

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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​(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​(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 7.

      • 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​(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​(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