Core class

This page gives documentation on core class XmlConfig that manages configuration parameters.
For more details you can read the javadoc documentation.

The net.sourceforge.jezxmlconfig.XmlConfig class implements a object that contains configuration parameters.

Configuration parameters are elements of hierarchical sections.
It means that a section can contain other sections and parameters.
These is no limit on sub-section depth level.

You can find below an example of a configuration structure:

A parameter is identified by its name and have a value.
A parameter value can contain a reference to a defined constant or a system property.

For more information on JEZXmlConfig format you can read the DTD.

Concrete configuration example:

We want to define configuration parameters for an application that read input files and produces a result in an output directory.

Two input data sources are defined:

Billing files will be accessed in a user home sub-directory that corresponds to execution environment, plus the billing sub-directory.
File name format is Bill_*.dat.
Example: "/home/frederic/production/billing"
The user home directory is "/home/frederic", and we are executing the program in the production environment.

Other files are accessed from the other sub-directory at same level of billing one.
File name format is Oth_*.xml.

Results are stored in /DATA directory.

Lastly, the application will be automatically launched every 60 minutes and will produce files which will contain a maximum of 5000 records.

See below a example of how to store theses application parameters:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <configuration>
        <constants>
            <constant name="env" value="production"/>
        </constants>
        <parameters>
            <section name="Input">
                <section name="Billing">
                    <param name="subDir" value="billing"/>
                    <param name="prefix" value="Bill_"/>
                    <param name="suffix" value=".dat"/>
                </section>
                <section name="Other">
                    <param name="subDir" value="other"/>
                    <param name="prefix" value="Oth_"/>
                    <param name="suffix" value=".xml"/>
                </section>
                <param name="rootPath" value="${user.home}/${env}"/>
            </section>
            <section name="Output">
                <param name="resultDir" value="/DATA"/>
            </section>
            <section name="Process">
                <param name="maxRecordPerFile" value="5000"/>
                <param name="frequency" value="60"/>
            </section>
        </parameters>
    </configuration>

Of cource, you can write youself theses parameters in an XML file.
But if you are not very familiar with XML you can use the provided editor.

How to load configuration

Your application will certainly load configuration parameters at initial start.
Your method code could be similar than following lines:

  // Get configuration instance: Build an empty configuration at very first access
  private XmlConfig config = XmlConfig.getInstance(); // Instance variable

  ...

  /**
   * Load application configuration in memory.
   * @param configFile Configuration file.
   * @exception MyApplicationException If configuration cannot be loaded (details in exception message).
   */
  private void loadConfig(File configFile) {
      try {
          this.config.load(configFile);
      }
      catch(XmlConfigException xce) {
          throw MyApplicationException("Cannot load configuration: " + xce.getMessage());
      }
  }

Note 1: You can import a Java properties file with the loadProperties() method. As parameters must be in a section, a simple parameter name (without dot) is considered as a constant.
Example:

word1.word2.word3=value1: will be the parameter word3 in sub-section word2 of root section word1.
word0=value2: will be the constant word0.

Note 2: It is also possible to load a configuration with JNDI (Java Naming Directory Interface).

How to access parameters

When you want to access parameter values in your application, you just have to write something like that:

      // Get process frequency
      int freq = this.config.getIntParameter("Process", "frequency", DEFAULT_FREQUENCY);

      ...

      // Get all billing files
      File billingDir;
      try {
          // Config object verify if rootPath directory exists
          File rootPath = (File)this.config.getObject(TYPE_DIR, "Input", "rootPath");
          billingDir = new File(rootPath, this.config.getStringParameter("Input.billing", "subDir"));
      }
      catch(XmlConfigException xce) {
          // Billing directory parameter is missed in configuration, or directory does not exist !
          throw new MyApplicationException("Cannot acces billing directory parameter: " + xce.getMessage());
      }

      ...

      File[] files = billingDir.listFiles();

      ...

How to update configuration at runtime

Suppose you want your application to provide a user-interface that permit to add an input data source.

In this way, an administrator wants to add the data source corresponding to a new "accounting" sub-directory.

Your code can contain a method that updates your configuration, and then save it:

  private void addSourceDirectory(String sourceName, String directory, String prefix, String suffix) throws XmlConfigException {
      // Get configuration instance
      XmlConfig myConfig = XmlConfig.getInstance();

      // Add new section for new data source
      String fullSectionName = "Input." + sourceName;
      config.addSection(fullSectionName);

      // Add new section parameters
      config.addParameter(fullSectionName, "subDir", directory);
      config.addParameter(fullSectionName, "prefix", prefix);
      config.addParameter(fullSectionName, "suffix", suffix);

      // Save configuration
      config.save();
  }

After your code execution, you will obtain the following configuration file:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <configuration>
        <constants>
            <constant name="env" value="production"/>
        </constants>
        <parameters>
            <section name="Input">
                <section name="Billing">
                    <param name="subDir" value="billing"/>
                    <param name="prefix" value="Bill_"/>
                    <param name="suffix" value=".dat"/>
                </section>
                <section name="Other">
                    <param name="subDir" value="other"/>
                    <param name="prefix" value="Oth_"/>
                    <param name="suffix" value=".xml"/>
                </section>
                <section name="Accounting">
                    <param name="subDir" value="acct"/>
                    <param name="prefix" value="Acct_"/>
                    <param name="suffix" value=".bin"/>
                </section>
                <param name="rootPath" value="${user.home}/${env}"/>
            </section>
            <section name="Output">
                <param name="resultDir" value="/DATA"/>
            </section>
            <section name="Process">
                <param name="maxRecordPerFile" value="5000"/>
                <param name="frequency" value="60"/>
            </section>
        </parameters>
    </configuration>

Finally, if you want to avoid coding for configuration updates, why not include the provided editor as a component of your application ?

Main menu

Core class