< Previous		Next >

Engines

This chapter describes how to manage engines running in a node.

Installation

Engines are installed on a node as part of application installation. See Application Installation for details. Engines provide an execution context for a fragment. The engine execution environment is specific to the fragment type, for example a Java fragment.

Configuration

This section 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.

Java engine configuration has a configuration type of com.tibco.ep.dtm.configuration.javaengine.

Engine affinity

The com.tibco.ep.dtm.configuration.javaengine configuration type is an example of a configuration that must be associated with a specific engine. This association is called engine affinity. Engine affinity can be explicitly specified using the JavaEngine.associatedWithEngines configuration field (see JavaEngine object properties). Engine affinity is also implicitly defined by 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 NodeDeploy), the engine configuration is associated with all engines running on all nodes.

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 (see Node), 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 (see EngineBinding), 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 field in configuration. This field 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" ]
        ...
    }
}

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.

Audits

The Java engine configuration is audited whenever it changes state, such as from load to activate. There are detailed audits for each of the configuration objects in the Java engine configuration file. These are described in JavaEngine and JVM. There are also these global audits:

All Java engine configurations for a specific engine must have the same configuration name. Attempting to load a Java engine configuration for an engine with an already active configuration using a different configuration name will cause an audit failure during configuration activation.
Java engine configurations can only be loaded and activated during engine start-up. Attempting to activate a Java engine configuration that has an engine affinity with an already running engine will cause an audit failure during configuration activation.

Merging

Java engine configuration supports merge semantics. This allows multiple Java engine configurations to be active if they have different configuration names. For example, these two configurations can be active at the same time since they have different configuration names — java-engine-configuration-a and java-engine-configuration-b.

name = "java-engine-configuration-a" 
version = "1.0.0"           
type = "com.tibco.ep.dtm.configuration.javaengine"
configuration =             
{                           
    JavaEngine = { ... }
}

name = "java-engine-configuration-b" 
version = "1.0.0"           
type = "com.tibco.ep.dtm.configuration.javaengine"
configuration =             
{                           
    JavaEngine = { ... }
}

Java engine configurations that have the same configuration name use replace semantics.

Merging of engine configuration provides a mechanism to augment engine configuration shipped in fragments as the fragments are packaged into an application archive and deployed. See Overriding Default Configuration for details on how additional configuration can be specified.

All merging occurs on the configuration properties in the JavaEngine root object. The merge semantics are summarized in Merge behavior.

Merge behavior

Property Name	Merge Behavior
`associatedWithEngines`	No merging.
`jvmTuning`	Replaced by last activated configuration.
`externalClassPath`	New values are prepended to existing values. This allows subsequent class path entries to take precedence over earlier ones, providing a mechanism to override earlier class path entries.
`externalNativeLibraryPath`	New values are prepended to existing values. This allows subsequent native library paths to take precedence over earlier ones, providing a mechanism to override earlier native library path entries.
`systemProperties`	New values are merged, with properties overwriting one another, so a later configuration's setting of a system property will take precedence over an earlier configuration's setting of the same system property.
`jvmArgs`	New values are appended. This allows subsequent JVM arguments to override previously specified ones.

JavaEngine

The JavaEngine object is the top-level container for the Java engine configuration. Figure 1, “JavaEngine relationships” shows the relationships to other configuration objects.

JavaEngine relationships

A detailed description of the configuration object properties is in JavaEngine object properties and a snippet for these properties is in Example 1, “JavaEngine object snippet”.

JavaEngine object properties

Name	Type	Description
`associatedWithEngines`	String [ ]	Engines associated with this configuration. Each entry can be a specific engine name or a regular expression that applies to more than one engine. If present, there must be at least one element in the array . If this field is not set the configuration is associated with all engines. See the Javadoc for `java.util.regex.Pattern` for the regular expression syntax. Optional. No default, which causes the configuration to be associated with all engines. See also Engine affinity for implicit default behavior.
`jvmTuning`	`JVM` configuration object	JVM configuration object (see JVM). Optional. See for default values.
`externalClassPath`	String [ ]	Jar files and class hierarchies to add to the engine's class path. Paths must be absolute and in Java (forward-slash) format. Optional. No default value.
`externalNativeLibraryPath`	Associate array of String arrays with the key an operating system enumeration. The valid enumeration values are `macos_x86_64`, `linux_x86_64`, or `windows_x86_64`.	An associative array specifying native library paths to add to an engine's library search path. Values are arrays of library paths. Paths must be absolute and be in the format appropriate for their operating system. Optional. No default.
`systemProperties`	Associative array of Strings with the system property name the key value	A list of Java system properties that will be set in each engine instance. Optional. No default value.
`jvmArgs`	String [ ]	A list of JVM arguments used for each engine's JVM. An audit error is reported if the engine is running when the configuration is activated. `jvmArgs` can only be specified in configurations that are activated before an engine is running. JVM arguments can also be specified on the deploy tool command line. JVM arguments specified on the deploy tool command line override the same JVM argument specified in this configuration property. Optional. No default.

Example 1. JavaEngine object snippet

name = "java-engine-configuration"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.javaengine"
configuration =
{
    JavaEngine =
    {
        associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
        jvmTuning = { ... }
        externalClassPath = 
        [
            "/an/external.jar"
            "/another/external.jar"
            "/a/class/file/hierarchy/root"
        ]   
        externalNativeLibraryPath = 
        {
            "macos_x86_64" = 
            [
                "/an/external/native"
                "/another/external/native"
            ]   
            "linux_x86_64" =
            [
                "/an/external/native"
                "/another/external/native"
            ]
        }
        systemProperties = 
        {
            prop1 = "val1"      
            prop2 = "val2"
            prop3 = "val3"
        }                         
        jvmArgs = 
        [
            "-Xmx1024m"
            "-Xms512m"  
            "-XX:MaxPermSize=768m"
            "-Xdebug"               
            "-Xnoagent"                   
            "-Djava.compiler=NONE"                          
            "-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"
        ]
    }
}

JVM

The JVM object defines product specific configuration values. Figure 2, “JVM relationships” shows the relationships to other configuration objects.

JVM relationships

A detailed description of the configuration object properties is in JVM object properties and a snippet for these properties is in Example 2, “JVM object snippet”.

JVM object properties

Name	Type	Description
`minimumDispatchThreads`	long	Minimum number of dispatch threads. Optional. Default value is `10`.
`maximumDispatchThreads`	long	Maximum number of dispatch threads. Optional. Default value is `2000`.
`timerParallelism`	long	Number of timers that can be executing concurrently. Optional. Default value is `1`.
`timerResolutionMilliseconds`	long	The maximum timer resolution in milliseconds. This is the interval at which timers are examined. Higher resolution timers have more impact on system performance. Optional. Default value is `1000`.
`shutdownTimerSeconds`	long	Maximum time to wait for an engine to shut down before forcing it down with an error. Optional. Default value is 60.

Example 2. JVM object snippet

name = "java-engine-configuration"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.javaengine"
configuration =
{
    JavaEngine =
    {
        jvmTuning =
        {
            minimumDispatchThreads = 10
            maximumDispatchThreads = 2000
            shutdownTimerSeconds = 60             
            timerParallelism = 1
            timerResolutionMilliseconds = 1000
        }
    }
}

Administration

shows the screen that is used to monitor and control an engine. The information on this screen can also be displayed using this command:

epadmin --servicename=A.X display --engine name=sandbox_Timer0

This information is displayed for an engine:

Name — Engine name.
State — Current state.
Build Type — DEVELOPMENT or PRODUCTION build.
Fragment Type — Fragment type.
Fragment Identifier — Fragment identifier.
Fragment Version — Fragment version.
Target — Engine target, for example a Jar or class name.
Target Parameters — Engine parameters specified at deployment
EventFlow Fragment Client URI — URI to access an EventFlow fragment's client port.
LiveView Fragment Client URI — URI to access a LiveView fragment's client port.
EventFlow Fragment Secure Client URI — URI to access a LiveView fragment's secure client port.
Engine Data Area — Engine data area directory.
JMX State — Current JMX state.
JMX Service Address — Network address to connect with JMX.
JMX Service URL — Network URL to connect with JMX.
Install Timestamp — Time engine was installed.
Start Timestamp — Time engine was last started.
Stop Timestamp — Time engine was last stopped.
Exit Status — Exit status last time engine was stopped.
Shutdown Timeout Seconds — Number of seconds engine waits for engine to exit during shutdown.
Java Home — Java JDK/JRE path.
Debugger Port — Debugger port if enabled.
Suspend Type — Type of engine suspend if engine was suspended for debugging. Valid values are All, JVM, Fragment, or None.

Once an engine is deployed it can be started, suspended, and stopped. The target node must be in the Started state to start an engine.

These actions can also be performed from the command line:

//
//  Start an engine
//
epadmin --servicename=A.X start engine --name=sandbox_Timer0

//
//  Suspend an engine
//
epadmin --servicename=A.X suspend engine --name=sandbox_Timer0

//
//  Stop a running engine
//
epadmin --servicename=A.X stop engine --name=sandbox_Timer0