Mapping events between EPL and HTTP client requests
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.
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.http.headers.keyname | |
metadata.http.cookies.keyname | |
metadata.http.queryString.keyname | |
metadata.charset | |
metadata.contentType | |
metadata.http.form.name.contentType | |
metadata.http.form.name.charset | |
metadata.http.form.name.filename | |
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 | |
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:
http:
- 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
- httpClient
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.