Runtime JavaEngine Configuration

Contents

Overview
Engine Affinity
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.

Engine Affinity

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 — also referred to as default — engine affinity is set using these rules:

  • When defined, affinity configurations must have explicit or implicit affinity with at least one engine. Otherwise, the audit rejects the configuration activation/replacement.

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

  • If an application archive or node deploy specifies a configuration, then any manually managed subsequent versions of that configuration must have specific affinity information in its HOCON if the configuration is to maintain the affinity it received automatically from its presence in a node deploy engine-scope section or a fragment archive.

  • 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. For example: 

    name = "node-deploy-configuration"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.node"
configuration =
  {
    NodeDeploy =
       {
         globalConfiguration =
         [
           //
           // Associated with all engines on all nodes
           //
           """
           name = "java-engine-configuration"
           version = "1.0.0"
           type = "com.tibco.ep.dtm.configuration.javaengine"
           configuration =
             {
               JavaEngine = { ... }
             }
           """
          ]
             nodes =
               {
                 "A.X" = { ... }
                 "B.X" = { ... }
               }
       }
  }

  • If engine configuration is specified in the node specific configuration section of a node deploy configuration, Node.configuration, the engine configuration is associated with all engines running on that node. 

    name = "node-deploy-configuration"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.node"
configuration =
  {
    NodeDeploy =
  {
      nodes =
  {
      "A.X" =
  {
      configuration =
      [
        //
        // Associated with all engines on node A.X
        //
           """
           name = "java-engine-configuration"
           version = "1.0.0"
           type = "com.tibco.ep.dtm.configuration.javaengine"
           configuration =
             {
                JavaEngine = { ... }
             }
            """
          ]
         }
           "B.X" = { ... }
       }
    }
  }

  • If engine configuration is specified in the engine specific configuration section of a node deploy configuration, EngineBinding.configuration, the engine configuration is associated with only that engine. 

    name = "node-deploy-configuration"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.node"
configuration =
  {
    NodeDeploy =
  {
      nodes =
    {
      "A.X" =
    {
      engines =
    {
        "settlement-engine" =
    {
         fragmentIdentifier = "settlement-engine-fragment"
         configuration =
         [
           //
           // Associated with settlement-engine on node A.X
           //
              """
              name = "java-engine-configuration"
              version = "1.0.0"
              type = "com.tibco.ep.dtm.configuration.javaengine"
              configuration =
      {
              JavaEngine = { ... }
      }
              """
          ]
      }
      }
      }
        "B.X" = { ... }
      }
    }
}

    Note

    Implicit engine affinity is only supported for configurations that are loaded from an application archive. Configuration loaded using the epadmin configuration target must always explicitly define the required engine affinity.

  • Explicit engine affinity is set using the JavaEngine.associatedWithEngines property in configuration. This property can contain specific engine names or a regular expression identifying multiple engines. 

    name = "java-engine-configuration"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.javaengine"
configuration =
  {
    JavaEngine =
  {
    //
    // Associated with settlement-engine
    //
         associatedWithEngines = [ "settlement-engine" ]
         ...
   }
   }

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 fails. Similarly, if you attempt to replace a configuration with a different version, and the new version has an invalid affinity property, you also get an error and the operation fails.

Configuration types that support engine affinity define engine specific configuration values that may not work correctly when they are associated with multiple engines on the same machine. For example, if the engine configuration defines a port number, the configuration will work for a single engine, but it will fail if multiple engines are running on the same machine. The configuration can be activated successfully on one engine, but all other engines will get a duplicate port failure. For reasons like this, it is generally best to associate configuration types that support engine affinity with a specific engine.

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

Root object for a Java engine configuration, which applies to an engine explicitly declared with associatedWithEngines, or applies implicitly according to the rules described in the preface above.

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]" ]
jvmTuning

Specifies 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. Specifies a list of JAR files and class hierarchies to add to the application fragment's classpath. This array is intended for application fragments that use common external Java libraries. Paths are required to be absolute and in Java (forward-slash) format. This array is optional and has no default value.

For example: 

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 = {
  "windows_x86_64" = [
    "C:/absoute/path/library1"
    "C:/absoute/path/library2"
  ]
}

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

externalNativeLibraryPath = {
  "linux_x86_64" = [
     "/absolute/path/library1"
     "/absolute/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. Do not set the classpath here. Use the guidance in Java VM Memory Settings for assistance when setting the -Xms (minimum) and -Xmx (maximum) Java heap size arguments. While it is possible to specify system properties here, it is better to use the systemProperties property described above. This array is optional and has no default value.

For example: 

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

Configuration File Sample

The following is an example of a Java engine configuration type. 

name = "javaengine"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.javaengine"
configuration = {
  JavaEngine = {
    associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
    jvmTuning = {
      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"
    ]
  }
}