Different XML structures and different parsers

jConfig suports a simple XML structure which consists of a two level hierarchy. There has been a few requests that this structure is not flexible enough. The latest version now supports different XML structure through the pluggable parsers. Beside the parser there is now the possibility to include different configurations. Currently jConfig supports three different kind of parsers. Every parser can read a different kind of XML structure.

DefaultConfigParser

This is the default parser. It supports a two level structure with categories and properties inside the categories.

Example:

<properties>
  <variables>
    <variable name="base_dir" value="${system:java.io.tmpdir}"/>
  </variables>
  <category name="general">
    <property name="hello" value="world"/>
  </category>
  <category name="server">
    <property name="port" value="8080"/>
    <property name="docroot" value="${base_dir}/docs"/>
  </category>
</properties>

CDataConfigParser

The default parser has a few disadvantages. First of all it does not support escape characters as property values. Also the definition of a property might be a little to complicated.

This parser is based on the structure of the default parser but it takes the tag name as property name and the cdata content as value.

Example:

<properties>
  <variables>
    <variable name="base_dir" value="${system:java.io.tmpdir}"/>
  </variables>
  <category name="general">
    <hello>world</hello>
    <text>
    Hello,
    this is me!
    </text>
    <directory>${base_dir}/docs/mydir</directory>
  </category>
  <category name="server">
    <port>8080</port>
    <docroot>${base_dir}/docs</docroot>
  </category>
</properties>

NestedConfigParser

The NestedConfigParser lets you defined categories inside categories.

This is an example that sums it up:

<properties>
  <variables>
    <variable name="base_dir" value="${system:java.io.tmpdir}"/>
  </variables>
  <category name="general">
    <server_port>8080</server_port>
    <server_root>${base_dir}/docs</server_root>
  </category>
  <category name="settings">
    <category name="client">
      <screen_size>1024,768</screen_size>
    </category>
    <category name="server">
      <home_dir>${base_dir}/app</home_dir>
    </category>
  </category>
</properties>

Defining which parser to use

There are a few ways how you can tell jConfig which parser should be used. The best way is to include a file called jconfig.properties in the classpath and define the parser inside. You can define the default parser that will be used by all configurations are a specific parser for a specific configuration. Inside the file put a line:

# this defines the default parser and this is the good old parser
parser=org.jconfig.parser.DefaultConfigParser

In order to define a parser for a specific configuration put the name after the parser:

# this defines a parser for the configuration called "myConfig"
parser.myConfig=org.jconfig.parser.NestedConfigParser

If you do not want to include a jconfig.properties file then you can set a system property called "jconfig.properties" and define the full qualified class name of the parser:

System.setProperty("jconfig.parser","org.jconfig.parser.CDataConfigParser");

This way you cannot specifiy different parsers for different configurations.

Writing your own parser

Since jConfig supports pluggable parsers you can write your own. For example if you want to read your configuration from a database. Your parser has to implement only one method:

public Configuration parse(Document doc,String configName);

The parser is called from the handler and recieves the document and the configName. The method must return the configuration. If you want to you can also implement your own configuration.