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: JSON and Properties files are expected to be UTF-8
• Note: The usage of variables (as in ${xyz}) to reference to other properties is available since v10.2.0
• Note: 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 (_).

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 \$.

Note: In case a variable is referenced, that is not resolved the handling can be customized.

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 (\)

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.

Configuration property resolution

Each configuration property is trying to be resolved in all configured sources. Each configured source is iterated in descending priority, so 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