Specifying 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 jars the user chooses to specify on the correlator command line using -J-Djava.class.path=path.

It is also possible to specify additional jars 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, e.g.

...
<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 semi-colon characters (;). Note that semi-colon 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

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.