Generic type parameters

Generic type parameters are used for implementing service interfaces.

A service that resides in a plugin is just a programming unit, which takes some input and returns the expected output. Similarly, the REST API, wrapped by our service, asks for the required input (request body, headers, cookies, and query parameters) and produces the desired response (response body, headers, and cookies). It requires certain generic notations for the inputs and outputs exchanged during end-to-end logical flow.

Content Integration Framework uses RQ type parameter to denote the type of input supplied to the service on its invocation. Here, the RS type parameter is used to denote either the type of object returned by the Functional service or the type of response body returned by the remote REST API invoked using RESTful approach. The purpose of RS might change based on where it is used, but it always indicates the return value of something.

RestService<RQ, RS>

Refer the com.example.service.rest.ExampleCustomService class from the asset-integration-starter project to understand the type parameters used in the RestService inteface. RestService is just a marker interface extended from HttpService. The definition of these type parameters is similar for the HttpService too.

RQ
A service requires an input to perform its operation. RQ corresponds to the type of input, or request, the service requires when invoked. The com.example.service.rest.ExampleCustomService takes an input of type ServiceInput. The same type parameter is used in the ExecutionContext object passed to all methods in the RestService or the HttpService interface. The input, or the request, object passed to the service, when invoked, is obtained by calling the getRequest method in the ExecutionContext object.
```
@Override
	public HttpRequest buildRequest(ExecutionContext<ServiceInput> executionContext) {
		ServiceInput input = executionContext.getRequest();
		// Remaining implementation omitted for brevity
	}
```
RS
This parameter type corresponds to the type of response (post deserialization) received from the remote REST API. Service implementation chooses this parameter based on the kind of object it wants to work with in transformResponse method. If you look at the signature of the transformResponse method in the com.example.service.rest.ExampleCustomService class, you will see that the ApiResponse is supplied as the type argument to the HttpResponse class, which corresponds to the RS type parameter of the RestService interface.
Note: Deserialization occurs according to the Content-Type header present in HTTP response received from REST API. The type used as the second generic argument to RestService, or the HttpService, must be appropriately annotated if Jackson or JAXB deserialization is expected.

FunctionalService<RQ, RS>

FunctionalService interface is analogous to the java.util.function.Function interface from the Standard Java Library. The type parameters of FunctionalService have similar semantics as the type parameters of java.util.function.Function interface.

RQ
Represents the type of input given to the service upon invocation.
RS
Represents the type of value returned by the service upon completion.

ServiceGateway<RQ, RS>

ServiceGateway is used as programmatic interface to services. ServiceGateway indicates the types of input & output/return values of the given service. Implementation of getServiceInterface method is mandatory for all services (except inbound HTTP service & Kafka consumer/listener services) & is supposed to return class object of subtype of ServiceGateway parameterized with appropriate input & output types. ServiceGateways & implementation for getServiceInterface already exists for all the standard services. All custom services implemented by the plugin must adhere to this contract. The definition of com.hcl.unica.system.integration.service.gateway.ServiceGateway is as follows:

public interface ServiceGateway<RQ, RS> {
		public RS execute(RQ request) throws ServiceExecutionException;
	}

Semantics for the type parameter RQ is the same as mentioned earlier. The other type parameter, RS represents the output of the service that resides in the plugin. It does not represent the response received from remote REST API or any other target systems. For the com.example.service.rest.ExampleCustomService class, the CustomServiceGateway is defined as the child interface of ServiceGateway by using ServiceInput and ServiceOutput type arguments because the service receives an input of type ServiceInput and returns the value of type ServiceOutput on completion. For RESTful implementations, execution of transformResponse method marks the service completion in case of successful response from respective system.

Note:

getServiceInterface method in com.example.service.rest.ExampleCustomService class returns the class object of CustomServiceGateway. ServiceGateway interface (or its child interface) provides information about the input and the output of service implementation. ServiceGateway interface is further used to contain the reference of service instance and invoke its execution.
By obtaining reference to the ServiceGateway instance of any service thus implemented, execute(RQ request) method can be invoked to execute the service. Note that the execute method may throw the ServiceExcecutionException if anything goes wrong during service execution. Details on service invocation and exception handling will be provided in topics that follow.

ObjectEventInterpreterService<T>

ObjectEventInterpreterService is used for implementing Webhooks to listen to the events coming over HTTP from external systems. The ObjectEventInterpreterService<T> is subtype of InboundHttpService<RQ, RS>. The RQ & RS type parameters in InboundHttpService represents the type of deserialized request expected by the inbound HTTP service & the type of response (prior to serialization) returned by this service. ObjectEventInterpreterService is a specialized version of InboundHttpService wherein type parameter T is analogous to RQ (the type of deserialized request). Services implementing ObjectEventInterpreterService can only specify the request type since response is managed by the Content Integration Framework itself. For example, refer to the com.example.service.rest.events.ExampleEventInterpreterService service from asset-integration-starter project.

KafkaConsumerService<K, V, RS>

KafkaConsumerService is used for implementing Kafka event listener/interpreter services. The type parameters K & V represents the Key & Value of incoming Kafka message. For example, refer to the com.example.service.kafka.events.consumer.ExampleKafkaEventInterpreterService service from asset-integration-starter project.

AbstractKafkaProducerService<K, V>

AbstractKafkaProducerService is used for implementing Kafka message publisher services. The type parameter K & V represents the Key & Value of outgoing Kafka message. For example, refer to the com.example.service.kafka.events.producer.ExampleKafkaProducerService service from asset-integration-starter project.