Configuration Properties

1. 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

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.

2. 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.

<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 there 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.

3. Layered Configuration Files

A DeltaXML configuration file can specify a 'search path list' to look for additional properties to be set (or overridden - if they have not previously been fixed). Here, the first search path in the 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.