.. highlight:: json .. index:: HOCON configuration file format .. _hoconConfig: 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: .. code-block:: js 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: .. code-block:: js // 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.: .. code-block:: js 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: .. code-block:: js 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. .. code-block:: js 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 :ref:`DPBUDDY_CONFIG environment variable ` pointing to the location of the config file or the ``-confFile`` option. 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: .. code-block:: xml "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. .. _confFile: ``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: .. code-block:: xml If multiple files contain the same property/object, the value from the last loaded file will take precedence. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 Examples ^^^^^^^^ .. code-block:: xml .. _confText: ``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: .. code-block:: xml The property defined in the last ``confText`` always takes precedence. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - Name - Description - Required * - text - Configuration in HOCON format. Configuration can also be provided using nested CDATA text. - Yes .. _confScope: ``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: .. code-block:: xml devDevice: {proxy.port: 7070} ${proxy.port} This task is similar to the :ref:`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. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - Name - Description - Required * - scopePath - Path to the object. - Yes