refcodes-configuration: Managing your application's configuration

refcodes-configuration: Managing your application's configuration


The REFCODES.ORG codes represent a group of artifacts consolidating parts of my work in the past years. Several topics are covered which I consider useful for you, programmers, developers and software engineers.

What is this repository for?

This artifact provides means to read configuration data from various different locations such as properties from JAR files, file system files or remote HTTP addresses or GIT repositories.

Jump start

 1 import static org.refcodes.configuration.PropertiesSugar.*;
 2 // ...
 3 public class Foo {
 4   public void bar() throws IOException, ParseException {
 5     // ...
 6     PropertiesBuilder theProperties =  fromProperties( 
 7       toProperty( "message", "Hello world!" ),
 8       toProperty( "foo", "bar" )
 9     );
10     fileToTomlProperties( theProperties, "application.toml");
11     // ...
12     Properties thePrecedence = toPrecedence( 
13       fromSystemProperties(), 
14       fromEnvironmentVariables(), 
15       seekFromTomlProperties( "application.toml" )
16     );
17     FooConfig theConfig = thePrecedence.toType( FooConfig.class );
18     // ...
19   }
20   // ...
21   public static class FooConfig {
22     String message;
23     int frequency;
24     TemperatureUnit unit;
25     int port;
26   }
27   // ...
28 }

See also the blog post Dead simple Java application configuration.

How do I get set up?

To get up and running, include the following dependency (without the three dots “…”) in your pom.xml:

1 <dependencies>
2   ...
3   <dependency>
4     <artifactId>refcodes-configuration</artifactId>
5     <groupId>org.refcodes</groupId>
6     <version>1.3.0</version>
7   </dependency>
8   ...
9 </dependencies>

The artifact is hosted directly at Maven Central. Jump straight to the source codes at Bitbucket. Read the artifact’s javadoc at

If you also want to observe your properties (e.g. listen for create , update or delete operations), you may instead add the following dependency to your pom.xml:

1 <dependencies>
2   ...
3   <dependency>
4     <artifactId>refcodes-configuration-ext-observer</artifactId>
5     <groupId>org.refcodes</groupId>
6     <version>1.3.0</version>
7   </dependency>
8   ...
9 </dependencies>

The artifact is hosted directly at Maven Central. Jump straight to the source codes at Bitbucket. Read the artifact’s javadoc at

How do I get started?

Use the static import syntactic sugar to easily harness the refcoces-configuration features.

1 import static org.refcodes.configuration.PropertiesSugar.*;
2 // ...

Create some properties and play around with them:

1 // ...
2 PropertiesBuilder theProperties = fromProperties( 
3   toProperty( "/user/firstName", "Nolan" ),
4   toProperty( "/user/lastName", "Bushnell" ),
5   toProperty( "/commodore/user/firstName", "Jack" ),
6   toProperty( "/commodore/user/lastName", "Tramiel" )
7 );
8 // ...

The content of your properties looks as follows:

1 /user/firstName=Nolan
2 /user/lastName=Bushnell
3 /commodore/user/lastName=Tramiel
4 /commodore/user/firstName=Jack

The PropertiesBuilder inherits from the Map interface, it is fully compatible with the Java collections framework.

You may have noted that the keys in your properties look like path declarations. This is no coincidence, you can now manipulate your properties using (sub-)paths. See more in the article The canonical model, an ace upon your sleeve. E.g. you may now retrieve the commodore specific properties (the properties below the /commodore path):

1 // ...
2 Properties theCommodoreProperties = theProperties.retrieveFrom( "/commodore" );
3 // ...

This results in your commodore specific properties to look as such:

1 /user/lastName=Tramiel
2 /user/firstName=Jack

There are many more features hidden in the Properties type, just browse the Javadoc.

The Properties type is the read-only super-type of the PropertiesBuilder type. Common functionality produces Properties instances which easily can be converted into a mutable PropertiesBuilder instance as follows:

1 // ...
2 PropertiesBuilder theBuilder = toPropertiesBuilder( theCommodoreProperties );
3 // ...

Storing properties

Considering the example from above, storing properties is as easy as this:

1 // ...
2 ResourcePropertiesBuilder theResourceProperties = saveToTomlProperties( theProperties, "/some/path/to/my/properties.toml" );
3 // ...

You can make the library choose a suitable place for you where to save your properties to; being near the launcher (JAR) of your application:

1 // ...
2 ResourcePropertiesBuilder theResourceProperties = fileToTomlProperties( theProperties, "properties.toml" );
3 // ...

See the ConfigLocator on how a suitable location is determined by the library.

Loading properties

Considering the example from above, loading properties back again is as easy as this:

1 // ...
2 ResourcePropertiesBuilder theResourceProperties = loadFromTomlProperties( "/some/path/to/my/properties.toml" ):
3 // ...

You can make the library seek for a suitable properties for you to load; being near the launcher (JAR) of your application:

1 // ...
2 ResourcePropertiesBuilder theResourceProperties = seekFromTomlProperties( "properties.toml" );
3 // ...

See the ConfigLocator on how the properties file is discovered by the library and where it is to be placed.

Properties parsers

There are some notations being supported by the refcodes-configuration artifact:

  • Java based properties
  • INI based properties
  • TOML based properties
  • XML based properties
  • YAML based properties
  • JSON based properties

Please note that some notations use the this keyword to denote the value of the enclosing element as some notations do not support (or make it hard) to assign a value to an element which has child elements (see the blog post refcodes-logger regarding the various notations).

Profiles from properties

A profile is identified by the first level path hierarchy in your originating properties. In the example above, commodore represents a profile specific configuration which we can use to get our profile view:

1 // ...
2 Properties theProfile = fromProfile( theProperties, "commodore" );
3 // ...

We can also specify a property in our properties for the path /runtime/profiles identifying the profiles to be considered (comma separated).

See also the ProfilePropertiesProjection type as well as the ProfilePropertiesDecorator type on more usages.

Schedule reloading of properties

Using the ResourcePropertiesBuilder form above which we attached to a file, we now can schedule a reload of the properties:

1 // ...
2 ResourceProperties theScheduled = schedule( theResourceProperties, 5000, ReloadMode.ORPHAN_REMOVAL );
3 // ...

We actually encapsulate the properties with a schedule decorator which reloads the encapsulated properties accordingly: Reload them each 5000 milliseconds and remove any properties not found in the attached resource (e.g. File) from your properties instance.

Observe properties

You may also listen to any create, update or delete changes applied to your properties. To do so, you must encapsulate your ResourcePropertiesBuilder instance with an observable decorator of type ObservableResourcePropertiesBuilder. This observable fires a sub-type of the PropertyEvent upon updates applied to the properties to each subscriber of those events:

 1 import static*;
 2 // ...
 3 PropertiesBuilder theProperties = toPropertiesBuilder();
 4 ObservablePropertiesBuilder theObservable = observe( theProperties );
 5 theObservable.subscribeObserver( aEvent -> {
 6   if ( aEvent.getAction() == PropertyAction.PROPERTY_UPDATED ) {
 7     System.out.println( aEvent.getClass().getSimpleName() + " (" + aEvent.getAction() + ") --> " + aEvent.getKey() + " := " + aEvent.getValue() );
 8   }
 9 } );
10 theObservable.put( "/user/firstName", "Nolan" );
11 theObservable.put( "/user/lastName", "Bushnell" );
12 theObservable.put( "/user/firstName", "Jack" );
13 theObservable.put( "/user/lastName", "Tramiel" );
14 theObservable.remove( "/user/firstName" );
15 theObservable.remove( "/user/lastName" );
16 // ...

For the example above to work, make sure to include the refcodes-configuration-ext-observer dependency (see at the beginning of this article) in your project’s pom.xml.

The lambda being subscribed acts as a listener which is a functional interface of type PropertiesObserver with which you explicitly may listen to the three event types PropertyCreatedEvent, PropertyUpdatedEvent and PropertyDeletedEvent as well as to the super-type PropertyEvent.

Observing just the PropertyEvent type catches all of its sub-types (as we did in the example above).

Multiple properties precedence

We can combine multiple Properties instances behind a composite behaving just like a Properties type:

1 // ...
2 Properties theProperties = toPrecedence( 
3   fromSystemProperties(), 
4   fromEnvironmentVariables(), 
5   seekFromJavaProperties( "application.config" ) );
6 // ...

Above we created a composite containing various properties instances, the first one overrules the second one and the second one overrules the third one when accessing the resulting Properties composite.

Take a look at the SystemProperties as well as at the EnvironmentProperties instances we added: They provide means to access Java ‘s system properties or the operating system’s environment variables within your properties..

Under the hood

The canonical model pattern is an ace up your sleeve in order to open your libraries for functionality otherwise to be implemented in a tiresome, error prone and redundant way. As you settle upon a canonical model within your library, your library’s will be able to interact with any existing and yet to be implemented functionality on top of your canonical model, making your bits and pieces work together magically.

The CanonicalMap is the super-type of the Properties related types. Read more in the blog post The canonical model, an ace upon your sleeve.


For examples and usage, please take a look at the according Unit-Tests here. For examples and usage on the observable extensions, please take a look at the according Unit-Tests here.

Contribution guidelines

  • Finding bugs
  • Helping fixing bugs
  • Making code and documentation better
  • Implement other locations from which to load (or store) properties (such as GIT repository support)

Who do I talk to?

  • Siegfried Steiner (

Terms and conditions

The REFCODES.ORG group of artifacts is published under some open source licenses; covered by the refcodes-licensing (org.refcodes group) artifact - evident in each artifact in question as of the pom.xml dependency included in such artifact.

comments powered by Disqus