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 typeServiceInput
. The same type parameter is used in theExecutionContext
object passed to all methods in theRestService
or theHttpService
interface. The input, or the request, object passed to the service, when invoked, is obtained by calling thegetRequest
method in theExecutionContext
object.@Override public HttpRequest buildRequest(ExecutionContext<ServiceInput> executionContext) { ServiceInput input = executionContext.getRequest(); // Remaining implementation omitted for brevity }
- RSThis 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 thetransformResponse
method in thecom.example.service.rest.ExampleCustomService
class, you will see that theApiResponse
is supplied as the type argument to theHttpResponse
class, which corresponds to the RS type parameter of theRestService
interface.Note: Deserialization occurs according to theContent-Type
header present in HTTP response received from REST API. The type used as the second generic argument toRestService
, or theHttpService
, 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;
}
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.getServiceInterface
method incom.example.service.rest.ExampleCustomService
class returns the class object ofCustomServiceGateway
.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 theServiceExcecutionException
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.