HOCON Syntax Reference

This article describes the HOCON configuration syntax.

The configuration syntax for StreamBase is Human-Optimized Configuration Object Notation (HOCON). HOCON is a superset of JavaScript Object Notation (JSON), enhanced for readability. The specification for HOCON syntax is found here. Features in HOCON that are unchanged from JSON are described here.

TIBCO StreamBase extends standard HOCON in several ways, including:

Further differences between standard HOCON format and configuration file syntax are described below.

StreamBase runtime, non-runtime StreamBase, and Live Datamart configuration files must have a suffix of .conf. The basename of the file can be any valid name supported by the underlying operating system. There is no special significance associated with the file name; that is, configuration files can be named anything that reminds you of their contents.

Certain configuration file types are generated by StreamBase Studio with conventional names, such as engine.conf and node.conf. These file names are not required, but are suggested starting points.

A configuration file's character encoding can be UTF-8, UTF-16, or UTF-32 as defined by the JSON specification.

Every configuration file must start with a header that contains the configuration type, name, and version identifiers. These identifiers are all string 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:

StreamBase Runtime configuration types, to specify and manage StreamBase Runtime applications, nodes, engines, cluster monitoring, and the node-to-node security realm.

StreamBase configuration types to specify and manage features of StreamBase EventFlow Fragments running within a StreamBase Runtime node.

Live Datamart Configuration types to specify and manage features of Live Datamart EventFlow fragments running in a StreamBase Runtime node.

name = "integration-test-application"
version = "10.1.0"
type = "com.tibco.ep.dtm.configuration.application"

configuration =
{
//your configuration data specific to configuration type
}

As in standard JSON and standard HOCON, any text between // or # and the next newline is considered a comment and is ignored (unless the // or # is inside a quoted string).

Configuration files provide substitution variable support, where the substitution variable values come from (in priority order):

For example, if the same substitution variable value is specified as both a Java system property and using install node's substitutions parameter, the value specified in the 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:

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

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

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}
}

The values in configuration objects follow the standard HOCON syntax, including support for unit formatting (for example: ms, bytes, MB, and so on). The complete list of the standard supported unit formatting can be found here.

The supported date formats for date fields are:

Example:

//   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"

HOCON configuration files can be embedded in another configuration file. The following example shows a complete node configuration file defined by its header lines at the top, that embeds an entire sbclientapilistener configuration file starting just below the fragmentIdentifier keyword. The embedded configuration file is bounded by a pair of triple quotes (""") within a pair of square brackets.

(The embedded type= line is broken artificially into two lines for clarity, but that must be a single long line in practice.)

name = "NodeDeployment"
version = "1.0"
type = "com.tibco.ep.dtm.configuration.node"
configuration = {
  NodeDeploy = {
    nodes = {
      "B.sbuser" = {
        engines = {
          engine1 = {
            fragmentIdentifier = "com.example.sample_operator"
            configuration = 
            [
              """
              name = "myapilistenersettings"
              version = "1.0.0"
              type = "com.tibco.ep.streambase.configuration.
                      sbclientapilistener"
              configuration = {
                ClientAPIListener = {
                  apiListenerAddress = {
                    portNumber = 10000
                  }
                }
              }
              """
            ]
          }
        }
      }
    }
  }
}

The HOCON Configuration File Editor is a validating HOCON editor that is aware of the structure that defines the HOCON syntax of StreamBase configuration files.

See HOCON Configuration File Editor for instructions on using the Editor.