Configuration API

This tutorial covers some of the more advanced features and use the BeNOW Web API.

Contents

About the Configuration API
Configuration Entries
Persistence Engines
Customising Configuration

About the Configuration API

The Configuration API is used to expose configurable functionality to the user. It is designed to be easy to specify and maintain by the programmer, and easy to override by the application administrator.

Configuration entries are declared in code. These entries live in the same classes where they are used, so that they can easily be found and documented by programmers. The entries are used in code and behaviour is modified accordingly. Users of the application can extract the entries to configuration stores and override the entries as required.

Configuration Entries

Configuration entries are declared as constants in the Java class where they are used. An example declaration and use might be:

package some.package;

import org.benow.java.config.entry.StringConfigurationEntry;

public class MyClass {
  public static final StringConfigurationEntry CFG_TEST=
    new StringConfigurationEntry("test","a default value",
      "this is a test configuration entry");
      
  public static void main(String[] args) {
    System.out.println(CFG_TEST+" is "+CFG_TEST.getStringValue());
  } 
}

A StringConfigurationEntry is defined with a name, value and description. The value of the entry is then printed when the application is run. As will be shown in Customising Configuration, an alternate value can be specified by the user.

There are many types of configuration entries, as shown in the javadoc for org.benow.java.config.entry package, and custom entries can be created. The default entries are:

StringConfigurationEntry: An entry which holds a single, or multiple string values
StringMapConfigurationEntry: An entry which holds a mapping of string keys to values
BooleanConfigurationEntry: An entry which holds a single, or multiple boolean values
ClassConfigurationEntry: An entry which one or more class values. Convenience methods include getClassValue(), getClassValues() and getInstances(), which returns a list of instantiated classes (via default constructor).
FileConfigurationEntry: An entry which one or more file values. Values may optionally be asserted to be existing and/or directories which may be created if they don't exist.
IntegerConfigurationEntry: An entry which one or more integer values.
URLConfigurationEntry: An entry which one or more URL values.

These entry classes can be used to easily access configuration values of certain types, in addition to enforcing constraints on values.

Persistence Engines

Configuration entries are persisted by a persistence engine, which implements the ConfigurationPersister interface. Persisters are responsible for saving and loading of configuration entries. By default, only changed entries are persisted, so the absence of a persistence store only indicates that no values have been overriden. The default persister is the XMLConfigurationPersister, which persists xml files (one per package) in the etc/config/ directory. Another configuration persister is the PropertiesConfigurationPersister which persists to the etc/config.properties file.

To specify an alternate persister, provide a class name for the org.benow.java.config.Configuration parameter when starting the vm, ie:

java -Dorg.benow.java.config.Configuration=org.benow.java.config.persist.PropertiesConfigurationPersister \ 
     some.package.MyClass

In practice, the XML persister works well, and alternate configuration should not be required.

To implement your own persister, extend the ConfigurationPersisterImpl class and implement the abstract methods.

Customising Configuration

Default configuration entries, as specified in Java code, can be extracted for overriding. Once overridden, the overridden value will be used instead of the default value (as declared in code).

If you are managing the configuration from within a web application, you are best to so via the configuration web interface. For other applications, the ConfigUtil utility exists to facilitate entry extraction for overriding, and also provides listing and searching of entries. Use ConfigUtil, by running

In Linux/Un*x
  bin/configUtil.sh [--search val] [--extract val] [--list] [--help]
In Windows:
  bin/configUtil.bat [--search val] [--extract val] [--list] [--help]

if bin/configUtil.[sh|bat] exists. If not, it can be run manually via:

In Linux/Un*x:
  java -cp benow-java.jar:lib/java/log4j.jar[:other.jars] org.benow.java.config.ConfigUtil \
    [--search val] [--extract val] [--list] [--help]
In Windows:    
  java -cp benow-java.jar;lib/java/log4j.jar[;other.jars] org.benow.java.config.ConfigUtil \
    [--search val] [--extract val] [--list] [--help]

The possible arguments are as follows:

--list: lists all known entries. Be sure to have all required jars on the classpath.
--search [term]: search for entries containing a given term. Entry names and descriptions are matched case-insentively.
--extract [entryName]: extract the given named entry so that it may be overriden. If using the default (XML) persister, entries are extracted to XML files in etc/config corresponding to the package name. For example, if the entry named some.pkg.MyClass.myEntry was extracted it would be available for override within etc/config/some.pkg.xml.

The [:other.jar] in the command refers to other jars which may contain configuration entries to search or extract. In order to see configuration entries declared in classes, the classes must be on the classpath.

The BeNOW tutorials are a work in progress. If you have any comments or suggestions, please email <andy@benow.ca>.