Property Guidelines
We'll be using XProperties from sbutil. XProperties extends Properties, provides nested properties and a readable XML-format input/output format.
If the system property dk.statsbiblioteket.doms.config.url is set, the properties will be loaded from the resource from that url, otherwise the classpath will be searched for the resource.
Conventions
We use . (ie. a dot) for namespace separation, not underscores or other characters
All properties should be namespaced. Like myapp.threads.count, not just threadcount
Use meaningful names, if your application parses an external log file specified in a property, don't use myapp.file for specifying the input file. Use a for example myapp.input.log
Regarding namespaces: Please consider that the reason we enforce proper namespacing of properties is that we want the properties to be meaningful and unambiguous in the context of other applications and third party modules.
Nested Properties
From other projects it has been experienced that the flat property-value map is too limiting to be useful for rich configuration systems. To counter this problem it has been decided to use a system where nested properties is possible. Fx if prop is a Properties object prop.get("myapp.server.config") could return another Properties object with settings specifically for the server part of myapp.
- Defaults are specified in a separate file, typically placed in a JAR-file upon deployment.
- Nested defaults are possible and encouraged.
The name of a nested property must end in .config
Global Configuration
It is expected that our setup will involve a handful applications running on (possibly) differrent servers. To ease configuration we use one centralized configuration file located at one designated configuration server (needs http server) and pass the location as an URL to be loaded via the standard Java resource system.
Each module will have a sub-XProperties object within the global properties file.
Reloading Properties
For the purpose of changing configurations of running system we establish the following conventions:
- No way to reload property files, it is not possible to reload a configuration entirely without restarting the application
- Some properties might make sense to inspect and change on a running system. Such properties should be exposed over a JMX interface
Default Properties
- - Bundled as file in the .jar
Command Line Overrides
There are several variations of command line overrides for XProperties.
-DXProperty:foo=87 adds or overrides the value for foo with integer 87.
-DXProperty:bar=-12.1 adds or overrides the value for bar with double -12.1.
-DXProperty:zoo=true adds or overrides the value for zoo with boolean true.
-DXProperty:cat=Maine_Coon adds or overrides the value for cat with String "Maine_Coon".
-DXProperty:mysub/uboat=88 adds the sub-property mysub if it doesn't exist already and adds or overrides the value for uboat in mysub with integer 88.
More clever command line updates are under consideration (lists would be nice).