RESTful approach

The com.example.service.rest.CustomService class helps you understand REST based service implementation.

This class is an implementation of RestService interface, and thus represents a REST based service. Since REST is completely based on HTTP standards, the RestService interface in Content Integration SDK is extended from HttpService interface and is defined as a marker interface. The RestService interface does not declare any additional method of its own. Listed below are the methods declared in HttpService interface, which REST based service implementation must implement. Not all methods are mandatory. All methods accept ExecutionContext object, which contains all the contextual information necessary for every method to perform its designated task. The generic type parameter to the ExecutionContext class represents the type of input required for the respective service on its invocation.

  • HttpRequest buildRequest(ExecutionContext<RQ> executionContext)
    This is a mandatory method. It returns an object of type com.hcl.unica.system.model.request.HttpRequest. The HttpRequest class provides builder API to construct the object with applicable details. This object comprises all the required details for making an HTTP request, such as endpoint URL, HTTP method, HTTP headers, and HTTP request body. The HttpRequest builder API accepts the following arguments:
    • String endpointUrl

      An absolute URL to target API.

    • HttpMethod httpMethod

      HTTP method to be used for making API call. Must be one of the values from com.hcl.unica.system.integration.service.HttpMethod enum.

    • Optional<Map<String, Object>> headers

      An optional Map of HTTP headers. It can include standard as well as custom HTTP headers. Header names must be specified in terms of Map keys, and header values must be supplied as corresponding values in the Map. In the absence of this optional value, no custom headers will be sent along with the outgoing HTTP request.

      Note: Although the header Map accepts values of type Object (or its subtypes), only String objects are supported as of current implementation of Content Integration Framework. Any other type of value will be ignored, and following warning will be logged:
      Header '{HEADER_NAME}' with value ‘{TO_STRING_REPRESENTATION}' will not be set since it is not a String and no Converter is available.
    • Optional<?> payload

      If the target service expects any request body, then this argument can be supplied with the desired HTTP request body. It can be any valid object so long as appropriate Content-Type header is supplied in the headers Map. In the absence of this argument, empty request body will be sent along with the outgoing HTTP request.

      Note: Jackson and JAXB Support: Object serialization using Jackson and JAXB is completely supported by the Content Integration Framework. Thus, appropriately decorated object with Jackson or JAXB annotations can be set as the request payload. In such case, appropriate Content-Type header must be specified in headers Map. Serialization of supplied object into the request body is handled by the Content Integration Framework, hence no explicit serialization is required.
  • Object transformResponse(HttpResponse<RS> response, ExecutionContext<RQ> executionContext)

    This optional method transforms the HTTP response into a desired format. The first argument, com.hcl.unica.system.model.response.HttpResponse, to this method, represents the response received from the target system. The generic type parameter to the HttpResponse class represents the type of response body, or response payload, expected from the remote API. Response payload can be of any type, such as a String containing the entire text as received from the service, a byte array containing the response body, or a deserialized POJO representing the response JSON/XML. In addition to the response payload, HttpResponse object can be used to obtain response headers, status code, and cookies.

    Note: Jackson and JAXB Support: Object deserialization using Jackson and JAXB is completely supported by Content Integration Framework. Thus, appropriately decorated object with Jackson or JAXB annotations can be accepted as an argument to this method. Deserialization of response body into specified type is handled by Content Integration Framework, hence no explicit deserialization is required during response transformation inside this method.

    In the absence of this implementation, no implicit transformation is performed by the Content Integration Framework.

    In addition to these methods, there is one more method the getServiceInterface inherited from com.hcl.unica.system.integration.service.AbstractService interface, that needs to be implemented by the service. But its implementation is more relevant to the service invocation rather than service implementation.

    Content Integration Framework takes care of real HTTP interaction with target system and simply consults with service object to obtain earlier mentioned details.

    Error Handling: Errors or exceptions received during HTTP call are handled by the Content Integration Framework. Methods listed earlier must not throw any checked exception. Unchecked exceptions can be thrown if required.