Managing Environment-Specific Configuration Settings

A typical organization uses multiple DataPower devices, and multiple domains in each device. Usually, at least one device is used for development and testing; multiple devices could be used in production.

Different devices have different IPs, ports and potentially other parameters (environment settings). DPBuddy provides an extensible and flexible mechanism for managing environment settings. This mechanism can be used instead of or in addition to any traditional approach for managing environment settings, such as specifying all settings for a given environment in a separate file.

DPBuddy supports two different formats for defining environment settings: HOCON and name=value properties. HOCON/JSON is much more powerful and expressive than properties and thus recommended for complex configurations.

env/device Attribute/Option and environment Task

The environment name is specified using the env attribute/option or the dp.env property. The env attribute/option is supported by all DPBuddy tasks/commands. DPBuddy also supports device attribute/option and dp.device aliases. env and device can be used interchangeably; it’s up to the user to decide which name to use.

DPBuddy also comes with the environment task described below. This task should be used if environment settings are used for non-DPBuddy tasks (e.g., if you want to “echo” the value of a property). In all other cases env/dp.env is sufficient.

dp.env globally defaults the environment name to its value for all DPBuddy tasks and commands.

The environment name can contain one or multiple elements separated by “.”. The trailing dot is not needed.

Once the environment name is set, DPBuddy provider will use this name for locating HOCON objects and for dealing with property prefixes.

The environment task can be called multiple times within a build file. Each invocation will override the name defined earlier.

The environment name defined using env attribute will only apply to the task where it was specified. In this case, the environment won’t be set globally.

You can also undefine the environment name using the environment task by specifying an empty string as the value: name="".

Note that the DPBuddy’s environment settings resolution mechanism does not propagate to Ant sub-projects. If you invoke another Ant file or target using Ant or AntCall, make sure to invoke environment in this sub-project.

Attributes of the environment Task

Name

Description

Required

name
prefix

Name of the target environment.

An empty value (name=””) will disable the DPBuddy’s environment settings resolution mechanism.

Yes

providerClass

Property provider implementation. The class has to implement the org.apache.tools.ant.PropertyHelper.PropertyEvaluator and com.myarch.propertyselector.PropertyProvider interfaces.

Defaults to DPBuddy’s property provider.

No

Examples

Using environment with HOCON configuration:

<dp:confText>
  dev: {proxy.port: 8080}
  test: {proxy.port: 7070}
</dp:confText>
<dp:environment name="test" />
<!-- Will print 7070 -->
<echo>{proxy.port}</echo>

Using environment with properties:

<!-- DataPower url is defined at the device level -->
<property name="devtestdevice.dp.url" value="https://devtest.dp" />
<!-- Each WS proxy has its own port in each of the domains -->
<property name="devtestdevice.devdomain.wsproxy.port" value="8082" />
<property name="devtestdevice.testdomain.wsproxy.port" value="9082" />
<!--Provide our name to DPBuddy's provider for property resolution-->
<dp:environment name="devtestdevice.devdomain" />
<!-- dp.url should point to devtest.dp url -->
<echo message="dp.url value: ${dp.url}"/>
<!-- the value of the port should be the one for the devdomain -->
<echo message="wsproxy.port value: ${wsproxy.port}"/>