Introduction

smartics-properties is a library for Java to declare and define properties and to access them from an application in a convenient way. Convenience means that properties are easily

  1. declared (as an annotated Java interface)
  2. defined (e.g. in form of properties files on the classpath)
  3. resolved (e.g. construct properties with placeholders like ${server.url}/index.html)
  4. converted (e.g. to an URL or custom instance)
  5. validated (e.g. mandatory values or a value within a given range)
  6. accessed (typesafe)
  7. documented (e.g. to display error information to the user)

Properties are used to configure an application. This is what the well-known Properties class of the Java SDK is all about: Simple key/value tuples of type String. It is quite easy to load property files from a stream or from the class path. But a standardized way to provide property values is not provided out-of-the-boy. In other words: The developer has to define a location to place the properties file and write the couple of lines of code to access it. Once in memory, the developer has to manage the properties and make it accessible by all clients.

What would be more convenient if the developer declares the properties at one place and provides the property values at another. Often these tasks are executed by different people anyway. And without further ado the system makes the property values available through a simple API. This is what smartics-properties can do for you. Let's have a quick walk through the steps of declaring, defining and accessing properties with this library.

Property Declaration

Property Sets are declared as an interface like this: 

@PropertySet("app")
public interface Application {
  String name();
}

This example provides a simple String property. The property set defines the prefix of the key, the value is identical with the name of the method in the interface. While the PropertySet annotation is mandatory, the name of the set is not. If you leave the value for the annotation, the prefix defaults to the fully qualified class name of the property set interface. And if you do not want a prefix, simply provide the empty String as the property set name.

Property Definition

A property definition provides property values for declared properties. In this simple example we provide a properties file with the same name (including the package!) as the declaring class: Application.properties. 

app.name=test

This example provides a String property with key app.name. The is the key you surely have expected.

Configuration Creation

After declaring and defining the property we want to access it through a configuration. A configuration is a set of property sets. There are a couple of implementations for configurations. In the following example we use ClasspathConfigurationProperties: 

final ClasspathConfigurationPropertiesFactory factory = new ClasspathConfigurationPropertiesFactory();
final ClasspathConfigurationProperties config = factory.createManagement();
config.addClassPathProperties(Application.class);

Via a factory we create the configuration and explicitly instruct it to load the properties declaration with their definitions (that is the interface and the properties file).

If you do not want to do the loading stuff explicitly, you may choose an implementation that retrieves all properties from the classpath automatically. 

final ConfigurationPropertiesFactory factory =
    ConfigurationPropertiesFactoryFactory.createDefaultFactory();

final ConfigurationPropertiesManagement config =
    factory.createDefaultManagement();

Property Access

final Application app = config.getProperties(Application.class);
final String name = app.name();

Using the configuration created in the previous step, the last two lines of this short introduction access the property set instance and then read the property value name.

Summary

What we have seen is not very spectacular. We declared a property set with one property, provided a definition via a properties file on the classpath and showed how we can access it through the client API.

What would make the use more interesting is to see, how we

  • can access properties from other places like data sources or a property configuration server.
  • can provide properties other than String: URLs, numbers, collections, etc.
  • can validate our property values with constraints provided with the declaration.
  • can have documentation for the properties generated from Javadoc comments.

Please refer to the tutorials to cover answers to these topics in depth!