Each config source reads data from a location of a specific type, without regard to the format of the config data there. Each config parser converts data expressed in a particular format into the in-memory config data structure that the rest of the config system uses, without any concern for where that data resides or how it is physically retrieved. These two work together to prepare data in a given format at a given location for the config system. When your application prepares a Config.Builder it sets what ConfigSources and ConfigParsers the builder should use in constructing the resulting Config object.

If your application uses the default configuration, then the config system automatically sets up the config sources for you, as described in the config introduction.

If instead your application uses a Config.Builder, then it can invoke one of the sources methods on that builder to set which config sources it should use.

The config system includes support for several types of config sources, for example:

• a resource on the runtime classpath,

• environment variables,

• a file,

• Java system properties,

• a URL,

• a variety of in-memory data structures (String, Map, Properties)

See the JavaDoc for the ConfigSources class for a complete list of the built-in config source types and how to use them.

You can also extend the config system to handle other types of sources by implementing the ConfigSource interface. See the extensions documentation for complete information.

See the advanced topics page for further information on some more involved aspects of config sources.

When it reads configuration text from sources, the config system uses config parsers to translate that text into the in-memory data structures representing that configuration. The config system includes several built-in parsers, such as for the Java properties, YAML, JSON, and HOCON formats. See this section in the introduction for how to change your pom.xml to make parsers for those formats available to your application. Then your application can invoke the config builder’s addParser method so that builder will use the parsers you choose.

You can extend the system with custom parsers of your own. Implement the ConfigParser interface, then construct a Config.Builder using the addParser method, passing an instance of your customer parser. Invoke one of the sources methods to include a source that uses the custom format and then build the Config object.

Each Config object which the config system returns to your application is immutable; even if the information in one of the underlying config sources changes, an in-memory data structure built from the earlier content remains unchanged.

Even so, the config system allows your application to learn when such underlying changes in the data occur and respond accordingly. The mutability section explains this in detail, and the PollingStrategies JavaDoc describes the built-in implementations. You can, of course, write your own by implementing the PollingStrategy interface. On a config source builder invoke pollingStrategy with an instance of your custom strategy and then invoke build to create the ConfigSource.

Config sources, especially those that depend on fallible mechanisms such as the network or a shared file system, might fail to load during momentary outages. The config system allows you to build resiliency into your application’s use of configuration that relies on such technologies.

When your application builds a ConfigSource it can specify a retry policy. When the config system needs to load data from that source it delegates the load operation to that retry policy. That policy is responsible not only for loading the data but also for detecting errors during loading and implementing the algorithm for deciding when and how many times to retry a failed load before reporting a failure back to your application.

The config system includes two predefined retry policies:

See the RetryPolicies JavaDoc for complete details on these built-in retry policies.

You can devise your own policy. Implement the RetryPolicy interface. Then pass an instance of your policy implementation to the config source builder’s retryPolicy method.