ph config

A multi-source configuration manager, that can use system properties, environment variables, resources and application specific values to work with. See ConfigFactory.getDefaultConfig () for the starting point. By default the following configurations sources are scanned in this order:

1. System properties - priority 400
2. Environment variables - priority 300
3. if the system property config.resource or the environment variable CONFIG_RESOURCE is present, and it points to an existing classpath resource, the first one matching is used - priority 200 or determined by the system property config.resource.priority or the environment variable CONFIG_RESOURCE_PRIORITY. Note: the file type is determined by the extension and defaults to "properties".
4. if the system property config.resources (note the trailing "s") or the environment variable CONFIG_RESOURCES is present, and it points to an existing classpath resource, all matching ones are used - priority 200 or determined by the system property config.resources.priority (also note the trailing "s") or the environment variable CONFIG_RESOURCES_PRIORITY. Note: the file type is determined by the extension and defaults to "properties".
5. if the system property config.file or the environment variable CONFIG_FILE is present, and it points to an existing file, it is used - priority 200 or determined by the system property config.file.priority or the environment variable CONFIG_FILE_PRIORITY. Note: the file type is determined by the extension and defaults to "properties".
6. if the system property config.url or the environment variable CONFIG_URL is present, and it points to an existing URL, it is used - priority 200 or determined by the system property config.url.priority or the environment variable CONFIG_URL_PRIORITY. Note: the file type is determined by the extension and defaults to "properties".
7. a JSON file called private-application.json - this is mainly to have an easy way to override settings - priority 195.
8. a properties file called private-application.properties - this is mainly to have an easy way to override settings - priority 190.
9. all JSON files called application.json that are in the classpath - priority 185.
10. all properties files called application.properties that are in the classpath - priority 180.
11. all properties files called reference.properties that are in the classpath - priority 1.

• Note: the default configuration does NOT contain any custom configuration files. It is solely based on system properties and environment variables.
• Note: The usage of variables (as in ${xyz}) to reference to other properties is available since v10.2.0 (see below)
• Note: The usage of variable default values (as in ${xyz:default}) is available since v11.1.11 (See below)

Environment Variables

The name of the respective environment variables are created using EnvVarHelper.getUnifiedSysEnvName - they are basically mapped onto the regular expression [A-Z_]+[A-Z0-9_]* - each unsupported character is replaced with an underscore character (_).

Note: Environment variables names MUST be provided all uppercase.

Configuration Variables

Since ph-config 10.2.0 the usage of variables in configuration properties can be enabled (but was disabled by default). Since ph-config 11.0.2 the usage of variables is enabled by default. To disable usage of variables, call setReplaceVariables (false) on your existing Config project.

Variables are represents in the form ${name} where name is the name variable. During the resolution of configuration values, ${name} is replaced with the configuration item with the key name. A configuration value can contain zero, one or more variables. Configuration values with variables can reference other configuration values that also contain variables. Cyclic references between variables (e.g. key1 references key2 references key3 references key1 again) is detected and will lead to a non-resolution of variables in that particular value. Additionally a log message is emitted.

Example:

key1: value
key2: Also a ${key1}
key3: ${key2} but more ${key1}

Resolving key2 will lead to the string Also a value. Resolving key3 will lead to the string Also a value but more value.

Note: To represent the dollar sign ($) in a configuration value mask it with a backslash (\) as in \$. Also characters { and } can be masked with the backslash.

Note: In case a variable is referenced, a default value can be configured (see below for the details). In case a variable is referenced and not default value is provided, the handling can be customized.

Variable default values

Starting from ph-config 11.1.11 the usage of default values in configuration variables is supported.

The general format is to use ${configurationProperty:defaultValue}. This may be helpful to provide default values for a development environment. The syntax is aligned with the default value provision of Spring and Spring Boot.

Example:

key2: Example ${key1:default}

Resolving key2 with the existence of key1 with a value of test will lead to the value Example test. Resolving key2 without the existence of key1 will lead to the value Example default.

It is possible to provide multiple nested variables for resolution as in the following example:

key2: Example ${key1:${key3:default}}

First the property key1 is resolved. If it is not found, key3 is resolved and only if this one is not found either, the value default is returned.

Properties format

The Properties configuration file is ready according to the default Java Properties format.

Note: the # can be used to provide comments, but only if it is on the beginning of the line. In the form x=y # really the value of x is y # really!

Note: multiline values are possible when the first line ends with a backslash (\)

Note: Properties files must be encoded in UTF-8

JSON format

The JSON configuration file must be a single large object so it must start with "{" and end with "}". The JSON syntax is a bit relaxed and allows for unquoted names (as in key: "value") but other than that it is regular JSON.

Note: JSON files must be encoded in UTF-8

Configuration property resolution

Each configuration property is trying to be resolved in all configured sources. Each configured source is iterated in descending priority. In the default setup stated above system properties would be searched first, then environment variables and then the optionally available configuration files.

Maven usage

Add the following to your pom.xml to use this artifact:

<dependency>
  <groupId>com.helger.commons</groupId>
  <artifactId>ph-config</artifactId>
  <version>x.y.z</version>
</dependency>

Note: the Maven groupId changed in v10 from com.helger to com.helger.commons