Package org.sakaiproject.entitybroker.providers

Interface EntityRESTProvider

  • public interface EntityRESTProvider
    Handles anything REST based that is not part of the core EB registration piece
    Author:
    Aaron Zeckoski (azeckoski @ gmail.com)

    • Method Detail

      • handleEntityRequest

        EntityResponse handleEntityRequest​(String reference,
                                   String viewKey,
                                   String format,
                                   Map<String,​String> params,
                                   Object entity)
        Processes and handles an entity request without requiring servlet processing and a request/response round trip
        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

      • formatAndOutputEntity

        void formatAndOutputEntity​(EntityReference ref,
                           String format,
                           List<EntityData> entities,
                           OutputStream outputStream,
                           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 (This is basically a copy of the code in EntityHandlerImpl with stuff removed)
        Parameters:
        ref - 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 to create formatted output for, if this is null then the entities should be retrieved based on the reference, if this contains only a single item AND the ref refers to a single entity then the entity should be extracted from the list and encoded without the indication that it is a collection, for all other cases the encoding should include an indication that this is a list of entities
        outputStream - the output stream to place the formatted data in, should be UTF-8 encoded if there is char data
        Throws:
        FormatUnsupportedException - if you do not handle this format type (passes control to the internal handlers)
        EntityEncodingException - if you cannot encode the received data into an entity
        IllegalArgumentException - if any of the arguments are invalid
        IllegalStateException - for all other failures

      • translateInputToEntity

        Object translateInputToEntity​(EntityReference ref,
                              String format,
                              InputStream inputStream,
                              Map<String,​Object> params)
        Translates the input data stream in the supplied format into an entity object for this reference
        Parameters:
        ref - 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
        Returns:
        an entity object of the type used for the given reference
        Throws:
        FormatUnsupportedException - if you do not handle this format type (passes control to the internal handlers)
        EntityEncodingException - if you cannot encode the received data into an entity
        IllegalArgumentException - if any of the arguments are invalid
        IllegalStateException - for all other failures

      • handleCustomActionExecution

        ActionReturn handleCustomActionExecution​(ActionsExecutable actionProvider,
                                         EntityReference ref,
                                         String action,
                                         Map<String,​Object> actionParams,
                                         OutputStream outputStream,
                                         EntityView view,
                                         Map<String,​Object> searchParams)
        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:
        actionProvider - the action provider which has declared itself as the handler for this action and prefix
        ref - 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
        actionParams - (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
        view - the entity view corresponding to all data sent in the URL for this action view
        searchParams - any search params which were included in the request
        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

      • encodeData

        String encodeData​(Object data,
                  String format,
                  String name,
                  Map<String,​Object> properties)
        Encode data into a given format, can handle any java object, note that unsupported formats and invalid data will result in an exception
        Parameters:
        data - the data to encode
        format - the format to use for output (from Formats)
        name - (optional) the name to use for the encoded data (e.g. root node for XML)
        properties - (optional) extra properties to add into the encoding, ignored if encoded object is not a map or bean
        Returns:
        the encoded string in the requested format
        Throws:
        UnsupportedOperationException - if the data cannot be encoded
        IllegalArgumentException - if the format requested cannot be encoded because there is no encoder

      • decodeData

        Map<String,​Object> decodeData​(String data,
                                    String format)
        Decode a string of a specified format into a java map of simple objects
        Returned map can be fed into #populate(Object, Map) if you want to convert it into a known object type
        Types are likely to require conversion as guesses are made about the right formats, use of the #convert(Object, Class) method is recommended
        Parameters:
        data - encoded data
        format - the format of the encoded data (from Formats)
        Returns:
        a map containing all the data derived from the encoded data
        Throws:
        UnsupportedOperationException - if the data cannot be decoded
        IllegalArgumentException - if the data cannot be decoded because there is no decoder for that format