8. Managing Environment-Specific Properties/Variables¶
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 variables or environment properties). DPBuddy provides an extensible and flexible mechanism for managing environment properties. DPBuddy’s mechanism can be used instead of or in addition to any traditional approach for managing environment properties, such as specifying all properties for a given environment in a separate file. It can be used with the DPBuddy CLI (by virtue of configuration files) or from Ant.
Internally, Ant delegates property resolution to property helper classes described in the Ant User Manual. DPBuddy comes with a simple property helper implementation (a.k.a. “property provider”), which relies on property name transformation based on name prefixes. You can easily build property providers that use other mechanisms to resolve properties – XML files, external database, corporate CMDB and so on. This section describes the logic of DPBuddy’s default property provider.
DPBuddy’s property provider relies on prefixes to define property namespaces. For example, you can prefix all properties for the “test” environment with the “test.” prefix. When a property (e.g., dp.url) is requested by Ant, the property provider will check if test.dp.url is defined and if it is, it will return the value of this property. The property provider prepends each known prefix to the requested name of the property and checks if a property with this prefixed name exists. Once the existing property is found, its value is returned to the requesting task/command.
You can concatenate multiple prefixes together. For example, you could have a prefix for an environment and then a sub-prefix for a DataPower domain in that environment, such as “test.domain1.”. DPBuddy’s property provider will first check if a property with the prefix “test.domain1.” is defined. Then it will check if a property with the prefix “test. ” is defined. In other words, prefixes create a hierarchy of namespaces. You can define properties specific to a domain using the “test.domain1.” prefix and properties specific to the “test” environment using the “test.” prefix.
DPBuddy’s property provider uses ”.” as the prefix separator, which is consistent with Ant’s property naming style.
The prefix-based property management mechanism is completely generic and can be used to manage any set of properties, not just those related to DPBuddy and DataPower.
Properties containing prefixes are regular Ant properties; they can be defined in one or multiple properties files, or inline using the Ant “property” task. They can also be specified in the configuration files used by DPBuddy CLI.
Run DPBuddy in verbose mode (using -v) to see to see how the property provider resolves properties. Look for “Resolved property ...” lines in the log.
8.1. env/device Attribute/Option and environment Task¶
The environment prefix 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-specific properties and the prefix-based property resolution is used for non-DPBuddy tasks. In all other cases env/dp.env should be used.
dp.env globally defaults the environment prefix to its value for all DPBuddy tasks and commands.
The environment prefix can contain one or multiple sub-prefixes separated by ”.”. The trailing dot is not needed.
Once the prefix is set, the DPBuddy’s property provider will use the supplied set of prefixes for property resolution.
The environment task can be called multiple times within a build file. Each invocation will override the prefix defined earlier.
The environment prefix defined using env will only apply to the task where it was specified, it won’t be set globally.
You can also remove the environment prefix using the environment task by specifying an empty string as the value: prefix="".
Not that the DPBuddy’s property provider 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.
8.1.1. Attributes of the environment Task¶
| Name | Description | Required |
|---|---|---|
| prefix | Environment prefix consisting of dot-delimited sub-prefixes. DPBuddy will try to resolve a property by prepending each sub-prefix to the property name starting with the entire prefix string, then removing the last sub-prefix and trying the resulting prefix and so on. An empty value (prefix=””) will disable the DPBuddy’s property resolution mechanism. |
Yes |
| providerClass | Property provider implementation. The class has to implement the Defaults to DPBuddy’s property provider. |
No |
8.1.2. Examples¶
This example shows how properties can be defined at both the domain and the device level. We use two-part prefixes in the <device>.<domain> format:
<!-- 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 prefix to DPBuddy's provider for property resolution-->
<dp:environment prefix="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}"/>
See samples/ant-tasks/environment.xml file located in your DPBuddy distribution or online for more examples.