Configuration syntax
Prev Chapter 8. Reference Next

Configuration syntax

The configuration syntax is Human-Optimized Configuration Object Notation (HOCON). HOCON is a superset of JavaScript Object Notation (JSON), enhanced for readability. The standard HOCON syntax can be found here. This section focuses on the conventions used to specify configuration data and any differences between the syntax supported in configuration files and the standard HOCON syntax.

Configuration data is contained in a file that must have a suffix of .conf. The file name can be any valid file name supported by the underling operating system. There is no special significance associated with the file name, i.e. configuration files can be named anything you want.

The file character encoding can be UTF-8, UTF-16 or UTF-32 as defined by the JSON specification.

There is no support for include directives in configuration files. This is different behavior than standard HOCON, which allows include directives.

Headers and envelope

Every configuration file must start with a header that contains the configuration type, name, and version identifiers. These identifiers are all strings values. Following the header, a configuration envelope must be specified in which the configuration data is contained. The configuration data allowed within the configuration envelope is defined by the configuration type specified in the header. The supported configuration types are:

Example 8.5. Configuration header and envelope

//
//    Header values
//
name = "integration-test-application"
version = "10.0.0"
type = "com.tibco.ep.dtm.configuration.application"

//
//    Configuration envelope
//
configuration =
{
    // configuration data specific to configuration type
}


Terminology

These terms are used to describe configuration data:

  • Root Object - Root objects are the first-level children in the configuration envelope for a type. Each type defines one or more root objects. A configuration envelope – that is, a single .conf file – can contain zero or one root objects for each schema defined. For example, LocalAdminAuthenticationRealm and TrustedHosts are root objects in this configuration.

    configuration =
{
    LocalAdminAuthenticationRealm = { ... }
    TrustedHosts = { ... }
}

  • Object - Objects are descendants of a root object and its contents are delimited with braces. For example, nodes and availabilityZones are objects in this configuration.

    configuration =
{
    NodeDeploy =
    {
        nodes = { ... }
        availabilityZones = { ... }
    }
}

  • Array - Arrays are a keyword whose contents are delimited with brackets, such as jvmArgs in this configuration. Each item in an array can be delimited with an optional comma (,).

    configuration =
{
    JavaEngine =
    {
        jvmArgs = 
        [
            "-Xmx1024m",
            "-Xms512m",
            "-XX:MaxPermSize=768m",
            "-Xdebug",               
            "-Xnoagent"                   
            "-Djava.compiler=NONE',                         
            "-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"
        ]
    }
}

  • Property - Properties are fields that do not contain an object or an array. For example, minimumDispatchThreads is a property in this configuration.

    configuration =
{
    JavaEngine =
    {
        jvm =
        {
            minimumDispatchThreads = 10
        }
    }
}

Substitution variables

Substitution variable support is provided in configuration files. Substitution variables are specified as parameters to certain epadmin commands, either directly on the command line, or using a substitution file. In all cases substitution variables are merged using these rules (in priority order):

  1. substitutions parameter to install node (see the section called “install command”) or load configuration (see the section called “load command”).

  2. a substitution file specified using the substitutionfile parameter to install node (see the section called “install command”) or load configuration (see the section called “load command”).

For example, if the same substitution variable value is specified in a substitution file using the install node substitutionfile parameter and also in the substitutions parameter, the value specified in the substitutions parameter would be used.

There is no support for using an environment variable value as a substitution variable value. This is different behavior than standard HOCON, which allows environment variable values to be used as a substitution variable value.

Substitution variables must follow these rules:

  • Defined using ${<variable-name>[:-<default-value>]}. This defines a substitution variable named <variable-name> with an optional default value of <default-value>.

  • <variable-name> can only contain characters specified by this regular expression [a-zA-Z0-9\\.-_]+.

  • <variable-name> cannot contain the HOCON escape character (\).

  • Substitution variable values, and <default-value> expressions, cannot contain unescaped newlines. Escaped newlines (\\n) are permitted, and will result in a newline character appearing in the substituted value.

  • Nested substitution variables are not allowed (these are allowed by standard HOCON). For example, 

    foo = bar
bar = biz

${${foo}}  // returns an error instead of the value biz

  • Substitution variables are supported anywhere in a configuration file, including the left-hand side of an assignment (extension to standard HOCON).

  • Substitution variables on the left-hand side of an assignment that contain the "." character must be surrounded with double quotes to prevent the value from being interpreted as a HOCON path (extension to standard HOCON)

  • Substitution variables are supported in quoted strings (extension to standard HOCON).

Example 8.6, “Substitution variables” and Example 8.7, “Default substitution variable value” show examples of the substitution variable rules.

Example 8.6. Substitution variables

//
//    Setting substitution variables on command line
//
epadmin load configuration source=my.conf substitutions="NODE_NAME=A.X,PROJECT_VERSION=1.0"

//
//    Use substitution variable in configuration file header
//
name     = "integration-test-application"
version  = ${PROJECT_VERSION}
type     = "com.tibco.ep.dtm.configuration.node"
configuration =
{
    NodeDeploy =
    {
        nodes =
        {
            //
            //    Use substitution variable on left-hand side
            //    of an assignment in a quoted string
            //
            "${NODE_NAME}" = { ... }
        }
    }
}

Example 8.7. Default substitution variable value

configuration =
{
    ApplicationDefinition =
    {
        execution
        {
            dataTransport =
            {
                //
                //    Default value of 10 if not specified
                // 
                nodeActiveTimeoutSeconds = ${TIME_OUT_VALUE:-10}
            }
        }
    }
}


Escaping characters

Per the standard HOCON specification, the \ escape character is used to escape the next character in the file. In all cases, except one, the escape character is significant and must follow the standard HOCON parsing rules. The one exception is escape characters in front of substitution variable definitions are ignored. For example,

configuration = 
{
    name = \${value}
}

//
//   Processed as (escape character stripped)
//
configuration = 
{
    name = ${value}
}

To escape the $ character that starts a substitution variable definition use:

configuration = 
{
    name = \\\${value}
}

//
//    Processed as (substitution variable escaped)
//
configuration = 
{
    name = \${value}
}

Built-in substitution variables

Built-in substitution variables are available. Built-in substitution variables can be used anywhere in a configuration file where a standard substitution variable can be used. Built-in substitution variables do not need to specified as described in the section called “Substitution variables”. These are the built-in substitution variables:

  • EP_NODE_NAME - node name.

Data value syntax

The values in configuration objects follow the standard HOCON syntax, including support for unit formatting, e.g. ms, bytes, MB. The complete list of the standard supported unit formatting can be found here.

Dates

The supported date formats for date fields are:

  • ISO8601 combined date and time - yyyy-MM-dd'T'HH:mm:ss

  • ISO8601 with milliseconds - yyyy-MM-dd'T'HH:mm:ss.SSS

  • Time only - HH:mm:ss.

//
//   Date value with timezone
//
dateValue = "1970-01-30T12:34:00"

//
//    Date value with milliseconds
//
dateValue = "1970-01-30T12:34:00.100"

//
//   Time-only date value
//
dateValue = "12:34:56"

Embedded configuration

HOCON configuration files embedded in another configuration file, e.g. the section called “NodeDeploy”, must be embedded in a triple (""") quote.

    NodeDeploy =
    {
        globalConfiguration = 
        [
            //
            //    Embedded configuration must be triple quoted
            //
            """
            name = "mysecurity"
            type = "com.acme.security.keystore"
            version = "1.0.0"
            configuration =
            {
                CommunicationSecurity =
                {
                    keyStore = "myKeyStore.jks"
                    keyStorePassword = "secret"
                }
            }
            """
        ]
    }
Prev Up Next
Command line interface Home Default logging configuration