.. highlight:: xml .. index:: Managing Environment Variables .. _managing_env_vars: 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 the virtue of configuration files) or from Ant. Internally Ant delegates property resolution to the property helper classes described in the `Ant User Manual `_. DPBuddy comes with a simple property helper implementation (a.k.a. "property provider") that 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 pre-pends 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 the ones 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. You can define the ``dpbuddy.trace.properties`` property and set it to ``true`` if you need to see how the property provider transforms property names. You will need to run Ant in verbose mode (-v option) to see this output. .. _environment_task: ``env`` Attribute/Option and ``environment`` Task ------------------------------------------------- The environment prefix is specified using the ``environment`` task, the ``env`` attribute/option or the ``dp.env.prefix`` property. The ``env`` attribute/option is supported by all DPBuddy tasks/commands. ``dp.env.prefix`` defaults the environment prefix to the value of this property for all DPBuddy tasks and commands. The environment prefix can contain one or multiple sub-prefixes separated by ".". The trailing dot is not needed. Setting the ``env`` attribute/option is equivalent to invoking the ``environment`` task right before the current task. 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. Similarly, ``env`` attribute/option updates the environment prefix value defined earlier. All subsequent tasks will use the new value. You can also remove the environment prefix by specifying an empty string as the value: ``prefix=""``. Attributes of the ``environment`` Task ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - Name - Description - Required * - prefix - Environment prefix consisting of dot-delimited sub-prefixes. DPBuddy will try to resolve a property by pre-pending each sub-prefix to the property name starting with the entire prefix string, then cutting the ending 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 ``org.apache.tools.ant.PropertyHelper.PropertyEvaluator`` and ``com.myarch.propertyselector.PropertyProvider`` interfaces. Defaults to DPBuddy's property provider. - No Examples ^^^^^^^^ This example shows how properties can be defined at both the domain and the device level. We use two-part prefixes in the . format: .. code-block:: xml .. code-block:: xml .. code-block:: xml See ``samples/ant-tasks/environment.xml`` file located in your DPBuddy distribution or `online `_ for more examples.