www.espertech.comDocumentation

Chapter 6. The HTTP Adapter

6.1. Adapter Overview
6.2. Getting Started
6.2.1. Plugin Loader Configuration
6.2.2. Configuration and Starting via API
6.3. HTTP Input Adapter
6.3.1. HTTP Service
6.3.2. Get Handlers
6.3.3. HTTP Input Limitations
6.4. HTTP Output Adapter
6.4.1. Triggered HTTP Get

This chapter discusses the EsperIO HTTP adapter.

The EsperIO HTTP input and output adapter can be used to send events into an Esper engine instance as well as perform HTTP requests triggered by output events generated by an Esper engine instance.

To send events into an Esper engine instance for processing you declare an HTTP service, which causes the adapter to expose an HTTP protocol server on the configured port to handle incoming requests. Your configuration then attaches Get handlers that receive Get requests that post events into the engine with data from each request.

Output events generated by an Esper engine instance can trigger an HTTP Get operation to a URI of your choice. For this purpose define a triggering event stream and the desired target URI and parameters.

You may configure the EsperIO HTTP adapter either as part of your Esper configuration file in the plugin loader section or via the adapter API. Add the esperio-http-version.jar file to your classpath.

For input adapter operation, add the httpcore-version.jar to your classpath. If using Java NIO add the httpcore-nio-version.jar to your classpath in addition.

For output adapter operation, add the httpclient-version.jar to your classpath.

A sample adapter configuration file is provided in esperio-http-sample-config.xml in the etc folder of the distribution. A configuration file must be valid according to schema esperio-http-configuration-6-0.xsd.

One or more handlers for HTTP Get operations can be installed for a service and are used to receive events.

Define a get element in the adapter configuration file (or use the GetRequest class) for every handler to register for a service.

The synopsis is as follows:

<get service="[service]" pattern="[pattern]"/>

The service attribute value is required and provides the name of the HTTP service to register the Get operation handler for.

A value for the pattern attribute is required and may be either * for all URIs, *[uri] for all URIs ending with the given URI or [uri]* for all URI starting with the given URI.

A sample Get-handler configuration follows:

<get service="myservice" pattern="*"/>

When posting events to the engine, the Get request URI must contain a stream parameter that carries the name of the stream (event type) to insert into. Each event property to be populated in the input event must be part of the Get request parameter values.

For example, the URI http://localhost:8079/sendevent?stream=MyFirewallEvent&name=Joe&changed=true entered into a browser sends an input event of type MyFirewallEvent setting the name property of the event to "Joe" and the changed property of the event to true.

Note that if your target type is a Java object event, your event class must provide setter-methods according to JavaBean conventions. The event class should also provide a default constructor taking no parameters. If your event class does not have a default constructor, your application may configure a factory method via ConfigurationEventTypeLegacy.

This facility instructs the adapter to perform an HTTP Get request when a triggering event occurs, passing event properties as URI parameters.

Define a request element in the adapter configuration file (or use the Request class) for every HTTP Get to execute.

The synopsis is as follows:

<request stream="[stream]" uri="[uri_with_placeholders]"/>

A value for the stream attribute is required and provides the name of the stream that triggers the HTTP Get. The adapter expects a stream by this name to exist at adapter start time.

The uri_with_placeholders attribute value is required. You may place event property placeholders inside the URI to format the URI as needed. Placeholders are of the format ${property_name}.

A sample request configuration follows:

<request stream="TriggerFirewallStream" uri="http://myremotehost:80/root/event"/>

Assuming the HttpTriggerStream has event properties name and ipaddress then a sample Get request URI is as follows:

http://myremotehost:80/root/event?stream=TriggerFirewallStream&name=Joe&ipaddress=120.1.0.0

You may parameterize the URI via placeholders by placing ${property_name} and the special placeholder ${stream} into the URI string.

The next example configuration defines URI parameters via placeholder:

<request stream="TriggerFirewallStream" uri="http://myremotehost:80/root/${stream}?violation&amp;name=${name};violationip=${ipaddress}"/>

The URI generated by the adapter:

http://myremotehost:80/root/TriggerFirewallStream?violation&name=Joe&violationip=120.1.0.0