Article: Jakarta Configuration »

FERDY CHRISTANT - NOV 11, 2005 (11:25:38 AM)

Introduction

A proper J2EE application does not hard-code configuration values. Instead, should reference configuration values from your code, and store them elsewhere.

A classic way to implement this is to use properties files. Properties files are configuration files that exist in your application. These files typically hold key/value pairs that you can look up from your code. Apache's Jakarta project has a powerful component to simplify working with configuration files: the Commons Configuration package. This package makes it extremely easy to read/write configuration values from various configuraton sources, such as .properties files, XML files, JNDI, JDBC, and more.

This article will demonstrate how to use this package to read various configuration values from a .properties and a .xml file. Example code is included. This article assumes that you have a basic understanding of your favorite Java IDE.

Setting up the configuration files

For our case, we will create two configuration files; a .properties file and a .xml file. Both contain the same configuration values that we like to retrieve:

A dynamic welcome message
An integer value
A multi-value/list of colors
A dynamic, multi-line exit message

Let's start by creating the .properties file. You can decide for yourself where to put it, but I recommend you to place it in /WEB-INF/classes, as this makes it easy to retrieve later. Furthermore, this makes sure that it will be part of your WAR once you export your project. Our conf.properties file will look like this:

# name property name = ferdy # welcome message includes reference to other property welcome message = hello ${name} # exit message spans multiple lines exit message = bye ${name} \ see you later! # numeric property log treshold = 200 # multi-value property colors = #f00, #ff0, #fff

Notable about the conf.properties file:

The format of an entry is key = value
You can refer to other properties in the file
Multi-line values are separated by a "\" character
Multiple values are separated by a "," character

The conf.xml file is more verbose, but allows for more structure: <?xml version="1.0" encoding="UTF-8" ?> <properties> <name>Ferdy</name> <messages> <welcomemessage>hello ${name}</welcomemessage> <exitmessage>bye ${name} see you later!</exitmessage> </messages> <logtreshold>200</logtreshold> <colors> <color>#f00</color> <color>#ff0</color> <color>#fff</color> </colors> </properties>

Notable about the conf.xml file:

It allows a clean structure of configuration values
It does not rely on a DTD, you're free to design your own configuration structure
The root element, <properties> can be anything you like, since it will be ignored when you retrieve a value from this file.

Retrieving the values

We will now create two servlets, one to read the values from the properties file, the other to read the values from the XML file. Before we do so, we first need to import the required Jakarta packages into our project. The following are required:

Both servlets will follow the same approach, the first one instantiates a PropertiesConfiguration class, the second one a XMLConfiguration class. After that they will read the values defined in the configuration file and output them to the user. You can view the full source code in a new window by opening the links below:

Notice how both servlets are almost identical. An import difference is that the XMLConfiguration object allows for the retrieval of more sophisticated hierarchical values, such as "messages.welcomemessage", while the PropertiesConfiguration object uses a flat approach.

Running the servlets

To run the servlets, you can import the full source package of the sample application into your IDE and run it. Or, you can deploy the WAR to your J2EE server and run it from there. For Tomcat deployment, my previous "Tomcat deployer in action" article may be useful to you.

To run the servlets after deployment, browse to:

http://yourhost:yourport/ConfigTest/Properties
http://yourhost:yourport/ConfigTest/XML

Both servlets should output exactly the same:

Conclusion

The Jakarta Commons Configuration package allows for a transparent way of managing configuration values from various sources, and is easy to use. This article has only demonstrated a small fraction of the possibilities of the package, so for the full package description go here.
Reuse...it's a great thing.