LiveView Engine Configuration

Contents

Overview
Required Header Lines
LDMEngine Root Object
EventFlowDeployment Root Object
LDMEngine Configuration File Sample

Overview

This article provides a reference for writing a LiveView Engine configuration file where the HOCON type is com.tibco.ep.ldm.configuration.ldmengine.

The root objects in this configuration type are:

LDMEngine

Use the LDMEngine root object to specify and manage features of LiveView fragments running in a StreamBase Runtime node.

EventFlowDeployment

Use the EventFlowDeployment root object to control the binding of EventFlow modules to containers at deployment time.

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 = "myldmengine"
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.ldm.configuration.ldmengine"

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 = {
...
...
}

LDMEngine Root Object

Below shows the configuration's HOCON properties, usage, and syntax example, where applicable.

LDMEngine

This root object describes a top-level LiveView engine configuration. The LiveView engine configuration inherits from the EventFlow engine configuration, which in turn inherits from the base Runtime Java engine.

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 can applies to more than one engine. This array is optional and has no default value. If not present, the configuration uses default engine association based on its location in a fragment or application archive, or in a node deploy configuration.

For example: 

associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
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. 

externalClassPath = [
  "/absolute/path/d.jar"
  "/absolute/path/g.jar"
  "/absolute/path/root" // class file hierarchy
]
jvmTuning

Specifies various tuning parameters to pass to the Java virtual machine that runs the LiveView server. This object is optional and has default values as described below.

minimumDispatchThreads

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 running 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
systemProperties

A list of Java system properties that will be set in each engine that uses this configuration. This object is optional and has no default value.

Note this is where you would put any LiveView system properties that are not explicitly modeled in this configuration.

For example: 

systemProperties = {
  prop1 = "val1"           
  prop2 = "val2"
  "prop.3" = "val3" // note dot, path separator so must be inside quoted string
}
jvmArgs

String. A array of JVM arguments used for this engine instance on this operating system type. These values can be overridden by individual application fragments. This array is optional and has no default value.

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.

It is a best practice to have a minimum of 4 GB of heap space for starting and running LiveView Server.

For example: 

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

This object controls the behavior of the EventFlow engine that is running this LiveView fragment. Some sample EventFlow engine settings are below, to demonstrate inheritance. See StreamBase Engine Configuration for more information about the streamBase object.

operatorStateChangeTimeoutMilliseconds

Int. Each Java operator changes state along with the engine process as a whole. The engine waits for each operator to change state before it completes its state change. The value of this property is the amount of time the engine will wait before timing out the operator. If an operator is timed out on a state change, the engine shuts down the operator and proceeds with the state change. This property is optional and its default value is 10000.

For example: 

operatorStateChangeTimeoutMilliseconds = 10002
engineMonitor

Configures the engine's monitoring subsystem. This object is optional.

enabled

Boolean. If false, prevents the StreamBase profile service from starting. If true, the profile service starts. This property is optional and its default value is true. Do not change this property to false except under the guidance of Support.

statsFrequencyMilliseconds

Int. Configures how frequently monitoring stats are produced. This property is optional and its default value is 1000.

For example: 

statsFrequencyMilliseconds = 2000
ldm

LiveView-specific part of the configuration.

alert

Alert service configuration. This object is optional and has values as specified below.

enabled

Bool. If false, prevent the alert service from starting. If true, the alert service starts. This property is optional and its default value is true.

For example: 

enabled = false
disableChanges

Bool. If true, prevent non-local LiveView clients from changing alert rules. If false, any client can change alert rules. This property is optional and its default value is false.

For example: 

disableChanges = true
registerStartup

Bool. If false, prevents configured alerts from being registered at startup. If true, alerts are registered. This property is optional and its default value is true.

For example: 

registerStartup = false
metadataStore

Identifies the type of LiveView metadata store to use.

storeType

Identifies the type of LiveView metadata store to use, where the recognized values are LOCAL, H2, TRANSACTIONAL_MEMORY, or JDBC. This property is optional and its default value is LOCAL.

For example: 

storeType = "JDBC"
jdbcDataSource

Only relevant when storeType is JDBC, in which case this property is required. Specifies the JDBC data source identifier that identifies the back-end JDBC database that will be used to store the LiveView metadata. This identifier is the name of a configuration filename of type jdbcdatasource. There is no default value.

For example: 

jdbcDataSource = "mySQL5"
jdbcMetadataTableNamePrefix

Only relevant when storeType is JDBC to specify a prefix for the names of tables that store LiveView metadata. The property is optional and its default value is an empty string.

For example: 

jdbcMetadataTableNamePrefix = "LV_CLUSTER1_"
tableGroup

Defines a single group of LiveView servers containing the same set of tables, for high availability. In Release 10.6.0, this property replaces the deprecated lvconf table group configuration method.

For example: 

tableGroup = "myTableGroup"

EventFlowDeployment Root Object

As of Release 10.5.0, EventFlowDeployment root objects are supported in the com.tibco.ep.ldm.configuration.ldmengine configuration type. Note that since EventFlowDeployment objects are deploy-time and LDMEngine objects are typically design-time, you would typically not combine them into one configuration file, but you are free to do so.

Refer to the link above for a description of supported EventFlowDeployment properties. 

name = "ldmengine_with_EFD"
type = "com.tibco.ep.ldm.configuration.ldmengine"
version = "1.0.0"
configuration = {
  LDMEngine = { }
  
  EventFlowDeployment = { }
}

LDMEngine Configuration File Sample

The following shows an example of the com.tibco.ep.ldm.configuration.ldmengine type, to illustrate how you can configure the Java and EventFlow parts of the LiveView engine. 

name = "myldmengine"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldmengine"
configuration = {
  LDMEngine = {
    associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
    externalClassPath = [
      "/absolute/path/d.jar"
      "/absolute/path/g.jar"
      "/absolute/path/root" 
    ]
    jvmTuning = {
      minimumDispatchThreads = 10
    }
    systemProperties = { 
      "liveview.server.allowedOrigins" = "*" }
    jvmArgs = [
      "-Xmx3g"
      "-Xms512m"
      "-XX:+UseG1GC"
      "-XX:MaxGCPauseMillis=500"
      "-XX:ConcGCThreads=1"
    ]
    streamBase = {
      operatorStateChangeTimeoutMilliseconds = 10002
      engineMonitor = {
        enabled = false
        statsFrequencyMilliseconds = 2000
      }
    }
    ldm = {
      alert = {
        enabled = false
        disableChanges = true
        registerStartup = false
      }
      metadataStore = {
        storeType = "JDBC" 
        jdbcDataSource = "mySQL5"        
        jdbcMetadataTableNamePrefix = "LV_CLUSTER1_"       
      }
      tableGroups = "myTableGroup"
      }
    }
  }
}