jConfig documentation
 In general
The goal of this project is to provide a simple to use ConfigurationManager that works with a XML structure. This version can read the configuration either from a file or get it from an URL. The second option gives you the ability to store your configuration on a different server (maybe one machine that has all the configurations for your system world wide). It can also be used as a fallback scenario so in a case that a configuration file is missing you can download it and then save it to a file. jConfig also supports reading Java properties files so that you can convert your existing properties files into XML files. In general jConfig supports a hierarchical structure to store the properties. All properties can be grouped into categories. There is one default category called “general”. Here is a short example how such a XML file might look like:

<?xml version="1.0" ?>
<properties>
  <category name="news">
    <property name="count" value="10" />
    <property name="mode" value="full" />
  </category>
  <category name="JDBC">
    <property name="URL" value="jdbc:mysql://localhost/iportal" />
    <property name="USER" value="dice" />
    <property name="PWD" value="dice" />
    <property name="DRIVER" value="org.gjt.mm.mysql.Driver" />
  </category>
  <category name="general">
 <property name="debug_file" value="/tmp/mystuff.log" />
    <property name="servlet_context" value="/MyStuff" />
    <property name="image_path" value="/MyStuff/img" />
    <property name="site_map_root" value="application" />
    <property name="upload_dir" value="/tmp/iPortal_upload" />
  </category>
</properties>
 How to use it
The use of jConfig is rather simple. Let us look at an simple example. First step is that we instantiate the ConfigurationManager:

private ConfigurationManager cfgmgr = ConfigurationManager.getInstance();

The class uses the Singleton pattern so there is always only one instance. If there is no instance so far then jConfig will create a new one with an empty configuration inside. Only the category “general” is created.

If you have the config.xml in your path, you can start using the ConfigurationManager immediately. There is no need to call the ConfigurationManager.load( File ) method any longer. You can still use the ConfigurationManager.load( File) method as before. That is described here:

File file = new File("test.xml");
// load the file
try
{
  cfgmgr.load(file);
}
catch (Exception e)
{
  // ups, something went wrong and we have to stop here
  e.printStackTrace();
  System.exit(1);
}

As mentioned above, this can be done automatically for you when you put the config.xml inside of your classpath. However, if you decide to use the ConfigurationManager.load( File ) method, you only have to do it once. Since there is always only one instance of the ConfigurationManager the configuration is kept in memory. Now you can simply get the properties from your configuration. For example like this:

//
// first we get an existing property from the category "general"
//
String debug_file = cfgmgr.getProperty("debug_file");
System.out.println("The debug_file is:" + debug_file);
//
// now we try to get a non-existing property from the category "general"
//
String neProp = cfgmgr.getProperty("hello","my default");
System.out.println("The value is:" + neProp );
//
// last step is we get a property from the category "JDBC"
//
String driver = cfgmgr.getProperty("DRIVER","","JDBC");
System.out.println("The driver is:" + driver);

 Multiple Instances
Version1.3 allows for multiple instances now. Up until now, the ConfigurationManager has delivered a single instance (Singleton) of itself. The requests came in for multiple configurations. Multiple configurations lead to multiple instances. New methods were added and the examples follows:

ConfigurationManager cfgmgr1, cfgmgr2; cfgmgr1 = ConfigurationManager.getInstance();
cfgmgr2 = ConfigurationManager.getInstance( "default" );
// cfgmgr and cfgmgr2 are the same instance. The getInstance() method
// calls the getInstance( String ) method with "default" as parameter.

If you want a new instance, you use the getInstance( String ) method with the name of your new instance.

ConfigurationManager cfgmgr =
  ConfigurationManager.getInstance( "myApp" );
// if this is the first time requesting this instance, a new instance
// will be instanciated. If not, the instance is returned to the caller.
// After instanciation, you can load whatever file. The default
// config.xml is used for the new instance.

 How to use variables
The latest version of jConfig supports variables. You can define them in the variables block inside your configuration file. Here is an example for such a variables-block:

<variables>
   <variable name="my.path" value="/usr/development/mystuff/etc" />
   <variable name="my.offset" value="100" />
   <variable name="app.name" value="MyStuff" />
</variables>

You can now use these variables inside your property definitions. The syntax for using a variable is:
${var-name} for example ${my.path}
Here is a category that uses variables:

<category name="settings">
   <property name="path" value="${my.path}/test.file" />
   <property name="maxNumber" value="${my.offset}00" />
   <property name="application" value="${app.name}" />
</category>

If you use the following call:
String myPath = cfgmgr.getProperty("path",null,"settings");
You will get the following result:
/usr/development/mystuff/etc/test.file
If you try to use a variable that is not defined then the text will not be replaced.
 Validation
Version1.1 supports now validation of the XML either from a file or an URL. But the validation is switched off by default and you have to switch it on. In order to validate your configuration you have to do the following (example for a file):

private ConfigurationManager cfgmgr = ConfigurationManager.getInstance();

File file = new File("myconfig.xml");
try
{
  // turn on the validation
  cfgmgr.setValidation(true);
  cfgmgr.load(file);
}
catch (Exception e)
{
  // not valid XML and now do something useful here
}
 Auto-Reload
Version1.3 provides for an automated reload of the configuration information when the configuration file changes. This applies currently to local files, but should be compatible with URLs in the future. The mechanism behind the reloading is a FileWatcher. The FileWatcher's job is to watch a file, and notify any listeners that the configuration has changed. The ConfigurationManager, for example, will reload the properties from the changed configuration. Incidentally, you can add your own FileListeners and receive the events for your use.

ConfigurationManager cfgmgr = ConfigurationManager.getInstance();
cfgmgr.addFileListener( new FileListener() {
  public void fileChanged( FileListenerEvent evt ) {
    //do what you want with the event
  }
});
 How to install it / how to use it
The installation is simple. All you have to do is make sure that jconfig.jar is in your classpath. jConfig depends on JAXP1.1. Therefore make sure that you also have the corresponding jar-files in your classpath as well. If you have downloaded the source distribution then these files are in the lib-subdirectory.
 How to build jConfig
In order to build the jConfig jar file you need Ant1.4. This is included in the source distribution in the lib subdirectory. There are two files that you can use. The first is a linux/Unix shell script create.sh and the second one is for windows create.bat. The syntax is:
./create.sh {target}
where {target} can be one of the following:
  • compile
    This will compile all java classes
  • javadoc
    Generates the javadoc
  • clean
    Cleans up everything
  • jar
    Will generate the jconfig.jar file
  • all
    This runs all targets in the following order: clean, compile, javadoc and jar
 Examples
Included in the package are three examples.
  • SimpleExample
    Shows the basic usage of jConfig.
  • ConvertExample
    This example demonstrates how to read a Java properties file and then save it as a XML file.
  • CreateExample
    This one shows how to build a configuration from Java and then save it to a file.