HOCON Syntax Reference

< Previous		Next >

Overview

This article describes the HOCON configuration syntax.

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.

StreamBase® extends standard HOCON in several ways, including:

Three lines that describe the file's name, version, and type properties must be present, traditionally placed at the top of the file as header lines. These three lines taken together uniquely identify the configuration realm and version of an individual configuration file.
StreamBase HOCON does not support the include keyword defined in the HOCON specification. Instead, StreamBase HOCON recognizes a multi-line array syntax within square brackets as a way to embed a subordinate configuration specification within another. Multi-line array syntax is bounded by three double-quote symbols. The brackets define an array:
```
[
"""
embedded configuration
"""
]
```
See Three-Quote Include Syntax below for an example.

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

Terminology

Refer to the following terms when using HOCON syntax:

Configuration Envelope

The structure of a StreamBase HOCON file is:

Three properties that identify the file as a whole, traditionally placed at the top of the file as the first three header lines.
A single brace-delimited configuration object. This object is referred to as the configuration envelope.
```
configuration = {
   ...
}
```

Root Object

Root objects are the first-level children of 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 one or more root objects for each type defined in the file. In the following example, LocalAuthenticationRealm and TrustedHosts are root objects:

configuration = {
  LocalAuthenticationRealm = { ... }
  TrustedHosts = { ... }
}

Object

Objects are descendants of a root object, with their contents delimited by braces. In the following example, nodes and availabilityZones are objects in this configuration.

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

Array

Arrays are properties with more than one argument, shown as a keyword whose contents are delimited by brackets. In the following example, jvmArgs is an array:

configuration = {
  JavaEngine =
  {
    jvmArgs = [
      "-Xmx3g"
      "-Xms512m"
      "-XX:+UseG1GC"
      "-XX:MaxGCPauseMillis=500"
      "-XX:ConcGCThreads=1"
    ]
  }
}

Property

Properties are key-value declarations that do not contain an object or an array. For example, minimumDispatchThreads in the following configuration is a property.

configuration = {
  JavaEngine = {
    jvmTuning = {
      minimumDispatchThreads = 10
    }
  }
}

HOCON File Names and Encoding

StreamBase 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 node.conf. These file names are not required, but are suggested starting points.

It is a best practice using the last element of the type name as the basename, or an abbreviation of the last element. This allows a configuration file's contents to be known by their names, without opening the file. For example, a configuration file named sbengine.conf tells you at a glance that it contains a configuration of type com.tibco.ep.streambase.configuration.sbengine. The file app.conf contains a configuration of type com.tibco.ep.dtm.configuration.application.

Configuration files are loaded in alphabetic order by file name. You may need to name a collection of configuration files so that, for example, a defined name for a security realm is loaded before that realm's name is referenced in other configuration files.

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

Headers and Envelope

Every configuration file must contain header lines that specify the configuration type, name, and version of the file, which are all string values. The header lines are traditionally placed as the first three lines at the top of each StreamBase HOCON file, but this is a convention, and is not enforced.

Traditionally following the header lines, specify a configuration envelope in which all configuration specifications are contained. The configuration specifications allowed within the configuration envelope is defined by the configuration type specified in the header lines.

The supported configuration types are:

Runtime Configuration Types

To specify and manage StreamBase Runtime applications, nodes, engines, and to configure all security realms and profiles.

StreamBase Configuration Types

To specify and manage features of StreamBase EventFlow fragments running in a StreamBase Runtime node; to manage the Artifact Distribution Service; and to manage Cluster Monitor applications.

LiveView Configuration Types

To specify and manage features of LiveView fragments running in a StreamBase Runtime node.

Comment Characters

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).

Prior to StreamBase 10.3.0, substitution variables commented AND inside a quoted string were ignored. Starting with 10.3.0 they are no longer ignored.

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 that escape characters in front of substitution variable definitions are ignored. For example:

configuration = 
{
    name = \${value}
}

The above is processed as the following, with the escape character stripped:

configuration = 
{
    name = ${value}
}

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

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

The above is processed as the following, with the substitution variable escaped:

configuration = 
{
    name = \${value}
}

Units Formatting

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.

Date Syntax

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.

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"

Three-Quote Include Syntax

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 property.

The embedded configuration file is bounded by a pair of triple quotes (""") within a pair of square brackets.

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

Note

Configuration embedded with the three-quote syntax into the global and per-node sections of a node deployment configuration file are only processed when the node deployment file is passed to epadmin install node. Any subordinate configuration in these sections is ignored when loading or activating configuration using the epadmin load configuration and epadmin activate configuration commands.

HOCON Configuration File Editor

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.