Async Service Channels - learn-tibco-cep/tutorials GitHub Wiki
The Async Service handler interacts with clients and external service providers by using 4 FTL endpoints, which are configured as BE channel destinations. This page describes the specifications of the FTL channel destinations.
FTL Connection and Channels
FTL Connection is defined as a BE shared resource. The FTL server URL can be configured at deployment time as a global variable FTL/Server_URL.
Client Channel is defined to hold FTL endpoints of client request and response.
Service Channel is defined to hold FTL endpoints of service request and response.
Both channels share the same FTL connection. At runtime, the BE engine will connect to all 4 FTL endpoints, and thus it does not make much difference to define 2 FTL channels, or define a single FTL channel that holds all 4 FTL destination.
However, grouping FTL endpoints into multiple channels gives you more flexibility to disable some channels in a BE engine, and thus remove the dependency of the engine on some FTL endpoints. For example, the Mock Service can be configured to disable the Client Channel since a service provider would not need to access the endpoints of client request and response. Refer the Tips section below for how to disable a channel.
Client Channel
This channel specifies FTL endpoints for client request and response messages. Both client messages are sent to a shared endpoint in the default FTL application, which means that when multiple message consumers are running, each message will be sent to only one of the consumers with the same durable name.
Client Request
This FTL endpoint is defined for a client, e.g., Test Driver, to send a ClientRequest message to one of the Async Service handlers. It is configured as follows.
| Property | Value | Comments |
|---|---|---|
| Name | clientRequest | Name of the channel destination |
| Default Event | /Events/ClientRequest | Deserialize FTL message to this type if event type is not specified |
| Application Name | default | FTL application name. default is pre-configured by FTL installation. |
| Endpoint Name | shared | FTL endpoint. shared is pre-configured by FTL for behavior of messaging queues. |
| Instance Name | default | FTL application instance. default is pre-configured by FTL installation. |
| Format Name | ClientRequest | FTL message format. FTL recognizes dynamic format, so it is not necessary to configure it in FTL. |
| Content Matcher | {"_nm_": "ClientRequest"} |
FTL message content filter. It receives only messages of specified BE event type. |
| Durable Name | ClientRequest | FTL durable name. Must specify the same name for load-balancing consumers of the same type. |
Client Response
This FTL endpoint is defined for an Async Service handler to send a ClientResponse message one of the client instances, e.g., Test Driver. It is configured as follows.
| Property | Value | Comments |
|---|---|---|
| Name | clientResponse | Name of the channel destination |
| Default Event | /Events/ClientResponse | Deserialize FTL message to this type if event type is not specified |
| Application Name | default | FTL application name. default is pre-configured by FTL installation. |
| Endpoint Name | shared | FTL endpoint. shared is pre-configured by FTL for behavior of messaging queues. |
| Instance Name | default | FTL application instance. default is pre-configured by FTL installation. |
| Format Name | ClientResponse | FTL message format. FTL recognizes dynamic format, so it is not necessary to configure it in FTL. |
| Content Matcher | {"_nm_": "ClientResponse"} |
FTL message content filter. It receives only messages of specified BE event type. |
| Durable Name | ClientResponse | FTL durable name. Must specify the same name for load-balancing consumers of the same type. |
Service Channel
This channel specifies FTL endpoints for service request and response messages. Service request messages are sent to a shared endpoint in the default FTL application, and so multiple service provider instances can be deployed to share the load, but the service response endpoint is configurable and it depends on the deployment architecture of the Async Service handlers.
Service Request
This FTL endpoint is defined for an Async Service handler to send a ServiceRequest message to one of the service providers, e.g., Mock Service. It is configured as follows.
| Property | Value | Comments |
|---|---|---|
| Name | serviceRequest | Name of the channel destination |
| Default Event | /Events/ServiceRequest | Deserialize FTL message to this type if event type is not specified |
| Application Name | default | FTL application name. default is pre-configured by FTL installation. |
| Endpoint Name | shared | FTL endpoint. shared is pre-configured by FTL for behavior of messaging queues. |
| Instance Name | default | FTL application instance. default is pre-configured by FTL installation. |
| Format Name | ServiceRequest | FTL message format. FTL recognizes dynamic format, so it is not necessary to configure it in FTL. |
| Content Matcher | {"_nm_": "ServiceRequest"} |
FTL message content filter. It receives only messages of specified BE event type. |
| Durable Name | ServiceRequest | FTL durable name. Must specify the same name for load-balancing consumers of the same type. |
Service Response
This FTL endpoint is defined for a service provider, e.g., Mock Service, to send a ServiceResponse message to one of the Async Service handlers. It is configured as follows.
| Property | Value | Comments |
|---|---|---|
| Name | serviceResponse | Name of the channel destination |
| Default Event | /Events/ServiceResponse | Deserialize FTL message to this type if event type is not specified |
| Application Name | default | FTL application name. default is pre-configured by FTL installation. |
| Endpoint Name | %%FTL/ResponseEndpoint%% | FTL endpoint. Variable can be configured to default or shared depending on required behavior of messaging topic or queue. |
| Instance Name | default | FTL application instance. default is pre-configured by FTL installation. |
| Format Name | ServiceResponse | FTL message format. FTL recognizes dynamic format, so it is not necessary to configure it in FTL. |
| Content Matcher | {"_nm_": "ServiceResponse"} |
FTL message content filter. It receives only messages of specified BE event type. |
| Durable Name | %%FTL/ResponseDurable%% | FTL durable name. Set the variable to ServiceResponse only if shared endpoint is used. |
The configuration of FTL endpoint and durable name of this channel destination depends on the deployment architecture of the Async Service handlers. This tutorial is configured to use in-memory object management, which stores handlers in the process memory of individual BE engines, and thus handlers are not shared by multiple engines. With this configuration, service responses must be sent to all Async Service instances by using the default FTL pubsub endpoint, and so one of the instances is the owner of the correlated handler that would be able to process the service response, while all other instances would ignore the response message.
The preprocessor function onServiceResponse also supports another common deployment scenario where handlers are persisted in a cache cluster or a persistent store, and so they are shared by multiple BE engines. With this configuration, any Async Service instance can fetch a correlated handler from the cache or persistent store, and then process the service response. In this case, service responses should be routed to only one of the instances by using the shared FTL endpoint.
The following table summarizes the global variables that can be configured for either scenario.
| Global Variable | In-memory | Cache or Store |
|---|---|---|
| Agent/LockLocal | true | false |
| FTL/ResponseEndpoint | default | shared |
| FTL/ResponseDurable | ServiceResponse |
Tips
Following practical tips may be helpful for configuration of BE channels and destinations.
Use default FTL application instance for BE application development and testing
FTL installation provides a pre-configured default application and endpoints that can be used for application development and testing. BE application developers do not have to learn any details about FTL administration, because the pre-configured FTL default application would provide all common messaging features required by a BE application.
However, for FTL servers shared by multiple client applications in production, it would be recommended to configure a new FTL application, and use it to setup BE channel and destinations, and so you can view and find related BE application clients more clearly in the FTL server UI.
Choose a threading model for an inbound channel destination
You can select appropriate threading model for each input channel destination in the CDD file, e.g. Demo.cdd.
The most common threading model is Shared Queue, which is used by default. With this option, event preprocessors will share the same pool of threads no matter which channel destination is the source of input. The thread count of the pool is configured in the inference agent class (not the individual input destinations). This option is good for most use cases, as long as you setup the pool size appropriately considering the total rate of input events, the elapsed time processing each event, and the available hardware threads.
Some channel destinations may require special treatment due to its high priority or high event rate. You may choose Destination Queue for such destinations. This option will assign a dedicated thread pool to the destination, and the thread count of the pool can be configured for individual input destinations.
HTTP channel destination is multi-threaded itself, and response to HTTP requests are usually returned on the same thread. For such destinations, you should use the Caller's thread.
Use BE event property _nm_ or _ns_ as FTL content matcher filter
As described in Event Tips, FTL messages published by BE applications will contain additional fields of _nm_ and _ns_ describing BE event types. Similar message headers are also included for JMS protocol, although the JMS headers can be disabled if application does not use these headers.
This tutorial uses the _nm_ field to define FTL content matchers, which assumes that this field exists in all inbound messages. It is a fine strategy if we know that the message producer is also a BE application. When non-BE producers are involved, however, we may not make such assumption, in which case, we may have to choose a more descriptive message field for FTL content matchers.
Disable channels for an agent class
At its startup, a BE engine will start all FTL endpoints defined in the application. It may create some unnecessary dependencies on resources that the engine does not actually use. You may remove such dependencies by setting the property be.channel.deactivate to a comma-delimited list of disabled channels. For example, we specified the following property in Demo.cdd under the definition of the agent class test-driver:
be.channel.deactivate=/Channels/FTLService
This property will remove the endpoints of service request and response from the startup of Test Driver instances.
If Ignite cache agent is used, you can disable all channels in cache engines by setting the following property:
be.engine.cacheServer.channel.disable=true