Configuration Properties

Introduction

DeltaXML's configuration properties are used to control the behaviour of DeltaXML products. For example, for those product's that support OASIS catalogs, they provide a facility to specify where these catalogs are located. Each product will specify the properties that can be configured.

A configuration property is constructed from a triple:

• name - A string representing the name of the property.

• value - A string representing the value of the property.

• fixed - An optional boolean specifying whether this property can be overridden. This stops a value being overriden by another configuration file on the search path. See the Layered Configuration Files section below.

These properties can be specified in a DeltaXML configuration file (deltaxmlConfig.xml), which is typically located in the same directory as the product's library (e.g. 'product.jar' file). We refer to this directory as the installation directory for the remainder of this discussion on configuration properties. If the file cannot be found in the installation directory then it is looked for in the user's home directory, and then the current working directory.

Variables - Using properties within properties

It is sometimes useful to be able to specify a property in terms of other properties. For example, it would be possible to specify a property P in terms of a property Q by including the text ${Q} in P's value. Note that Java system properties, such as user.home and user.dir can be referred to in this way (i.e. ${user.home} and ${user.dir} respectively). We also provide an install.dir property, for locating the product's installation directory, when this information is obtainable from the JVM. Some application server's prevent the automatic installation directory detection from working.

Some of DeltaXML's products come with in-built catalogs, such as our DocBook and DITA products. In such cases it is typical to provide some DeltaXML specific properties for enabling both the existing catalogs and some user specified catlogs to be used at the same time. The following DeltaXML configuration properties file extract illustrates how the xml.catalog.files property is defined in terms of an empty external (com.deltaxml.ext.catalog.files) and existing internal (com.deltaxml.rsc.catalog.files) properties.

Example configuration properties

<configProperty
  name="com.deltaxml.ext.catalog.files"
  value=""
  fixed="false"
/>
<configProperty 
  name="xml.catalog.files"
  value="${com.deltaxml.ext.catalog.files};${com.deltaxml.rsc.catalog.files}"
  fixed="false"
/>

The internal catalog files are stored within the jar, and its property is fixed; it is only exposed so that a user can easily arrange for their own catalogs to be searched in addition to it. Note that if the user overrides the com.deltaxml.ext.catalog.files property with a location to another catalog, then this catalog will be searched before that of the internal catalog, as it appears before the internal catalog in the defintion of the xml.catalog.files property.

Layered Configuration Files

A DeltaXML configuration file can specify a 'search path list' to allow additional configuration files to be loaded and further properties to be set (or overridden - if they have not previously been fixed). The first entry in the search path list that exists is loaded; all other entries in the search path are ignored. Further, any attempt to reload a previously visited configuration file will finish the configuration file loading process. Below is an example of a search path list

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deltaxmlConfig SYSTEM "deltaxml-config.dtd">
<deltaxmlConfig>
  <configProperty name="com.deltaxml.cores9api.PipelinedComparatorS9.debugFiles" value="false" />
  <!-- see javadoc for field: com.deltaxml.cores9api.PipelinedComparatorS9#CONFIG_DEBUG_FILES -->
   
  <configSearchPath>
    <search path="${install.dir}${file.separator}deltaxmlConfig.xml" />
    <search path="${user.home}${file.separator}deltaxmlConfig.xml" />
    <search path="${user.dir}${file.separator}deltaxmlConfig.xml" />
  </configSearchPath>
</deltaxmlConfig>

When running the product gets values for a property in the following order of precedence:

1. The first configuration file on the search path which has a value for the property AND which has marked that property as fixed.

2. Any internal overrides which are set up. This must be the case to ensure consistency.

3. Any System property of that name. ( configuration property files do not override properties that do not begin with com.deltaxml)

4. The value of the property as it appears in the last configuration file on the search path.