Package de.ufinke.cubaja.config

Easy access to XML configuration data.

Introduction

The idea is to unburden the application from interpreting typeless configuration data. Instead, the application relies on typesafe data which can be retrieved from objects giving a really object oriented view on the configuration. This framework makes configuration issues as easy as coding simple data access objects.

The central class of this package is Configurator.

Configuration objects

An arbitrary configuration object represents an XML element. Like XML elements, the element node objects may be nested. For every type of XML element, there is a corresponding class. These classes have 'setter' and 'adder' methods; their names begin with set or add, followed by the name of an XML attribute or the tag name of an XML element. The difference between setter and adder methods is that setters may be invoked only once (for an attribute value or a unique subelement), whereas adders may be invoked any number of times. Within an adder method, the passed parameter is typically added to a collection.

Setter and adder methods must have a void return type and exactly one parameter. Built-in supported parameter types are

  • all primitive types and their corresponding object classes
  • String
  • java.util.Date
  • java.math.BigInteger
  • java.math.BigDecimal
  • Enum types
  • Class (the parameter is a class name)
  • any interfaces (the parameter is the name of an implementing class)

Other types with a public parameterless constructor are considered to be element nodes. Those types do not need to extend or implement supertypes or interfaces. But if such a type implements StartElementHandler, EndElementHandler or ParameterFactoryProvider, the implemented methods will be called during the configuration process to gain more control for special purposes.

An attribute value will be passed to the actual element node object as the appropriate parameter type when processing the starting XML element tag. Element content (subelements) is also passed with the appropriate type to the adder / setter method when processing the XML element's end tag. In case the parameter type is an array of the types listed above, the attribute value or element content may be a comma separated list which is split into separate trimmed strings. The strings are processed in the same way as single values and collected in an array.

The application passes its root configuration object to the configure method of a Configurator instance. Before processing, the Configurator may be customized, e.g. by setting the name of the XML source, applying properties, setting patterns, or providing ParameterFactoryFinders for your own parameter types.

Properties

The XML attribute values or element content may contain properties of the form ${propertyName}. Those properties are replaced by their actual values when the parameter types of the setter / adder methods are processed. There are several possible sources for property values, all provided by implementations of PropertyProvider. Basic property providers are defined by enum PropertyProviderType. Additionally, you can write your own providers or pass an instance of java.util.Properties.

The properties' search order is defined by the order of addPropertyProvider method calls. Basic property providers are automatically appended to the search order if they were not defined explicitly and there is no NULL property provider. The default order is as follows:

  1. SYSTEM
    System properties.
  2. CONFIG
    Properties in an optional resource config.properties which is loaded by the resource loader.
  3. XML
    Properties defined in the XML document with the special element
    <configProperty name="name" value="value/">.
  4. ENVIRONMENT
    Environment variables.

The configure method may be called more than once on an Configurator instance. This is useful when a big configuration should be split into several independent files (e.g. technical and end-user responsibility) and the same basic settings should be used. The provider for property type XML is stored in a stack. The properties are searched from the top of the stack downward. On every call to configure, the actual XML provider is initialized and pushed onto the stack. When configure finishes, it is popped off the stack. A call to pushXMLProperties pushes the actual provider onto the stack before the next call to configure parses the next XML document. There is a corresponding method popXMLProperties to pop a provider off the stack.

Implementations of NamedPropertyProvider are not part of the search sequence. The provider is called directly when a configProperty element with an attribute 'provider' is encountered. Such configProperty elements may have sub-elements with the tag name 'parm', containing attributes 'name' and 'value'.

Named property providers are defined by the application, or within the XML. For the latter, code an element 'configPropertyProvider' with the attributes 'name' (the name of the provider) and 'class' (the implementing class name). The class has to be in the classpath.

Includes

The special element configInclude with an attribute named include includes the named resource (or file) while parsing. The root element of the included resource is discarded but its children are processed as if they had been defined in the root document.

Settings

There is another special element named configSettings to set the parser's behaviour. Possible attributes are

  1. datePattern
    The date pattern for parsing date values. For a description how to code the pattern see SimpleDateFormat. Default is yyyy-MM-dd.
  2. trueValues
    A comma separated list of constants representing the boolean value true. Default is true,yes,on.
  3. falseValues
    A comma separated list of constants representing the boolean value false. Default is false,no,off.
  4. decimalPoint
    The decimal point character, which may be a point or a comma. By default, both characters are processed as decimal point.
  5. processEscape
    Enables or disables processing of escape characters (introduced by backslash, i.e. \n for newline). The values true, yes or on enable processing, other values disable processing. By default, processing is enabled.
  6. processProperties
    Enables or disables processing of properties (that is, replacement of ${...} sequences). The values true, yes or on enable processing, other values disable processing. By default, processing is enabled.

Copyright (c) 2006 - 2010, Uwe Finke. All rights reserved.
Subject to BSD License. See license.txt distributed with this library.