Runtime JavaEngine Configuration

Contents

Overview
Required Header Lines
HOCON Properties Explained
Configuration File Sample

Overview

This article provides a reference for writing a StreamBase Runtime JavaEngine 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 array, 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 Runtime Node Configuration), the engine configuration is associated with all engines running on all nodes.

  • The StreamBase Runtime audits for valid engine affinity configurations. If you attempt to run a configuration containing engine affinity and one or more of the engines in the affinity property do not exist, the operation will fail. Similarly, if you attempt to replace a configuration with a different version, and the new version has an invalid affinity property, you will also get an error and the operation will fail.

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 = "javaengine"
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 three 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.

The top-level configuration object defines the configuration envelope the same way for all HOCON file types.

configuration

On a line below the header lines, enter the word configuration followed by an open brace. The configuration object is a sibling of the name, version, and type identifiers, and serves to define the configuration envelope around this type's objects as described on this page. The file must end with the matching close brace. 

configuration = {
...
...
}

HOCON Properties Explained

The following shows this configuration's HOCON properties, 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 array 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 object is optional and has default values as described below.

minimumDispatchThreads

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

minimumDispatchThreads = 10
maximumDispatchThreads

Long. Specifies the maximum number of dispatch threads. This property 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 property 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 property 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 property 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 property 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 property 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 array 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 array 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 association of objects specifying the path to one or more directories containing native libraries to add to the engine's library search path. Specify an operating system array to specify paths appropriate for the operating system, using one of the exact array names osx_x86_64, linux_x86_64 , or windows_x86_64. Values for members of these arrays are absolute paths to directories containing native libraries, in the path format appropriate for each operating system. For Windows paths, use forward slashes.

This object is intended for use by fragments with adapters or operators that use external native libraries. This object is optional and has no default value.

For example:

externalNativeLibraryPath = {
  // "osx_x86_64" = [
  //  "/absolute/path/library1"
  //  "/absolute/path/library2"
  "windows_x86_64" = [
    "C:/absoute/path/library1"
    "C:/absoute/path/library2"
  ]
}
systemProperties

String. A list of Java system properties that you can set in each engine instance on this operating system type. These values can be overridden and extended by individual application fragments. This object is optional and has no default value.

For example:

systemProperties = {
  prop1 = "value1"           
  prop2 = "value2"
  "prop.3" = "value3" // Notice that any period or path 
                      // separator in a property name 
                      // must be inside a quoted string
}
jvmArgs

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

For example:

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

Configuration File Sample

The following is an example of the 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/libfiles1"
        "/absolute/path/libfiles2"
      ]
    }
    systemProperties = {
      prop1 = "val1"           
      prop2 = "val2"
      "prop.3" = "val3"
    }
    jvmArgs = [
      "-Xmx3g"
      "-Xms512m"
      "-XX:+UseG1GC"
      "-XX:MaxGCPauseMillis=500"
      "-XX:ConcGCThreads=1"
    ]
  }
}