Injecting code into a correlator
To inject EPL files, EPL plug-ins in Java, JMon applications, or correlator deployment packages (CDPs) into the correlator, invoke the
engine_inject tool. The executable for this tool is located in the
bin directory of the Apama installation. Running the tool in the Apama Command Prompt or using the
apama_env wrapper (see
Setting up the environment using the Apama Command Prompt) ensures that the environment variables are set correctly.
Note:
Apama's in-process API for Java (JMon) is deprecated and will be removed in a future release.
Synopsis
To inject applications into the correlator, run the following command:
engine_inject [ options ] [ file1 [ file2 ... ] ]
When you run this command with the –h option, the usage message for this command is shown.
Description
The engine_inject tool reads application definitions from the specified file(s) and injects them into a correlator. If you do not specify a filename, or if you specify a hyphen (-) as the filename, the correlator reads data from the standard input device (stdin) until you indicate the end of the file: Ctrl+D on UNIX and Ctrl+Z on Windows.
Application definitions can be monitors scripted in Apama's Event Processing Language (EPL). For more information on EPL, see
Introduction to Apama Event Processing Language. Alternatively, you can specify the
–j or
-c options. The
-j option specifies that you will inject an application or plug-in written in Java. The
-c option specifies that you will inject a correlator deployment package file.
When you specify the
-j option, each file you inject must be a Java archive file (JAR) that contains a single EPL plug-in written in Java or JMon application. For more information, see
Writing EPL Plug-ins in Java and
Overview of Apama JMon Applications.
When you specify the
-c option, the file you inject must be an Apama correlator deployment package (CDP). For more information on preparing a CDP, see
Packaging correlator input files.
By default, the engine_inject tool is silent unless an error occurs. To view information about engine_inject execution, specify the --verbose option.
If you try to inject invalid EPL files or invalid JMon applications, the correlator generates an error. None of the application data in the invalid file is loaded. The engine_inject tool terminates. If you specify multiple EPL or Java files for injection the engine_inject tool injects all of them or terminates when it reaches the first file that contains an error. For example:
engine_inject 1.mon 2.mon 3.mon
If the file 2.mon contains an error, then engine_inject successfully injects 1.mon and then terminates when it finds the error in 2.mon. The tool does not operate on 3.mon.
If you try to inject a CDP, the correlator processes each EPL file packaged in the CDP separately. If one file in a CDP contains an error, then the correlator reports an error for that file and does not run it but it does run the other files in the CDP (if they have no errors). It does not matter which file in the CDP contains the error. That is, the first file in the CDP that the correlator processes can contain an error and the correlator still runs the other files in the CDP if they contain no errors.
Note:
If a license file cannot be found, the correlator does not allow the injection of user-generated CDPs. See
Running Apama without a license file.
Options
The engine_inject tool takes the following options:
Option | Description |
-h | --help | Displays usage information. |
-n host | --hostname host | Name of the host on which the correlator is running. The default is localhost. Non-ASCII characters are not allowed in host names. |
-p port | --port port | Port on which the correlator is listening. The default is 15903. |
-v | --verbose | Requests verbose output during engine_inject execution. |
-u | --utf8 | Indicates that input files are in UTF-8 encoding. The default is that the engine_inject tool assumes that the EPL files to be injected are in the native character set of your platform. Set this option to override this assumption. The engine_inject tool then assumes that all input files are in UTF-8. |
-V | --version | Displays version information for the engine_inject tool. |
-j | --java | Indicates that each operand is a Java archive file (JAR file) that contains a single JMon application or an EPL plug-in written in Java. |
-c | --cdp | Indicates that each operand is a correlator deployment package (CDP) file. |
-s | --hashes | Indicates that instead of injecting the specified files you want to print the hashes (UTF8-encoded) for the files. If engine_inject is operating on Java or correlator deployment package (CDP) files, then you must also specify -j or -c. |
Operands
The engine_inject tool takes the following operands:
Operand | Description |
[ file1 [ file2 ... ] ] | The names of zero or more files that contain application data in Apama EPL, JMon, or correlator deployment package (CDP) files. If you do not specify one or more filenames, the engine_inject tool takes input from stdin. |
Exit status
The engine_inject tool returns the following exit values:
Value | Description |
0 | All definitions were injected into the correlator successfully. |
1 | No connection to the correlator was possible or the connection failed. |
2 | Other error(s) occurred while injecting the supplied definitions. |
Text encoding
By default, the engine_inject tool uses the default system encoding to determine the local character set. The engine_inject tool then translates all submitted EPL text from the local character set to UTF-8. Consequently, it is important to correctly set the machine's locale.
However, some input files might start with a UTF-8 Byte Order Mark. The engine_inject tool treats such input files as UTF-8 and does not do any translation. Alternatively, you can specify the -u option when you run the engine_inject tool. This forces the tool to treat each input file as UTF-8.