Oracle

PERL

vi

Un*x

JBuilder

Java Programming Language Basics

Properties Basics

Good programmers don't hard code configuration information. Instead, they store this information outside the realm of the source code so that changing system configuration doesn't require recompilation of the system. For the Java platform, those program settings are typically stored in properties files. While you could design and develop your own home grown solution, the java.util.Properties class offers an easy way to load and save these settings with little to no fuss in your code.

A properties file is a series of key-value pairs, stored in a file. The name of the file ends with .properties. For instance, the following two lines might represent a properties file with two properties. The first property of hello has a value of world and the second of goodbye has a value of cruel world.

    hello=world
    goodbye=cruel world

The Properties class basically offers a persistent hash table where all the keys and values are strings. Ignoring the loading part for the moment, accessing key-value pairs works similarly to working with a Hashtable, as Properties is a subclass of it:

    String value = (String)aPropertiesObject.get("hello");
    System.out.println("Value of hello is: " + value);

Notice the casting here to a String of results of get. Since the Properties class is only meant to work with strings, it offers special get and put methods: getProperty and setProperty. With getProperty, you can ask for the value of a specific property with getProperty(key) and also do the same but provide a default value in the event the key is not present with getProperty(key, default). Instead of returning an Object like the get method, getProperty will return a String object. The setProperty method works identically to the put method, but it requires both arguments to be strings: setProperty(keyString, valueString).

Loading of property settings is done through the mysteriously named load method. Just pass in an InputStream and the properties will be read in from the stream. Even though the stream is meant to contain lines of String objects, the load method accepts an InputStream, not a Reader object. The 8859_1 character encoding is hard-coded into the class definition and cannot be changed. You can however specify Unicode values by putting \uXXXX constants into the file.

The basic loading process goes as follows:

InputStream is = ...
Properties props = new Properties();
try {
  props.load(is);
} catch (IOException e) {
  System.err.println("Load failed");
}

The InputStream is typically a FileInputStream. However, if you've jarred up your web application, instead of using a FileInputStream, the InputStream would need to come from the JAR file. If that is the case, then you need to ask the class loader for that stream, as shown here:

InputStream is =
    this.getClass().getClassLoader().getResourceAsStream(
                                         "foo.properties");

This will look for the foo.properties file in the same directory as the class that is executing. The line says, get the Class object for the current class, get its class loader, and then finally get the properties file as a resource and provide it as a stream.

Once the properties file is loaded, you can then use the getProperty and putProperty methods.

To see what properties got loaded, use one of the list methods. This allows you to pass in an OutputStream or Writer object to write the properties to. By passing in System.out, the current settings are written to the console.

If you need to update the properties and resave them, the Properties class offers a store method. When called, you pass in an OutputStream and a String: store(OutputStream stream, String string). The string is stored as a comment in the first line of the file, allowing a file viewer to see what is supposed to be in the file. There is also a save method but it is deprecated because it didn't throw an IOException upon error saving.

The final bit of the Properties class is the propertyNames method which returns an Enumeration. This method will combine all of the current properties, including those loaded via the load method, with a default set of Properties passed into the Properties constructor. Thus, if you'd like to replicate the list behavior yourself, you should use the propertyNames method of Properties to enumerate through the elements, not the elements method inherited from Hashtable. With the elements method, you would only get the specific key-value pairs stored in the properties list, not a combined version with the defaults.