Injecting code into a correlator dynamically
To inject EPL files, EPL plug-ins in Java or correlator deployment packages (CDPs) into the correlator, invoke the engine_inject tool. The executable for this tool is located in the Apama/bin directory.
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).
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 an EPL plug-in written in Java. For more information, see To create a Java class to use as an EPL plug-in.
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 Java plug-in 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.
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 EPL plug-in(s) 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, Java EPL plug-in JAR, 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.