Mapping events between EPL and HTTP

The HTTP client accepts requests with metadata fields indicating how to make the request and a binary payload to be submitted as the body of the request. 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.getUnique(); // 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 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 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	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.

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.

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