![]() |
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> ${var-name} for example ${my.path} Here is a category that uses variables:
<category name="settings"> 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:
|
Examples |
Included in the package are three examples.
|