The purpose of this blog post is to introduce new features that extend the HTTP Server Connectivity Plug-in with the ability to respond to a request from the EPL. Prior to 10.3.1 only a basic response was returned to indicate the call had succeeded. This change allows a full request and response protocol to be implemented.
Now, you can configure the HTTP Server transport to allow the response to an HTTP request to be created by an EPL application, instead of automatically returning an empty accepted response.
CONFIGURING THE HTTP SERVER TRANSPORT
You can configure the HTTP Server transport for sending response using new configuration options including automaticResponses for handling responses in EPL . The transport adds a request id, and channel that enables the EPL to route back the responses to the correct source. The payload.channel need to be always “@{httpServer.responseChannel}” , httpServer plugin handles the responses to corresponding payload requests independently. To use these fields we need to make the fields visible to the EPL in the configuration:
mapperCodec:
“*”:
towardsHost:
mapFrom:
- payload.requestId:metadata.requestId
defaultValue:
- payload.channel:“@{httpServer.responseChannel}”
The above maps the incoming request id, and channel into the event payload so that the EPL code can use them below. The request id from the EPL is mapped back into the metadata ready for the transport to return the response correctly.
mapperCodec:
“*”:
towardsTransport:
mapFrom:
- metadata.requestId:payload.requestId
Finally to have the request and response handled by your EPL application you have to set automaticResponses to false in the httpServer transport configuration.
HTTPServerTransport:
automaticResponses: false
Demonstration
To show simply how this works we have created an example application which implements a simple Request/Reply API. The example can be found in this github project . The project consists of an application in EPL, configuration that runs the correlator with the HTTP Server plugin, and a static html page that allows the user to send events to Apama when a button is pressed.
clone the repository (or download a zip and unzip it) and cd into the directory.
git clone https://github.com/sasmitaA/HTTPServerResponseSample.git
cd HTTPServerResponseSample
The port used by the application will be configured in the config/connectivity/HTTPServer/HTTPServer.properties file to a value that you can work with
HTTPServer_port=30002
Now you need to create a deployable version of the application so we can run the correlator.
engine_deploy --outputDeployDir app application
start the correlator using the output directory of the last command
correlator --config app
Now you should be able to point a browser at the correlator
http://localhost:30002/index.html
The page will process responses and display the contents of the response and should look like the image below.
The setup for the HTTP Server connectivity plugin in application\config\connectivity\HTTPServer\HTTPServer.yaml does all the mappings required on the inbound and outbound messages and defined the event type expected and transformations required.
The web page uses jQuery ajax calls (see sendRequest(type) function in html/index.html ) to send in the MoodEvent messages
event MoodEvent {
/** Request ID of the corresponding request object. */
integer requestId;
/** Channel to respond on. */
string channel;
/** request payload */
integer moodId;
}
and asynchronously processes the Success responses
event Success
{
/** Request ID of the corresponding request object. */
integer requestId;
/** Success Message*/
string message;
integer count;
}
When Apama receives the MoodEvent message it will increment a count of the events received, then return a Success message containing the current count and a description of the mood the event represents.
action receiver() {
monitor.subscribe("requests");
on all MoodEvent() as mood {
counter := counter + 1;
if ( mood.moodId = 0 )
{
send Success(mood.requestId,"HAPPY",counter) to mood.channel;
}
else if ( mood.moodId = 1 )
{
send Success(mood.requestId,"SAD",counter) to mood.channel;
}
else
{
send Success(mood.requestId,"ANGRY",counter) to mood.channel;
}
}
}
You can also refer to the sample “httpserver-responses” under samples/connectivity_plugin/application/httpserver-responses in your Apama installation, which demonstrates a generic Create Retrieve Update Delete (CRUD) store implementation.
Conclusion
The ability of your EPL application logic to provide a response to incoming events will increase the flexibility of your applications. It is easy to have bidirectional communications, but they are asynchronous and may require significant configuration effort. If the application logic can reply directly to an event then it doesn’t have to open a connection or potentially even know about how to connect to the source.
As an example, we might want to monitor the operational parameters of devices in a factory. If we can respond to those readings after receiving them, we could throttle or shut down the devices if a bad reading was received. After that response is sent, the application can then call an engineer out. This may protect the machine from further damage while the engineer makes his way to the machine in the real world. The machines or IoT devices could be configured to connect to the application sending their readings and any identifiers. the application then can operate on the stream of data and doesn’t need to know how many or where the sources are.
You can find full documentation on the HTTP server in the online documentation for Apama 10.3.1 under “The HTTP Server Transport Connectivity Plug-in > Handling responses in EPL”.
Feel free to post on our our stack exchange site with any questions you may have about this, or any other, topic.
–Sasmita