www.espertech.comDocumentation
This chapter discusses the EsperIO Socket adapter.
The EsperIO Socket input adapter can be used to send events into an Esper runtime via socket client, either as Java objects or as CSV name-value pair strings.
The adapter only requires Esper runtime as a dependency.
You may configure the EsperIO Socket adapter either as part of your Esper configuration file in the plugin loader section or via the adapter API. Add the esperio-socket-version.jar file to your classpath. There are no other dependent jar files required.
A sample adapter configuration file is provided in esperio-socket-sample-config.xml in the etc folder of the distribution. A configuration file must be valid according to schema esperio-socket-configuration-8-0.xsd.
You may place the configuration XML directly into your Esper configuration file as the example below shows:
<esper-configuration xmlns="http://www.espertech.com/schema/esper">
<runtime>
<plugin-loader name="EsperIOSocketAdapter"
class-name="com.espertech.esperio.socket.EsperIOSocketAdapterPlugin">
<config-xml>
<esperio-socket-configuration>
<socket name="mysocketOne" port="7101" data="object"/>
<socket name="mysocketTwo" port="7102" data="csv" hostname="myhost" backlog="20" unescape="true"/>
</esperio-socket-configuration>
</config-xml>
</plugin-loader>
</runtime>
</esper-configuration>Alternatively you can provide a URL in the Esper configuration file to point to your adapter configuration file:
<esper-configuration xmlns="http://www.espertech.com/schema/esper">
<runtime>
<plugin-loader name="EsperIOSocketAdapter"
class-name="com.espertech.esperio.socket.EsperIOSocketAdapterPlugin">
<init-arg name="esperio.socket.configuration.file"
value="file:/path/esperio-socket-sample-config.xml" />
</plugin-loader>
</runtime>
</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 Socket adapter is com.espertech.esperio.socket.config.ConfigurationSocketAdapter. The adapter class itself is
EsperIOSocketAdapter.
The code snippet below is a sample that configures using driver manager and starts the adapter via API:
ConfigurationSocketAdapter adapterConfig = new ConfigurationSocketAdapter();
SocketConfig socket = new SocketConfig();
socket.setDataType(DataType.CSV);
socket.setPort(port);
adapterConfig.getSockets().put("SocketService", socket);
// start adapter
EsperIOSocketAdapter socketAdapter = new EsperIOSocketAdapter(adapterConfig, "runtimeURI");
socketAdapter.start();
// destroy the adapter when done
socketAdapter.destroy();Add a socket configuration for each unique port that you want to expose a socket receive service for use by socket client connections.
The synopsis is as follows:
<esperio-socket-configuration>
<socket name="[name]" port="[port]" data="[csv|object|property_ordered_csv]"
[hostname="hostname"] [backlog="backlog"] [unescape="true|false"]/>
</esperio-socket-configuration>The required name attribute provides the name of the socket service for use in logging.
The required port attribute provides the port that the socket service accepts client connections.
The required data attribute specifies whether the data arriving through the socket is formatted as a Java binary object stream or as CSV string values.
The optional hostname attribute can provide the host name passed to the server socket (ServerSocket).
The optional backlog attribute can provide the backlog number of connections passed to the server socket. This number defaults to 2 when a host name is passed but no backlog is provided.
The optional unescape attribute is false by default. When false the adapter does not unescape (Java escape rules) values. When true the adapter performs an unescape on all values.
If configuring via the adapter API or Spring, use the com.espertech.esperio.socket.config.SocketConfig class.
When sending events as Java objects, configure the data attribute value to object and use ObjectOutputStream to write events to the client socket. When sending a java.util.Map event,
your Map must contain a String value for the key stream which must denote a configured Map event type.
This example XML configures a socket accepting client connections that provide Java objects:
<esperio-socket-configuration> <socket name="objectStreamSocket" port="8079" data="object"/> </esperio-socket-configuration>
When object data type is configured, clients connections are expected to send java.io.Serializable or java.io.Externalizable objects using ObjectOutputStream.
Below is a block of sample code that for use in clients to the adapter. It assumes the MyEvent class implements either of the above interfaces:
// connect first
Socket requestSocket = new Socket("localhost", port);
ObjectOutputStream out = new ObjectOutputStream(requestSocket.getOutputStream());
// send a few events, here we send only one
out.writeObject(new MyEvent("Hello World"));
out.flush();
// Consider resetting the output stream from time-to-time, after sending a number of objects.
// This is because the stream may cache strings etc. . The reset is:
// out.reset();
// close when done
out.close();
requestSocket.close();When sending events as CSV strings, the format of the string should be:
stream=[type],[name]=[value] [,...] (newline)
The CSV string must end with a newline character: Each event is one line. Each CSV element must be in the [name]=[value] format. Your CSV must contain a value for stream which must denote a configured event type.
The adapter parses each string value and populates an instance of the target type.
This next example XML configures a socket accepting client connections that provide events as CSV-formatted strings with name-value pairs :
<esperio-socket-configuration> <socket name="csvStreamSocket" port="8079" data="csv"/> </esperio-socket-configuration>
A piece of client code that sends an event of type MyEvent may look as follows:
// connect first
String newline = System.getProperty("line.separator");
Socket requestSocket = new Socket("localhost", port);
BufferedWriter wr = new BufferedWriter(
new OutputStreamWriter(socket.getOutputStream()));
// send a few events
wr.write("stream=MyEvent,price=20.d,upcCode=A0001");
wr.write(newline);
wr.flush();
// close when done
wr.close();
requestSocket.close();
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.
Similar to the string CSV data format as discussed earlier, this data format allows specifying a property order as well as the event type name.
The format of the string that represents an event is the CSV format (no name= or stream= texts are required):
value [, value [,...]] (newline)
This next example XML configures a socket accepting client connections that provide events as CSV-formatted strings with name-value pairs :
<esperio-socket-configuration> <socket name="csvStreamSocket" port="8079" data="property_ordered_csv" stream="MyEvent" propertyOrder="price,upcCode"/> </esperio-socket-configuration>
Set the data attribute to property_ordered_csv. The stream attribute is a required configuration and must contain the event type name.
The propertyOrder attribute is also required and must contain the property names of properties of the event type, in the same order that the value for the property arrives on each line.
As part of the sample client code shown above, the following line sends an event with values 20.0 and A0001.
wr.write("20.0,A0001");
wr.write(newline);
The JSON-formatted message can be processed by following below format. Please make sure to use create json schema to declare the respective JSON event type.
The format of the string that represents an event in JSON format is:
stream=eventtypename,json=jsontext (newline)
The eventtypename is the JSON event type name. The jsontext is the JSON-formatted string without newline characters. The message must end with newline.
This XML snippet configures a socket accepting client connections that provide events as JSON-formatted strings:
<esperio-socket-configuration> <socket name="jsonStreamSocket" port="8079" data="json" stream="MyEvent"/> </esperio-socket-configuration>
A sample message is:
stream=MyEvent,json={"price":20,"upcCode":"A0001"}
Each message must end with a newline character. The above example assumes a JSON event type such as @public @buseventtype create json schema MyEvent(price double, upcCode string).