Configuration library for JVM languages.

Overview

• implemented in plain Java with no dependencies
• supports files in three formats: Java properties, JSON, and a human-friendly JSON superset
• merges multiple files across all formats
• can load from files, URLs, or classpath
• good support for "nesting" (treat any subtree of the config the same as the whole config)
• users can override the config with Java system properties, java -Dmyapp.foo.bar=10
• supports configuring an app, with its framework and libraries, all from a single file such as application.conf
• parses duration and size settings, "512k" or "10 seconds"
• converts types, so if you ask for a boolean and the value is the string "yes", or you ask for a float and the value is an int, it will figure it out.
• JSON superset features:
  • comments
  • includes
  • substitutions ("foo" : ${bar}, "foo" : Hello ${who})
  • properties-like notation (a.b=c)
  • less noisy, more lenient syntax
  • substitute environment variables (logdir=${HOME}/logs)
• API based on immutable Config instances, for thread safety and easy reasoning about config transformations
• extensive test coverage

This library limits itself to config files. If you want to load config from a database or something, you would need to write some custom code. The library has nice support for merging configurations so if you build one from a custom source it's easy to merge it in.

Table of Contents generated with DocToc

• Essential Information
  • License
  • Binary Releases
  • Release Notes
  • API docs
  • Bugs and Patches
  • Build
• Using the Library
  • API Example
  • Longer Examples
  • Immutability
  • Schemas and Validation
  • Standard behavior
    • Note about resolving substitutions in reference.conf and application.conf
  • Merging config trees
  • How to handle defaults
  • Understanding Config and ConfigObject
  • ConfigBeanFactory

Essential Information

Binary Releases

Typesafe Config is compatible with Java 8 and above.

You can find published releases on Maven Central.

<dependency>
    <groupId>com.typesafe</groupId>
    <artifactId>config</artifactId>
    <version>1.4.4</version>
</dependency>

sbt dependency:

libraryDependencies += "com.typesafe" % "config" % "1.4.4"

Link for direct download if you don't use a dependency manager:

• https://repo1.maven.org/maven2/com/typesafe/config/

Release Notes

Please see NEWS.md in this directory, https://github.com/lightbend/config/blob/main/NEWS.md

API docs

• Online: https://lightbend.github.io/config/latest/api/
• also published in jar form
• consider reading this README first for an intro
• for questions about the .conf file format, read HOCON.md in this directory

Bugs and Patches

NOTE: Please read Readme #Maintained-by before spending time suggesting changes to this library.

Report bugs to the GitHub issue tracker. Send patches as pull requests on GitHub.

Before we can accept pull requests, you will need to agree to the Akka Contributor License Agreement online, using your GitHub account - it takes 30 seconds. You can do this at https://contribute.akka.io/contribute/cla

Please see CONTRIBUTING for more including how to make a release.

Build

The build uses sbt and the tests are written in Scala; however, the library itself is plain Java and the published jar has no Scala dependency.

Using the Library

API Example

import com.typesafe.config.ConfigFactory

Config conf = ConfigFactory.load();
int bar1 = conf.getInt("foo.bar");
Config foo = conf.getConfig("foo");
int bar2 = foo.getInt("bar");

Longer Examples

See the examples in the examples/ directory.

This is the beginning of the README. Read the rest at the original. Read the full README ↗