The IAF runtime

Once installed, running the IAF is straightforward. As already stated, the IAF is not a development library but a generic adapter framework whose functionality can be tailored according to a user’s requirements through loading of the appropriate plug-ins.

In order to create an adapter with the IAF, one must supply a configuration file. This file – described in The IAF configuration file – specifies which plug-ins to load and what parameters to configure them with, defines the translation and transformation rules of the Semantic Mapper, and configures communication with Apama.

The adapter can then be started as follows:

In order for the IAF to successfully locate and load C/C++ transport layer and codec plug-ins, the location(s) of these must be added to the environment variable LD_LIBRARY_PATH on UNIX, or PATH on Windows.

A transport or codec plug-in library may depend on other dynamic libraries, whose locations should also be added to the LD_LIBRARY_PATH or PATH environment variable as appropriate for the platform. The documentation for a packaged adapter will state which paths should be used for the adapter’s plug-ins. Note that on the Windows platform, the IAF may generate an error message indicating that it was unable to load a transport or codec plug-in library, when in fact it was a dependent library of the plug-in that failed to load. On UNIX platforms the IAF will correctly report exactly which library could not be loaded.

When using the IAF with a Java adapter the location of the Java Virtual Machine (JVM) library is determined in the same way. On UNIX systems the LD_LIBRARY_PATH environment variable will be searched for a library called libjvm.so, and on Windows the IAF will search for jvm.dll, first in the third_party\jre\bin\server and third_party\jre\bin directories of the Apama installation referenced by the APAMA_HOME environment variable, then in any other directories on the PATH environment variable. Using a JVM other than the one shipped with Apama is not supported and Technical Support will generally request that any Java-related problems with the IAF are reproduced with the supported JVM. Apama requires JDK 6.0 and ships with JRE 6.0 update 27. See Java configuration (optional) for information about how the location of Java plug-in classes are determined.

The complete usage information for the executable iaf (on UNIX) or iaf.exe (on Windows) is as follows. This can be displayed at any time by launching the IAF with the --help option.

Usage: iaf [ options ] [ config.xml ]
Where config.xml is the name of a configuration file using the format
described in the Integration Adapter Framework documentation.
Options include:
  -V | --version           Print program version info
  -h | --help              This message
  -p | --port <port>   Port to listen for commands on (default is 16903)
  -f | --logfile <file>    Log to named file (default is stderr)
  -l | --loglevel <level>  Set logging verbosity. Available levels
                         are TRACE, DEBUG, INFO, WARN, ERROR, FATAL, CRIT and OFF.
                           The default logging level is INFO.
  -t | --truncat           Truncate the log file
  -N | --name <name>       Set the component name
  -e | --events            Dump event definitions to stdout then exit
  -Xconfig | --configFile <file> Use service configuration file <file>
Note that a configuration file must be provided unless the -h or -V
options are used.

Unless –e or --events are used, the above will generate and start a custom adapter, load and initialize the plug-ins defined in the configuration file, connect to Apama, and start processing incoming messages.

When the –e or --events command line switches are used, iaf generates event definitions that can be saved to a file and injected during your application’s startup sequences as specified by Apama Studio, the Enterprise Management and Monitoring console (EMM), or Apama command line tools. If either of these switches is used, the IAF will load the IAF configuration file, process it, generate the event definitions and print them out onto stdout (standard output) and promptly exit. A valid configuration file must be supplied with either of these switches. The output definitions are grouped by package, with interleaved comments between each set. If all the event types in the configuration are in the same package, the output will be valid EPL code that can be injected directly into the correlator. Otherwise, it will have to be split into separate files for each package. The IAF can be configured to automatically inject event definitions into a connected correlator, but this is not the default behavior. The event definitions generated by the -e or --events options are exactly what the IAF would inject into the correlator, if configured to do so.