Using Configutron

STEP 1

The first step is to define the application configuration in a configuration schema.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config-schema SYSTEM "configutron.dtd">

<config-schema name="S3C">
     <element name="cache">
          <attribute name="name"/>
          <attribute name="slots" type="int"/>
          <attribute name="timeout" type="int"/>

          <element name="slot" multiple="true">
               <attribute name="name"/>
               <attribute name="timeout" type="int">
                    <comment>Expiry time of Slot</comment>
               </attribute>
          </element>
     </element>
</config-schema>

The example shows a sample config-schema in which element cache is the root element that has sub-element slot. The 'multiple' attribute of element 'slot' shows that the parent element cache can hold multiple sub-elements of type slot. [Note: You must use 'configutron.dtd' file when writing the schema. The DTD file is located in CONFIGUTRON_HOME/resources folder.]

The sample XML configuration file against this schema is as follows:

<cache name="testCache" slots="5" timeout="60000">
     <slot name="1" timeout="10000"/>
     <slot name="2" timeout="20000"/>
     <slot name="3" timeout="30000"/>
</cache>

STEP 2:

In this step a user-config-api is generated using a <configutron> ANT task. Configutron dynamically creates an object model against the config-schema which is populated with all the configuration data and provided to the application. The attributes of each element become the properties of their corresponding objects that can be accessed via getters and setters. The package name for all the generated classes is 'xeus.config.user.<schema_name>'; the schema_name in this example is s3c (in lowercase), therefore the package name used in this example becomes 'xeus.config.user.s3c'.

The object model against this sample config-schema is:

This model is generated, compiled and a JAR user-config.jar file is created. To do this:

  • Download and install Configutron and ANT*

  • Set ANT_HOME environment variable pointing to the install directory of ANT

  • Go to home directory of Configutron; open a command prompt and type in the following command with required arguments


> configutron [CONFIG_DIR] [CONFIG_SCHEMA] [OUTPUT_DIR]

For example

> configutron c:\s3c\ s3c-schema.xml c:\output
 

[CONFIG_DIR]        The path of directory containing the config schema
[CONFIG_SCHEMA]  The name of the config schema file
[OUTPUT_DIR]        The path of output directory

This command will generate all the required java source in 'src' folder, compiled classes in 'classes' directory and user-config.jar file at [OUTPUT_DIR].

STEP 3:

Now all the application developer has to do is to put the user-config.jar and all the CONFIGUTRON_HOME/lib jar files in the application's CLASSPATH and access all the configuration using the following line of code.

import xeus.config.*;
import xeus.config.user.s3c.*;
 .
 .
 .

Cache c= (Cache)Configutron.load("c:\\s3c\\","s3c-schema.xml","s3c.xml");
 

The load method returns the object representation of the root element. The first argument of load method is the directory path where the configuration file and schema is located. The second argument is the schema file and the third argument is the configuration file itself.

The sub elements slot can be accessed as a list:


Cache c= (Cache)Configutron.load("c:\\s3c\\","s3c-schema.xml","s3c.xml");

List slots=c.getSlotList();

for(int i=0;i<slots.size();i++)
     System.out.println("Slot Name: "+((Slot)slots.get(i)).getName());
 

It is also possible to hash multiple sub elements so that they can be accessed directly without having to iterate the list. To do this the config-schema has to be modified in the following way:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config-schema SYSTEM "configutron.dtd">

<config-schema name="S3C">
     <element name="cache">
          <attribute name="name"/>
          <attribute name="slots" type="int"/>
          <attribute name="timeout" type="int"/>

          <element name="slot" multiple="true" hash="true" key="name">
               <attribute name="name"/>
               <attribute name="timeout" type="int">
                    <comment>Expiry time of Slot</comment>
               </attribute>
          </element>
     </element>
</config-schema>

When the value of hash attribute is set to true then the element can be accessed directly with it's key, which in this case will be the value of name attribute [See the configuration file]. The key and multiple attributes become mandatory when hash is enabled. The type of key is the type of the attribute being used as key. Now Slot element can be accessed directly by the value of it's name attribute:


Cache c= (Cache)Configutron.load("c:\\s3c\\","s3c-schema.xml","s3c.xml");

Slot s1=c.getSlot("1");
 

 

* ANT is available for download at Apache's website