Bee Config - Java & Scala Configuration API

  • Bee Config provides a very simple Java and Scala API for loading configuration files.
  • Config files become Maps
  • Simplicity is the key!

Still often used in Scala applications, java.util.Properties is rarely satisfactory. Bee Config is broadly similar in intent, but pimped to work well in Scala. Why is Bee Config different: well, Properties files are sooo 20th Century. We need something similar, something as simple but something refreshed. We need to move on from ASCII to Unicode. We need standard collections support and string interpolations. And we need simplicity. That's it.

Simple Example

Just construct Config instances using the factory method.

val config = Config(new File("src/test/resources/sample1.txt"))

You can create a new Config instance from a File or anything that provides an InputStream. An obvious use of the latter is obtaining a class-path resource (equivalent to ClassLoader.getResourceAsStream(String)). When constructing a Config, you can include another Config as a fallback source of default values; this too can have a fallback so a chain of any length of them is possible.

val fallback = Config.fromClasspath("resources/default.txt")
val file = new File("/etc/myapp/config.txt")
val config = if (file.exists) Config(file, fallback) else fallback


  • Config files are like properties files, except they are always Unicode. UTF-8, UTF-16 and UTF-32 are supported (either word order); boms differentiate them. ASCII is supported as a subset of UTF-8. No other encodings are supported.
  • Configs can be loaded from files, from the classpath, from URLs, or from any other source that provides a
  • Configs can be cascaded to provide fallback values. The cascades form linked lists of any length.
  • String interpolation allows values to contain other values, or system properties or environment variables.
  • String interpolation also allows keys to contain other values, or system properties or environment variables. This can be used for conditional configurations!
  • Config values are evaluated once during construction and thereafter are immutable and thread-safe.
  • A configuration is an immutable ListMap and the full capability of Scala’s collections can be applied to its data.
  • Values can be enclosed by double-quote marks if whitespace is to be preserved in them. Otherwise any surrounding whitespace is trimmed.
  • Values can span multiple lines by ending each line with a single back-slash, then continuing on the next line. The newline characters are retained to form part of the value.
  • Values can contain comma-separated lists. These can use double-quotes to surround list elements, which may then contain commas. Backslash is used to mark the following character as a literal.
  • Values can have units. “60s” means sixty seconds. “8 KiB” specifies 8192 bytes. Fill your boots.
  • Comments are introduced by the ‘#’ character and run to the end of the line. They can appear anywhere that is not a double-quoted string.
  • Configs can contain sub-sections, and these are themselves configs. This provides, in effect, arbitrary nesting of sections. It is all controlled by key prefixes of your choosing.
  • INI-file sections are supported - these start with a [section] mark and they behave very similarly to nested sub-sections. These are optional.
  • Good Test Coverage via a comprehensive set of developer tests, providing assurance of the library’s quality.
  • No other external dependencies are needed.
  • Configs have a low memory footprint. Just a ListMap, nothing more.
  • Configs can be accessed via JMX if required.

Reloading Changed Files

If you want to read configuration from a file once at startup, fine that’s easy. If instead you want to read configuration from a file (or similar) which may change from time to time and you want the changes to be loaded automatically, there is support for this too.

Why Bee Config? Why Not xxx?

Several compelling attempts have been made recently to produce a new configuration API. No disrespect to these, so why not…

  • Typesafe Config - Nice one, but it is not simple. Also, being Java, it's a little awkward when Scala needs configuring.
  • Fig - Json might be popular but all those quote marks are a pain.
  • SnakeYaml (and other Yaml parsers) - a good idea but frustratingly I can't persuade my colleagues to adopt this stuff.

I hope you'll find Bee Config is a useful small alternative.