The File Transport plug-in
The FileTransport/JFileTransport transport layer plug-ins can read and write messages both from and to a text file. This makes it very convenient for testing string encoding and decoding, semantic mappings, and EPL code, because a text file with some sample messages can be put together quickly and then run through the IAF. Similarly in the upstream direction it allows messages to be written to a file instead of an external message sink such as a middleware message bus.
Messages (or events) are read from and written to named files. Each line of the input file is taken to be a single input event. Each output event is written to a new line of the output file.
In order to load this plug-in, the <transport> element in the adapter’s configuration file must load the FileTransport library (this represents the filename of the library that implements the plug-in). Note that for the Java version, the full path to the plug-in’s .jar file must be specified.
A configuration file for C/C++ would use this:
<transport name="FileTransport" library="FileTransport">
In a configuration file for Java:
<transport name="JFileTransport"
jarName="Apama_install_dir\lib\JFileAdapter.jar"
className="com.apama.iaf.transport.file.JFileTransport">
The File Transport plug-in takes the following properties:
input — Specifies the name of the input file.
output — Specifies the name of the output file.
cycle — Specifies the number of times that the plug-in should cycle through the input file. Any value less than zero causes the plug-in to cycle endlessly, until the adapter is either shut down or re-configured. A zero value (the default if the property is missing) means ‘no cycling’ and results in the same behavior as if the value of this property was ‘
1’.
For more information on specifying plug-ins in an adapter’s configuration file, see
Transport and codec plug-in configuration.
The plug-in automatically stops after reading the entire input file the requested number of times. If the adapter is subsequently asked to reload its configuration, the plug-in starts running again, using the current property values in the configuration file. If the adapter configuration is reloaded while the plug-in is running, the new configuration will not take effect until the plug-in reaches the end of the current input file. In this case, a second reload request is required before the plug-in will actually start reading the new file.
By default, the File Transport plug-in always communicates with the event codec using Java String objects. Therefore, the String Codec plug-in is a suitable companion as it provides a mechanism for converting between String objects and normalized events.
There are some minor differences between the C and Java implementations:
In the
C version, if no input filename is specified, the standard input stream is used; similarly if no output filename is specified the standard output stream is used.
In the
Java version, there is an extra property called
upstreamNormalised. If this is specified and set to
true, the File Transport communicates with its codec using
NormalisedEvent objects rather than
String objects. In this configuration it should be used with the
JNullCodec, which does not perform any encoding or decoding but simply passes the unchanged
NormalisedEvent objects between the codec and transport layers. If
upstreamNormalised is set to
true, the File Transport uses the functionality of the
JStringCodec class to perform encoding/decoding, and all the properties available for use with the
JStringCodec plug-in class can be specified as properties to the
JFileTransport.
This is one of the sample plug-ins for which source code is available – see
IAF samples for more information.
JMultiFileTransport is the recommended way to read/write files, the FileTransport/JFileTransport is just a sample for which binaries are also included. See
Using the Apama File Adapter for more information.