esper.codehaus.org and espertech.comDocumentation
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-5-0.xsd.
You may place the configuration XML directly into your Esper configuration file as the example below shows:
<esper-configuration>
<plugin-loader name="EsperIOHTTPAdapter"
class-name="com.espertech.esperio.http.EsperIOHTTPAdapterPlugin">
<config-xml>
<esperio-http-configuration>
.....as outlined below or contents of esperio-http-sample-config.xml here...
</esperio-http-configuration>
</config-xml>
</plugin-loader>
</esper-configuration>Alternatively you can provide a URL in the Esper configuration file to point to your adapter configuration file:
<esper-configuration>
<plugin-loader name="EsperIOHTTPAdapter"
class-name="com.espertech.esperio.http.EsperIOHTTPAdapterPlugin">
<init-arg name="esperio.http.configuration.file"
value="file:/path/esperio-http-sample-config.xml" />
</plugin-loader>
</esper-configuration>If using Spring or if your application requires API access, the following code snippet configures and starts the adapter via API.
The class for configuring an EsperIO HTTP adapter is com.espertech.esperio.http.config.ConfigurationHTTPAdapter. The adapter class itself is
EsperIOHTTPAdapter.
The code snippet below is a sample that configures using driver manager and starts the adapter via API:
ConfigurationHTTPAdapter adapterConfig = new ConfigurationHTTPAdapter();
// add additional configuration
Request request = new Request();
request.setStream("TriggerEvent");
request.setUri("http://localhost:8077/root");
adapterConfig.getRequests().add(request);
// start adapter
EsperIOHTTPAdapter httpAdapter = new EsperIOHTTPAdapter(adapterConfig, "engineURI");
httpAdapter.start();
// destroy the adapter when done
httpAdapter.destroy();A service is required for the adapter to receive events via a HTTP client connection.
The synopsis is as follows:
<esperio-http-configuration> <service name="[name]" port="[port]" [nio="true|false"]/> <!-- add additional configuration here --> </esperio-http-configuration>
The name attribute value is required and provides the name of the HTTP service for use in logging and for get-handlers as described below.
The nio attribute is optional and can be used to enable Java NIO (disabled by default).
If configuring via the adapter API or Spring, use the com.espertech.esperio.http.config.Service class.
An example XML to configure a service and single get-handler is:
<esperio-http-configuration> <service name="myservice" port="8079" nio="false"/> <get service="myservice" pattern="*"/> </esperio-http-configuration>
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&name=${name};violationip=${ipaddress}"/>The URI generated by the adapter:
http://myremotehost:80/root/TriggerFirewallStream?violation&name=Joe&violationip=120.1.0.0