config

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 Using HOCON, the JSON Superset Features of HOCON Examples of HOCON Uses of Substitutions Factor out common values Inheritance Optional system or env variable overrides Concatenation Miscellaneous Notes Debugging Your Configuration Supports Java 8 and Later Rationale for Supported File Formats Other APIs (Wrappers, Ports and Utilities) Guice integration Java (yep!) wrappers for the Java library Scala wrappers for the Java library Clojure wrappers for the Java library Kotlin wrappers for the Java library Scala port Ruby port Puppet module Python port C++ port JavaScript port C# port Go port Linting tool Online playground 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. You can run these from the sbt console with the commands project config-simple-app-java and then run. In brief, as shown in the examples: libraries should use a Config instance provided by the app, if any, and use ConfigFactory.load() if no special Config is provided. Libraries should put their defaults in a reference.conf on the classpath. apps can create a Config however they want (ConfigFactory.load() is easiest and least-surprising), then provide it to their libraries. A Config can be created with the parser methods in ConfigFactory or built up from any file format or data source you like with the methods in ConfigValueFactory. Immutability Objects are immutable, so methods on Config which transform the configuration return a new Config. Other types such as ConfigParseOptions, ConfigResolveOptions, ConfigObject, etc. are also immutable. See the API docs for details of course. Schemas and Validation There isn't a schema language or anything like that. However, two suggested tools are: use the checkValid() method access your config through a Settings class with a field for each setting, and instantiate it on startup (immediately throwing an exception if any settings are missing) In Scala, a Settings class might look like: class Settings(config: Config) { // validate vs. reference.conf config.checkValid(ConfigFactory.defaultReference(), "simple-lib") // non-lazy fields, we want all exceptions at construct time val foo = config.getString("simple-lib.foo") val bar = config.getInt("simple-lib.bar") } See the examples/ directory for a full compilable program using this pattern. Standard behavior The convenience method ConfigFactory.load() loads the following (first-listed are higher priority): system properties application.conf (all resources on classpath with this name) application.json (all resources on classpath