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 name of the property set (app) defines the prefix of the key, the name of the method (name) the suffix. The key to the property is therefore app.name. The key is only relevant to those who want to define a value to the property. The value is accessed through the interface.

While the PropertySet annotation is mandatory, the name of the set is not. If you omit the name, 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 the key app.name and the String value test.

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 (the interface) with their definitions (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();

Values may be provided by different store implementations, e.g. SQL databases.

Please note that the recommended way of creating configurations is by CDI injection.

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.

As you can see, the access is type safe. If the type was a complex type, say an URL, the defined text value would be resolved (e.g. if there is a placeholder to be substituted), converted to an URL instance and validated behind the scenes.

If you integrate smartics-properties with CDI, you will inject property sets and usually not interface with a configuration directly.

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 find answers to these topics in depth!