= Property Guidelines =

We'll be using [[http://hera/cgi-bin/viewcvs.cgi/sbutil/src/dk/statsbiblioteket/util/XProperties.java?rev=HEAD&content-type=text/vnd.viewcvs-markup|XProperties]] from [[SBUtil| 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).