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 Asset Picker 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 the input given to the service being implemented.

• String getEndpointUrl(ExecutionContext<RQ> executionContext)

  This method returns an absolute endpoint URL of the service running on target system. Base URL of target system is configured in Unica Platform. Hence, the plugin need not make any provision to configure that in any way. ExecutionContext object supplied to this method provides a way to read the base URL so that the absolute URL of the service can be composed. Also look at how the getEndpointUrl method is defined in com.aem.service.AemSimpleSearchService class inside aem-integration project. As it can be noted, the base URL is obtained from ExecutionContext by navigating through InstanceConfig object. The InstanceConfig holds all the configurations made in Unica Platform for the very target system instance your service will communicate with. This is a mandatory method for the service to implement.

• HttpMethod getHttpMethod()

  This method should return one of the values from the HttpMethod enum supplied with the Asset Picker SDK. As the name goes, this method tells which HTTP request method should be used during HTTP interaction with target system. This is a mandatory method for service to implement.

• Map<String, Object> getHeaders(ExecutionContext<RQ> executionContext)

  This optional method can be overridden by the service if it wants to include any HTTP request headers in the outgoing HTTP call. Return value must be a Map instance, wherein HTTP 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 implementation, no custom headers will be sent along with the outgoing HTTP request.

  Note: Although the Map returned by this method accepts values of type Object (or its subtypes), only String objects are supported as of current implementation of Asset Picker. 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. 

  • Content-Type HTTP header must be populated as contentType key due to special considerations in underlying framework.
  • application/json is the default contentType for RESTful services, if none is supplied by the getHeaders method.
• Object buildRequest(ExecutionContext<RQ> executionContext)

  This is also an optional method. If the target service expects any request body, then this method can be overridden to build the desired HTTP request body. Return type of this method is Object, and hence any type of valid request body can be supplied so long as relevant Content-Type header is populated using the getHeaders method.

  Note: Jackson and JAXB Support - Object serialization using Jackson and JAXB is completely supported by Asset Picker. Thus, appropriately decorated object with Jackson or JAXB annotations can be returned from this method. In such case, no Content-Type header is required to be populated explicitly. Asset Picker takes care of supplying appropriate header during HTTP invocation. Serialization of supplied object into the request body is also handled by Asset Picker itself, hence no explicit serialization is required.

  In the absence of this implementation, empty request body will be sent along with the outgoing HTTP request.

• Object transformResponse(RS response, ExecutionContext<RQ> executionContext)

  This optional method transforms the HTTP response into a desired format. The additional, first argument to this method is the HTTP response body received from the target service. This argument is a generic type and is decided based on the actual type parameter used while implementing the service. This response can be any object, either a String containing the text as received from the service, a byte array containing the response contents or a deserialized object representing the response JSON/XML.

  Note: Jackson and JAXB Support - Object deserialization using Jackson and JAXB is completely supported by Asset Picker. 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 Asset Picker, 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 Asset Picker.

  In addition to these methods, there is one more method the getServiceInterface inherited from com.hcl.unica.cms.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.

  Asset Picker 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 Asset Picker. Methods listed earlier must not throw any checked exception. Unchecked exceptions can be thrown if required.