Apama 10.15.0 | Deploying and Managing Apama Applications | Correlator Utilities Reference | Deploying a correlator
 
Deploying a correlator
The engine_deploy tool lets you perform the following actions with an Apama project that has been created with Software AG Designer or with the apama_project tool:
*generate an initialization file list,
*generate a correlator deployment directory,
*create a Zip file with the contents of the correlator deployment directory,
*generate a correlator deployment package (CDP),
*perform the initialization in a running correlator.
This tool can also be used with a directory of Apama files if you are not using Software AG Designer.
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.
You can also use Ant to generate a correlator deployment directory or a correlator deployment package. The apama-macros.xml file includes the generate-correlator-deploy-dir and project-to-cdp macros for this purpose. See also About deploying Apama applications with an Ant script.
Note: 
If a license file cannot be found, the correlator cannot read user-generated CDPs. See Running Apama without a license file.
Synopsis
To use this tool, run the following command:
engine_deploy action [options] path1 [path2 ...]
When you run this command with the –h option, the usage message for this command is shown.
Description
The action that you have to specify when you run this tool can be one of the following:
Action
Description
--outputList file | stdout
Specifies where the initialization file list is to be created. This can be written either to a file or standard output.
-d dir | zipfile
or
--outputDeployDir dir | zipfile
Specifies the deployment directory into which the project artifacts are to be copied and in which the YAML configuration files and properties files are to be created. You must not specify a subdirectory of the project directory as the deployment directory.
Instead of a directory, you can also specify the name of a Zip file that is to be created (for example, OutputDir.zip) and which contains the same contents as the deployment directory. If you specify the name of an existing Zip file, this Zip file will be overwritten.
--outputCDP file
Specifies the file name of the correlator deployment package (CDP) that is to be generated. The CDP is created using the correct injection order, and it contains any EPL files, JMon JAR files, event files and nested CDPs.
Note: 
You can also create CDPs using Software AG Designer. See Exporting correlator deployment packages.
Note that Apama's in-process API for Java (JMon) is deprecated and will be removed in a future release.
--inject host port
Specifies that each EPL file is to be injected into the correlator that is running on the specified host and port.
Note:
It is not advisable to inject CDP files containing event files with large numbers of events into a persistent correlator. In this case, it is recommended that you create a CDP which only contains event files. A CDP which only contains event files is not persisted.
Note:
Only one action can be specified at a time.
Deployment directory
When you use this tool to generate a deployment directory, it copies all required files from the project into a deployment directory. It also generates all required YAML configuration files and properties files using the information that is currently defined in the project's launch configuration (see Launching Projects for more information on how to set up a launch configuration).
The deployment directory includes all of the project artifacts, except for log files, along with following generated files:
File name
Contents
initialization.yaml
List of all files that are to be loaded by the correlator at startup. See also Deploying Apama applications with a YAML configuration file. This file is always generated.
initialization.properties
Substitution variables for locations outside the project directory and APAMA_HOME used by initialization.yaml. This file is not generated for projects that use only initialization files from APAMA_HOME and the project directory.
connectivity.yaml
Connectivity configuration. This file is only generated when the input directory is an Apama project and when this project includes connectivity bundles.
arguments.yaml
Configuration entries for the port, log file and log level. This file is only generated when a launch configuration is present.
correlator.properties
Substitution variables for customizing the settings in arguments.yaml, such as the port.
Includes extraArgs for any extra command line arguments specified in the launch configuration. These cannot be used by the YAML configuration file for the correlator. Therefore, they must be manually passed on the command line by whatever tool is responsible for staring the correlator.
This file contains properties logsDir and dataDir to allow easily changing the location where data (for example, runtime cache directory, pid file) and log files are written without needing to modify the properties for each file path individually. There is also a property startTimeoutSecs, which is not currently used by any Apama tools, but can be used to provide a hint to customer-developed deployment or testing tools about how long to wait for the component to start up.
persistence.yaml
Persistence configuration of the project. This file is only generated when a launch configuration is present.
persistence.properties
Values for the persistence options such as storeLocation, clear and enabled. See also Configuring persistence in a YAML configuration file.
After all output has been generated, you use the correlator executable with the --config option to start the correlator with all the YAML and properties files that have been generated. For example:
correlator --config C:/MyDeployDir
See Starting the correlator for detailed information on the available options.
If you want to override one or more property values that are defined in the generated properties files, you have to send an additional properties file containing these overrides (or you can set the property directly by specifying it on the command line) to the correlator before sending the generated properties files. For example, when you specify the following, the property values defined in the file myOverrides.properties will take precedence over all of the properties defined in other files.
correlator --config myOverrides.properties --config deployDir/
Important: 
If the project requires any JAR files from an EPL plug-in in Java or from a JMon application, you have to make available the JAR files before you start the engine_deploy tool.
Note that Apama's in-process API for Java (JMon) is deprecated and will be removed in a future release.
Options
The engine_deploy tool takes the following options:
Option
Description
--include pattern[,pattern]
Specifies the files from the project that are to be included in the output/injection. For example:
**/foo/Bar*.evt,**.mon
--exclude pattern[,pattern]
Specifies the files from the project that are to be excluded from the output/injection. For example:
**/foo/Bar*.evt
Note:
Log files are always excluded.
Operands
path1 and other optional paths that you can specify when you run the engine_deploy tool can point to the following:
*A project directory. This is the directory which contains the .project file and, if defined, the .dependencies file.
If exactly one deployment (.deploy) file exists in the project directory, it is automatically used. If the directory contains more than one deployment file, an exception is thrown. In this case, you have to select the deployment file to be used by specifying the path to it (instead of specifying the path to a project directory). You also have to specify the path to a deployment file explicitly if your launch configuration contains multiple correlators, followed by an exclamation mark (!) and the correlator name as described below.
Note:
You can only specify one project at a time. If a project references additional projects, then the generated injection order might not be accurate.
If you are not using Software AG Designer or the apama_project tool, you can specify any directory containing Apama files (for example, .mon files, etc.).
*A deployment (.deploy) file. This file is automatically generated by Software AG Designer for each launch configuration that has been defined for a given project. It is located under project_dir/config/launch. See also Defining custom launch configurations.
If more than one correlator is defined in the deployment file, you have to add an exclamation mark (!) followed by the correlator name (otherwise, the tool will give an error message and fail). For example:
MyDeployFile.deploy!myCorrelator
If your launch configuration has multiple correlators, it is recommended that you generate a separate correlator deployment directory for each correlator.
If a deployment file is used which contains environment variables, you have to explicitly specify these variables when you start the correlator with the correlator executable. These variables are not captured from the launch configuration. This is important when using EPL plug-ins and connectivity plug-ins that are written in C++.
*Zero or more .properties files which contain substitution variables that have been defined in the specified project. The properties files are used when you specify a project directory or deployment file. You can specify these paths in any order.
*A text (.txt) file. This is the initialization file list which lists the project artifacts to be included.
*One or more correlator deployment packages (.cdp files) to be injected into the correlator.
Examples
The following examples (for Windows) show the different ways in which the engine_deploy tool can be started.
*Create an initialization list by pointing to a project directory containing the EPL files:
engine_deploy --outputList C:/initialization_list.txt MyProject
*Create a correlator deployment directory by pointing to a deployment file within the project, and using the substitution variables that have been defined in a properties file that is also available in the project:
engine_deploy --outputDeployDir C:/MyDeployDir
MyProject/config/launch/MyDeployFile.deploy!myCorrelator
C:/MyProjects/environment.properties
The name of the correlator that is to be used is given after the exclamation mark (!).
Files coming from external variables are also copied into C:/MyDeployDir. In addition, the file initialization.properties is generated which contains information on these variables.
*Create a correlator deployment package by pointing to a deployment file within the project:
engine_deploy --outputCDP C:/output.cdp
C:/MyDeployDir/MyProject/config/launch/MyDeployFile.deploy!myCorrelator
The correlator deployment package can then be injected into the correlator using engine_initalize or engine_inject.
*Perform the initialization into a running correlator by pointing to a deployment file within the project and excluding specific files from the injection:
engine_deploy --inject C:/MyDeployDir
--exclude MyProject/dashboards/**
MyProject/config/launch/MyDeployFile.deploy!myCorrelator
The --exclude option specifies that the generated deployment directory does not contain the files from the MyProject/dashboards directory, and that these files are also not to be used during injection.