HTTP Server EPL responses

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:

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.

Finally to have the request and response handled by your EPL application you have to set automaticResponses to false in the httpServer transport configuration.

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.

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

Now you need to create a deployable version of the application so we can run the correlator.

start the correlator using the output directory of the last command

Now you should be able to point a browser at the correlator

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

and asynchronously processes the Success responses

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.

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 for 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 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 tpost on our our stack exchange site with any questions you may have about this, or any other, topic.

–Sasmita