Reference for DTM JavaEngine Configuration

Overview

This article provides a reference for writing a DTM JavaEngine HOCON configuration file, and provides a detailed description of all configuration object properties to configure Java engines.

A Java engine is used to execute a Java fragment. A snippet is provided for each configuration object showing the syntax for specifying all of the configuration values.

The com.tibco.ep.dtm.configuration.javaengine configuration type must be associated with a specific engine; this association is called engine affinity. Engine affinity can be explicitly defined with the associatedWithEngines key, or implicitly defined based on where the engine configuration is specified. Implicit engine affinity is set using these rules:

  • If engine configuration is contained in a fragment archive, the engine configuration is associated with all engines running the fragment.

  • If engine configuration is specified in a node deploy global configuration section, NodeDeploy.globalConfiguration (see Reference for DTM Node Configuration), the engine configuration is associated with all engines running on all nodes.

Required Header Lines

Each configuration file must contain the following header lines, typically found at the beginning of each file:

name

Specifies an arbitrary, case-sensitive string to name this configuration, which must be unique among other files with the same type, if any. Configuration files can refer to each other by this name. Select a name that reminds you of this configuration's type and purpose. For example:

name = "dtmjavaengine"
version

Specifies an arbitrary version number that you can use to keep track of file versions for this configuration type in your development project. The maintenance of version numbers is under user control; StreamBase does not compare versions when loading configuration files during the fragment launch process. The version number is a string value, and can contain any combination of characters and numbers. For example:

version = "1.0.0"
type

This essential setting specifies the unique HOCON configuration type described on this page.

type = "com.tibco.ep.dtm.configuration.javaengine"

The header lines taken together constitute a unique signature for each HOCON file in a project's configurations folder. Each project's configurations folder can contain only one file with the same signature.

In addition, the configuration top-level element is the same for all HOCON file types.

configuration

On a line below the header element lines, enter the word configuration followed by an open brace. The configuration element is a sibling of the name, version, and type elements, and serves as a wrapper around this type's elements described below. The file must end with the matching close brace.

configuration = {
...
...
}

HOCON Elements Explained

The following shows this configuration's HOCON elements, its name-value pairs, usage, and syntax examples.

JavaEngine

Java engine configuration; specifies the JVM to which these settings apply, as determined by the configuration name.

associatedWithEngines

If you want to restrict this object to be associated with specific engines, do so here. Each entry can be a specific engine name or a regular expression that applies to more than one engine. This name-value pair is optional and has no default value. If not present, this configuration is associated with all engines.

For example:

associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
jvm

Various JVM tuning parameters. This name-value pair is optional and has default values as described below.

minimumDispatchThreads

Long. Specifies the minimum number of dispatch threads. This name-value pair is optional and its default value is 10. For example:

minimumDispatchThreads = 10
maximumDispatchThreads

Long. Specifies the maximum number of dispatch threads. This name-value pair is optional and its default value is 2000. For example:

maximumDispatchThreads = 2000
shutdownTimerSeconds

Long. Specifies the maximum number of seconds to wait for a JVM to shut down before aborting it. This name-value pair is optional and its default value is 60. For example:

shutdownTimerSeconds = 60
timerParallelism

Long. Specifies the number of timers that can be executing concurrently. This name-value pair is optional and its default value is 1. For example:

timerParallelism = 1
timerResolutionMilliseconds

Long. Specifies the maximum timer resolution. This is the interval at which timers are examined. Higher resolution timers have more impact on system performance. This name-value pair is optional and its default value is 1000. For example:

timerResolutionMilliseconds = 1000
schedulerPolicy

The scheduling policy for the JVM process. The valid values for the policy are "SCHED_FIFO", "SCHED_RR", and "SCHED_OTHER". This name-value pair is optional. For example:

schedulerPolicy = "SCHED_FIFO"
schedulerPriority

Long. Specifies the scheduling priority for the JVM process. The valid range for priority depends on the policy; for Linux the valid values for SCHED_FIFO and SCHED_RR are 1 to 99. This name-value pair is optional and its default value is operating system-specific. For example:

schedulerPriority = 1
externalClassPath

String. JAR files and class hierarchies to add to the application fragment's class path. This name-value pair is intended for application fragments that use common external Java libraries, such as JDBC drivers. Paths are required to be absolute and in Java (forward-slash) format. This name-value pair is optional and has no default value.

For example, an array such as the following:

externalClassPath = [
      "/absolute/path/external1.jar"
      "/absolute/path/external2.jar"
      "/absolute/path/hierarchy/root"
]
externalNativeLibraryPath

String. An associative array specifying native libraries to add to the engine's library search path. name-value pairs are operating system codes, one of osx_x86_64, linux_x86_64 , or windows_x86_64. Values are arrays of library paths. Paths are required to be absolute and must be in the format appropriate for their operating system.

This field is intended for use by fragments that use external native libraries. This name-value pair is optional and has no default value.

For example:

externalNativeLibraryPath = {
  "osx_x86_64" = [
    "/absolute/path/library1.so"
    "/absolute/path/library2.so"
  ]
}
systemProperties

String. A list of Java system properties that will be set in each engine instance on this operating system type. This name-value pair is optional and has no default value.

For example:

systemProperties = {
  prop1 = "value1"           
  prop2 = "value2"
  "prop.3" = "value3" // notice that the period and path 
                      // separator must be inside quoted string
}
jvmArgs

String. A list of JVM arguments used for each engine instance. This field is optional and has no default value.

For example:

jvmArgs = [
  "-Xmx3g"
  "-Xms512m"
  "-XX:+UseG1GC"
  "-XX:MaxGCPauseMillis=500"
  "-XX:ConcGCThreads=1"
  "-XX:+UseCompressedOops"
]

HOCON Configuration File Sample

The following is an example of the com.tibco.ep.dtm.configuration.javaengine type.

name = "javaengine"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.javaengine"
configuration = {
  JavaEngine = {

    associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]

    jvm = {

      minimumDispatchThreads = 10
      maximumDispatchThreads = 2000
      shutdownTimerSeconds = 60
      timerParallelism = 1
      timerResolutionMilliseconds = 1000
      schedulerPolicy = "SCHED_FIFO"
      schedulerPriority = 1
    }

    externalClassPath = [
      "/absolute/path/external1.jar"
      "/absolute/path/external2.jar"
      "/absolute/path/hierarchy/root"
    ]

    externalNativeLibraryPath = {
      "osx_x86_64" = [
        "/absolute/path/library1.so"
        "/absolute/path/library2.so"
      ]
    }

    systemProperties = {
      prop1 = "val1"           
      prop2 = "val2"
      "prop.3" = "val3"
    }

    jvmArgs = [
      "-Xmx3g"
      "-Xms512m"
      "-XX:+UseG1GC"
      "-XX:MaxGCPauseMillis=500"
      "-XX:ConcGCThreads=1"
      "-XX:+UseCompressedOops"
      ]
  }
}