HOCON Substitution Variables

< Previous		Next >

Overview

This article describes the use of HOCON substitution variables.

Substitution Variables

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

The substitutions= parameter of the epadmin install node or epadmin load configuration commands.
A substitution file specified using the substitutionfile= parameter of the same two epadmin commands.

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 is 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 letters (A-Z, a-z) digits (0-9), an underscore character ( _ ) or the dollar sign ($).
variable-name cannot start with a digit and must not contain the HOCON escape character (\).
variable-name cannot be a Java keywords.
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.
Closing braces (}) in substitution variable values must be escaped. For example:
```
roleSearchFilter = "${ROLESEARCHFILTER:-member={1\}}"
```
Nested substitution variables are not allowed (these are allowed by standard HOCON). For example:
```
foo = bar 
bar = biz 
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. This is an 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. This is an extension to standard HOCON.
Substitution variables are supported in quoted strings. This is an extension to standard HOCON.

Substitution Variable Example

The following is an example of a substitution variable in the configuration file header as well as in the body of the file.

Note

When using the HOCON Editor in StreamBase Studio, substitution variables without default values will be marked with a Warning marker. Nevertheless, projects containing configuration files like the sample below (without default values) can be run as shown from the epadmin command line.

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

Default Substitution Variable Value Example

The following example shows a configuration file that specifies a default for its substitution variable using the colon-hyphen (:-) syntax.

Note

When using the HOCON Editor in StreamBase Studio, substitution variables without default values will be marked with a Warning marker. Nevertheless, projects containing configuration files without default values can be successfully run.

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

There is a quick-fix in the HOCON editor to insert a default value for missing substitution variables in order to remove validation warnings.

Use the shortcut keys Control+1 for Windows OS or Command+1 for Mac OS to activate the quick fix.

If you press 'Enter', it changes to null value and the error is gone.

Lists in Substitution Variable Example

The following examples shows a configuration file that specifies a list in a substitution variable.

Note

When using the HOCON Editor in StreamBase Studio, substitution variables MUST be specified with default values in order to pass Studio typechecking. Nevertheless, configuration files without default values can be successfully run from the epadmin command line.

      {
       myProp = ${foo}
      }
         //
         //  svar file value is
         //
         foo = ["a","b","c"]
      //
      // Output will be List value for myProp.
      //

The output will be list value for myProp. Alternate ways of getting the list value is as shown in the examples below:

     
      {
       myProp = [${foo}]
      }
         //
         //  Prop file value will be like
         //
         foo = a,b,c
       //
       //  Output will be List value for myProp.
       //

OR

 
      { 
        myProp = [ a,b ${foo}] 
      } 
         // 
         // And 
         // 
         foo = ,c 
      // And so on

The output will be list value for myProp.

Built-in Substitution Variables

Built-in substitution variables are available. You can use built-in substitution variables anywhere in a configuration file where a standard substitution variable can be used. Built-in substitution variables do not need to specified. Built-in substitution variables include:

EP_NODE_NAME — node name.

The EP_NODE_NAME variable makes it easier to create elastic node deployment files such as:

name = "MyApplication"
version = "2.0"
type = "com.tibco.ep.dtm.configuration.node"
configuration = {
  NodeDeploy = {
    nodes = {
      "${EP_NODE_NAME}" = { ... }
    }
    availabilityZones = {
      zone1 = {
        dataDistributionPolicy = "dynamic"
      }
    }
  }
}