The Jakarta Commons project recently released version 1.6 of their open-source Java configuration library. Code to handle project configuration isn't, admittedly, the sexiest of technologies — but the Jakarta project does it exactly right. Its "composite configuration" features are particularly useful to manage configuration settings for different runtime environments.

As an example of how composite configuration works, let's say we're working an eCommerce project creatively named "estore." We need a library that sends out email notifications to all existing customers of new products, say. In production, these emails should obviously be sent to the customers. But in a QA environment, they most certainly should not be sent to the customers — imagine their confusion if they received notification of a new product named "Test Product Two" and costing $9999.99! In development, only emails to the currently working dev should be sent. And so on.

At Ideograph we've addressed this category of problem by checking each outgoing email against a regular expression filter right before sending. If the outgoing address doesn't pass through the filter, then it just isn't sent. Preventing emails from "escaping" keep us safe from potentially embarrassing error. The code looks something like this:

public class OutgoingEmail extends Email {
 
  public OutgoingEmail() {
    filter = Pattern.compile(config.getEmailFilter());
  }
 
  // ...blah blah blah...
 
  // Add the specified address to the list of recipients
  public void addTo(String address) {
    Matcher m = filter.matcher(address);
    if(m.matches()) {
      super.addTo(address);
    } else {
      log.warn("Not sending to " + address + " because does not pass filter.");
  } 
 
  // ...blah blah blah...
 
  private static Config config = new Config();
  private Pattern filter;
}

This code is pretty easy to understand: if the recipient address passes through our filter, then the email is sent; if it doesn't, then we drop it on the floor and log a warning. The right filter to use is selected at runtime by checking with our Config object, which is just a thin wrapper around the commons-configuration library. Here are the two relevant methods:

public class Config {
 
  // Load up the configuration from estore.xml 
  public Config() {
    ConfigurationFactory factory = new ConfigurationFactory();
    URL configURL = Configuration.class.getResource("/estore-conf.xml");
    factory.setConfigurationURL(configURL);
    config = factory.getConfiguration();
  }
 
  // ...blah blah blah...
 
  // Return the email filter
  public String getEmailFilter() {
    return config.getString("email.filter", "");
  }
 
  // ...blah blah blah...
 
  private org.apache.commons.configuration.Configuration config;
}

In the constructor of this object, we read up all the settings from the configuration file estore-main.xml, which is found in the project's classpath. (commons-configuration can read from a variety of different file formats, but we've chosen to use XML here.) The getEmailFilter method reads from the email/filter element, defaulting to the empty string if there's no other setting. (Note that we've chosen a very safe default here — unless there's a specific filter pattern set, no email address will match the default and thus no emails will get out.)

We keep our default configuration settings in the file estore-default.xml, which looks in part like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<estore>
  <!-- ...blah blah blah... -->
 
  <mail>
 
    <!-- SMTP settings -->
    <host>smtp.ideograph.com</host>
    <username>jon</username>
    <password>v3rys3cret!</password>
 
    <!-- Email filter: only send to these addresses -->
    <filter>.*ideograph.com</filter>
 
  </mail>
 
  <!-- ...blah blah blah... -->
</estore>

Nothing too fancy so far: by default, the filter effectively permits emails to be sent to ideograph.com addresses only.

But note that this file, estore-defaults.xml is not the one read by our Config object. The Config object reads estore-conf.xml, which looks like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<configuration>
	<xml fileName="estore-node.xml" optional="true"/>
	<xml fileName="estore-default.xml"/>
</configuration>

This is where the composite configuration comes into play. This block tells commons-configuration to read the settings from two files, in the specified order of priority. If there is a estore-node.xml file, and if that file contains a value for the setting we're reading, then that value is returned. Otherwise, drop back and pull the value from estore-default.xml.

estore-node.xml contains the overrides for a particular node type — in this example, either production, QA or dev. The settings specified in that file are "composited" on top of the values that are in default.

We keep QA settings in a file named estore-qa.xml. These settings allow emails to be sent to the estore QA team but no one else:

<?xml version="1.0" encoding="ISO-8859-1"?>
<estore>
  <mail>
    <filter>qa@estore.com</filter>
  </mail>
</estore>

Jon's dev settings are in a file named estore-local.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<estore>
  <mail>
    <filter>jon@ideograph.com</filter>
  </mail>
</estore>

And finally, for production, the settings in estore-production.xml allow emails to be sent to the actual customers:

<?xml version="1.0" encoding="ISO-8859-1"?>
<estore>
  <mail>
    <filter>.*</filter>
  </mail>
</estore>

We keep three files in the source code control system: the full set of system configuration settings, in estore-default.xml; settings for the QA node in estore-qa.xml; and of course the production settings in estore-production.xml. Each dev has his or her own copy of estore-local.xml. Our Ant script knows which file to copy over into estore-node.xml before package and release.

True, configuration is not particularly sexy. But it's very important to get right. The Jakarta project's commons-configuration makes it easy for us to get right.