9. HOCON/JSON Configuration Format

DPBuddy supports specifying configuration settings (properties and variables, including environment-specific properties) in a JSON-like format, called HOCON. HOCON is a JSON superset: it can support strict JSON but it also allows for a less restrictive notation. HOCON format allows for comments, it does not require quotes, it supports variable substitution and includes. For more details, please refer to HOCON documentation.

For example, this is a valid HOCON fragment:

devDevice: {
    dpUrl: dp.mydomain
    dpUsername: dpbuddy
    // use dpbuddy encrypt command to encrypt passwords
    dpPassword: "ENC{NIR5xVHWngkGpsBA/Y9YT4KTDtgAPiBN}"
}

You can also specify properties in a HOCON file without the need for enclosing JSON object:

// release info for the audit file
dp.release.info="release 3.3"

HOCON format is better suited for defining complex configuration than properties files. It is a preferred way to define DataPower/DPBuddy configuration.

HOCON can be used very effectively for managing environment-specific settings. You simply need to define a HOCON object with the name of your environment. All properties of this object will be scoped to that environment.

E.g.:

dev: {
  dpDomain: devdomain
  proxyPort: 8080
}

test: {
  dpDomain: testdomain
  proxyPort: 8090
}

Once the environments are defined, you can provide the name of the environment to DPBuddy using the -env command line option or dp.env Ant property.

You can also specify environment-specific values for any simple property that defines a single value, e.g., a port number:

dp.wsproxy.port: { _env: true, dev: 7096, test: 8087, preprod: 9096, prod1: 5096, prod2: 5096 }

If the special key _env is set to true, DPBuddy will use the name of the environment to select the value. I.e., it will use 7096 for dev, 8087 for test and so on.

In addition, DPBuddy supports the _default keyword. This value will be used if the environment name is not listed. In case of the definition below, the value “7096” will be used for the environments “dev” and “test” since their values are not defined explicitly.

dp.wsproxy.port: { _env: true, _default: 7096, preprod: 9096, prod1: 5096, prod2: 5096 }

In Ant HOCON configuration can be specified using confFile and confText tasks. These tasks make HOCON configuration available to Ant scripts via regular Ant properties/variables.

E.g., if you define a HOCON object myProp:{nestedProp1:{netstedProp2:value}}, you can reference its properties it by using ${myProp.nestedProp1.nestedProp3} expression in Ant.

DPBuddy CLI supports dpbuddy.conf file where HOCON configuration is defined by default.

You can have any number of confFile and confText in your Ant scripts. DPBuddy combines objects and properties from all confFile/confText together. If the same property or an object is defined multiple times, the last definition always takes precedence.

HOCON properties/objects also override Ant properties with the same path. Consider the following example:

<property name="gateway.port" value="8080" />
<dp:confText text="gateway.port: 9090"/>

“9090” will be the value used by Ant/DPBuddy since it was defined last.

Note that this is different from the standard behavior of Ant properties where it is not possible to override a property that was already defined (unless local task is used).

You can, however, specify Ant properties on the command line using -D to override properties defined using HOCON.

9.1. confFile

confFile loads HOCON configuration from a file and makes it available to Ant. You can have multiple confFile tasks in your scripts, the configuration from all files is merged together:

<dp:confFile file="dpbuddy.conf" />
<dp:confFile file="anotherConfFile.conf" />

If multiple files contain the same property/object, the value from the last loaded file will take precedence.

9.1.1. Attributes/Options

Name	Description	Required
file	Path to the configuration file.	Yes
required	If set to true, raise an error if the file does not exist. Defaults to true.	No

9.1.2. Examples

<dp:confFile file="dpbuddy.conf" />
<dp:confFile file="${config.home}/dpbuddy-override.conf" required="false"/>

9.2. confText

confText loads HOCON configuration specified inline in its text attribute and makes it available to Ant. You can have multiple confText tasks in your scripts, the configuration from all tasks is merged together. It is also merged with the configuration defined using confFile.

You can use confText to override configuration properties defined using confFile and vice versa:

<dp:confFile file="dpbuddy.conf" />
<dp:confText text="devDevice: {dpPassword: dpbuddy3}" />

The property defined in the last confText always takes precedence.

9.2.1. Attributes/Options

Name	Description	Required
text	Configuration in HOCON format. Configuration can also be provided using nested CDATA text.	Yes

9.3. confScope

confScope makes properties of an object referenced by scopePath available to Ant. It allows for addressing these properties directly without specifying the full path:

<dp:confText>
    devDevice: {proxy.port: 7070}
</dp:confText>
<dp:confScope scopePath="devDevice"/>
<echo>${proxy.port}</echo>

This task is similar to the environment task, except that it only applies to the properties/objects defined using confFile/confText. prefix of the environment task applies to HOCON objects and to “regular” Ant properties.

9.3.1. Attributes/Options

Name	Description	Required
scopePath	Path to the object.	Yes

To document: In environment properties – mention that it is deprecated, update hocon