Examples of How to Use rsh-config

This page provides some examples of how to use rsh-config. At its core, rsh-config strives to be as simple as possible while still maintaining flexibility.

A Typical Configuration

A very simple configuration would be something like the following:
foobar_config.properties

# Configuration for foobar
config.source.0.sysenv.type = SysEnv
config.source.0.sysenv.refreshinterval = 10000

# Add additional settings here ...
my.setting=value

Any settings contained in the foobar_config.properties file will then be read into the final Configuration, along with any values from the system environment. The system environment will override any settings contained in the file.

The format of the configuration source property nanes is as follows:

config.source.[PRIORITY].[SOURCENAME].[PROPERTY]

Where:

• [PRIORITY] is the priority in which this source is applied and considered ("Composite Configuration" below).
• [SOURCENAME] is the name of the configuration source. This can be anything you want, so long as it is unique within the config file (you can't have two "prop1" sources in foobar_config.properties).
• [PROPERTY] is any property name accepted by the ConfigurationSource implementation. The standard property is "type", which refers to what type of ConfigurationSource implementation is used. This value is either the fully-qualified classname, or it is the class name for an implementation in the "com.rshtech.config" package namespace.
  
  For a list of supported properties and settings for a ConfigurationSource, see its documentation (in API).

A Composite Configuration

The following configuration will build a composite configuration, built from the specified sources using the order declared:
foobar_config.properties

# Configuration for foobar
config.source.0.sysenv.type = SysEnv
config.source.0.sysenv.refreshinterval = 10000
config.source.1.prop1.type = Properties
config.source.1.prop1.sourcefile = in/the/filesystem/proptest1.properties
config.source.2.prop2.type = Properties
config.source.2.prop2.source = in/the/classpath/proptest2.properties

# Add additional settings here ...
my.setting=value

The numbers in the "config.source.N.*" now become more important. These describe the order the configuration files are applied. The number represents the prirority of the source, where lower numbers mean greater priority ("0" being the greatest priority). All numbers must be valid integers.

In the above configuration, the settings are applied, in greatest importance to least:

• System Environment
• The settings from the foobar_config.properties file itself
• Property file in/the/filesystem/proptest1.properties
• Property file in/the/classpath/proptest2.properties

The one that might be surprising is the settings from the foobar_config.properties file itself. These are added between 0 and 1 be default (you have no control over this). This means you can always trump the contents of the file with something like the system environment.

NOTE: if two sources have the same priority, they are applied in the order, sorted by name. Lesson being, don't share priority numbers ;-)

Getting a Configuration

Retrieving a configuration is very easy:

Configuration config = Configurations.get("foobar");

The Configurations utility will take the application name, append "_config.properties" and look for that file in the local directory. If the file is not found in the local directory, the root of the classpath is searched for the file. Once found, the configuration cached.

Using a Configuration

See the Configuration API documentation for details. Below, you will find some highlights of useful functionality:

Conversion

The Configuration contains convenient conversion methods. If a property's String value is meant to be used as an integer, you can call getInteger(propName). There are conversion methods for all the major java.lang objects.

Conversion to Lists and Arrays

In addition to the standard java.lang conversion methods, there are two methods for retrieving the value as a List or as a String array. The String value is split using the following regular expression pattern:

\\s*,\\s*

Subsets of Configurations

The Configuration interface supports using regular expressions for obtaining subsets of a Configuration (or a key set of the Configuration). You can use the regular expression to match certain sets of properties, and these would then be returned in a new Configuration instance (or a new Set of keys).

Configuration config = Configurations.get("foobar").subset("^foo\\.start.*");

This would return a configuration containing all the properties starting with "foo.start".