Apama 10.15.0 | Connecting Apama Applications to External Components | Standard Connectivity Plug-ins | The HTTP Client Transport Connectivity Plug-in | Mapping events between EPL and HTTP client requests
 
Mapping events between EPL and HTTP client requests
 
Distinguishing response types
Handling HTTP headers
Handling HTML form encoding
Handling HTML form encoding using a predefined generic event definition
Mapping the body
Dealing with cookies
Providing HTTP query parameters
Example mapping rules
The information in this section applies when you have added the HTTP Client connectivity bundle with the JSON with application-specific event definitions option in Software AG Designer.
Note: 
The JSON with generic request/response event definitions option provides predefined configurations and events for the HTTP client transport which already define the mapping between EPL and the HTTP client requests, and you need not do anything. See Using predefined generic event definitions to invoke HTTP services with JSON and string payloads for further information.
The HTTP client accepts requests with metadata fields indicating how to make the request and a binary or dictionary payload to be submitted as the body of the request. Each entry in the dictionary payload should have a string key and either a string or a binary value. If the payload is a dictionary, then metadata.contentType must be set to either multipart/form-data or application/x-www-form-urlencoded. A response contains a binary payload which is the body of the response and further metadata fields describing the response. For the responses to be useful to EPL, they must be converted into the format expected by Apama. This is done using the Classifier codec, Mapper codec and other codecs (see Codec Connectivity Plug-ins).
In order for EPL to connect a response event to the correct request event, each request contains a top-level requestId field in the metadata. This is returned verbatim in the corresponding response event along with the path and method copied from the request. If these are mapped to or from EPL, then they can be used for a request-response protocol in EPL. For example:
integer id := integer.incrementCounter("HTTPClient.requestId"); // get a
// unique ID to differentiate different responses
// listen for success and failure responses
on Response(id=id) as response and not Error(id=id) {
// handle successful requests
}
on Error(id=id) as error and not Response(id=id) {
// handle unsuccessful requests
}
send Request(id, .../* more request data here */) to "httpchannel";
// send the request
The event types used in EPL should be specific to your application and then mapped in the chain to the fields expected by the HTTP client.
The following fields in each event are read by the HTTP client. Field names containing periods (.) indicate nested map structures within the metadata. This nesting is automatically handled by the Mapper codec, and fields can be referred to there just using these names (see also The Mapper codec connectivity plug-in).
Field
Description
payload
Binary or dictionary payload to submit with the request.
metadata.requestId
Required. A request ID (string) to include in the response.
metadata.http.method
Required. The HTTP method to use: GET, POST, PUT or DELETE.
metadata.http.path
Required. URI (string) on the host to submit the request to.
metadata.concurrencyControlKey
Only used when the numClients configuration option is greater than 1 for this instance of the HTTP client transport.
Serializes all requests with the given key. The key can be set to one of the following:
*Empty, unset or the empty string (""): no waiting for any other requests to complete (default).
*Any other value: this request waits until any earlier requests with the same key have completed and causes any later requests with the same key to wait until it has completed. This means that only one request can be in-progress at a time for a given concurrency control key.
Note: 
While any type of value is supported in the concurrencyControlKey, it is recommended to only use string or integer types.
For examples and use in conjunction with concurrencyControlFlush, see also Executing HTTP requests concurrently.
metadata.concurrencyControlFlush
Evaluates to true or false:
*false (or empty, unset, empty string (""), "false" string): no waiting for any other requests to complete (default).
*Any other value: delays this request from starting until all earlier requests have completed (regardless of concurrencyControlKey). Note that later requests are permitted to start while the flush-enabled request is still executing.
For examples and use in conjunction with concurrencyControlKey, see also Executing HTTP requests concurrently.
metadata.http.headers.content-encoding
The Content-Encoding to be applied to the entity-body. This can be one of the following: gzip, deflate or identity. When an unsupported content encoding is specified, the HTTP request is ignored and an error message is logged.
metadata.http.headers.keyname
An HTTP header (string) to set in the request. See also Handling HTTP headers.
metadata.http.cookies.keyname
An HTTP cookie (string) to set in the request. See also Dealing with cookies.
metadata.http.queryString.keyname
An HTTP query parameter (string) to be encoded as part of the path in the URI. See also Providing HTTP query parameters.
metadata.charset
Describes the format of the payload (string). See also Handling HTTP headers.
metadata.contentType
Describes the format of the payload (string). See also Handling HTTP headers.
metadata.http.form.name.contentType
The media type of the form data. See also Handling HTML form encoding.
metadata.http.form.name.charset
The encoding of the form data. See also Handling HTML form encoding.
metadata.http.form.name.filename
The file name of the form data. See also Handling HTML form encoding.
The responses returned from the HTTP client contain the following fields:
Field
Description
payload
Binary payload received in the response. May be an empty buffer if no response, or null in some error cases.
metadata.requestId
The request ID (string) from the request. Always present in the response.
metadata.http.method
The HTTP method from the request: GET, POST, PUT or DELETE. Always present in the response.
metadata.http.path
The HTTP path (string) from the request. Always present in the response.
metadata.http.statusCode
HTTP status code (integer). Code 200 indicates success. All other codes indicate errors. Always present in the response. See also Distinguishing response types.
metadata.http.statusReason
HTTP status reason (string). Always present in the response.
metadata.http.headers.keyname
The HTTP header (string) returned by the response. See also Handling HTTP headers.
metadata.http.cookies.keyname
An HTTP cookie (string) being set by the response. Only present if this is in the response headers. See also Dealing with cookies.
metadata.charset
Describes the format of the payload (string). Only present if this is in the response headers. See also Handling HTTP headers.
metadata.contentType
Describes the format of the payload (string). Only present if this is in the response headers. See also Handling HTTP headers.
You can use the Mapper codec to move things between the payload and the metadata, and vice versa. For example:
startChains:
HTTPClientChain:
- apama.eventMap
- mapperCodec:
MyRequest:
towardsTransport:
mapFrom:
- metadata.http.path: payload.path
- metadata.requestId: payload.id
- payload: payload.body
defaultValue:
- metadata.http.method: GET
- metadata.http.headers.accept: application/json
MyResponse:
towardsHost:
mapFrom:
- payload.body: payload
- payload.path: metadata.http.path
- payload.id: metadata.requestId
Error:
towardsHost:
mapFrom:
- payload.message: metadata.http.statusReason
- payload.id: metadata.requestId
- payload.path: metadata.http.path
- payload.code: metadata.http.statusCode
- classifierCodec:
rules:
- MyResponse:
- metadata.http.statusCode: 200
- Error:
- metadata.http.statusCode:
- stringCodec
- HTTPClientTransport
The above example also demonstrates how to use the Classifier codec to split responses into normal responses and error responses based on the status code (see also Distinguishing response types).
Examples of using the Mapper and Classifier codecs to set these fields can be found in Example mapping rules.