Specifying the classpath in deployment descriptor files
Each JMon or Java plug-in JAR is loaded in its own dedicated Java classloader, which by default has access only to its own classes, and those available globally in the correlator's system classloader.
Note: The correlator's system classloader includes some standard Apama libraries such as the ap-correlator-extension-api.jar and ap-util.jar JAR files plus any additional JAR files the user chooses to specify on the correlator command line using -J-Djava.class.path=path.
It is also possible to specify additional JAR files for use by a specific JMon application or Java plug-in, to provide access to any third-party libraries that the JAR requires. This approach is more self-contained than adding to the correlator's global classloader.
The classpath string for a JMon application or Java plug-in is specified in its deployment descriptor XML file as follows:
If you are manually writing the deployment descriptor XML, add the optional
classpath element just after the
description element, for example:
...
<description>Description of this application</description>
<classpath>${sys:MY_THIRD_PARTY_DIR}/lib/foo.jar;
${sys:MY_THIRD_PARTY_DIR}/lib/bar.jar</classpath>
...
Note that the classpath element is only available in the 1.2 (and greater) versions of the JMon XML DTD (jmon-jar_1_2.dtd), so it may be necessary to update the DOCTYPE of the deployment descriptor to specify this DTD version if it does not already.
If you are generating the deployment descriptor automatically using Java annotations, then use the optional
classpath attribute in the
@Application annotation:
@Application(
name = "Simple",
author = "My Name",
version = "1.0",
company = "Apama",
description = "My simple JMon application or Java plug-in",
classpath = "${sys:MY_THIRD_PARTY_DIR}/lib/foo.jar;
${sys:MY_THIRD_PARTY_DIR}/lib/bar.jar"
)
If you are using
Software AG Designer to generate the
.jar and deployment descriptor, use the
@Application annotation approach to specify the classpath.
In both cases, the classpath string consists of any number of classpath entries, delimited by semicolon characters (;). Note that the semicolon must be used even on platforms that typically use a colon or other character to separate path entries, and also that forward slashes (/) should be used instead of backslashes (\), in order to ensure that the application works in the same way regardless of the platform it is deployed on.
Avoid using absolute paths in the classpath, as this makes it difficult to use the application JAR on different machines. Instead, use ${...} placeholders to identify the first part of each path, for example, the installation directory of a third party whose libraries you wish to use. Currently two types of placeholder are supported:
${sys:MY_SYS_PROP_NAME} is replaced by a Java system property called
MY_SYS_PROP_NAME ${env:MY_ENV_VAR_NAME} is replaced by an environment variable called
MY_ENV_VAR_NAME The values for system property placeholders can be specified on the correlator command line using: -J-DMY_SYS_PROP_NAME=path.
The correlator will log a warning for any path that cannot be found, but will fail to inject the application entirely if the classpath includes any ${...} placeholders that are not defined.
You can make the location of your project directory available by defining an environment variable in a YAML configuration file as described in
Setting environment variables for Apama components. You can use
${PARENT_DIR} as the value of the property if the YAML file is located in your project directory root. If you do this, you can specify JAR files from your project directory. For example:
<classpath>
${env:APAMA_PROJECT_DIR}/lib/foo.jar;${env:APAMA_PROJECT_DIR}/lib/bar.jar
</classpath>