Section 4.4. The Properties Class

4.4. The Properties Class

The Javadoc page for the Properties class describes it as "a persistent set of properties . . . saved to . . . or loaded from . . . a stream." In other words, it is a hashtable (a set of name/value pairs) that can be read from or written to a streamwhich typically means a file. (Other things can be streams, but for now, think "file".)

The great thing about name/value pairs is how readable and usable they are. When they are written to a file, there's no fancy formatting, no fixed width fields, no unreadable encryptions and special characters; it's just name=value. You could say that the "=" and the newline are the special characters that provide all the formatting you need. It means that you can type up a properties file with the simplest of editors, or even generate one quickly as we saw in the previous example (here we use a simple filename):

 $ env > propertyfile 

Properties are also easy to use. Since they're based on hashtables, there is no searching code to write. You call a method giving it the name, it returns the value.

If we pass in the name of the file via the -D parameter, then we can get that filename in Java with:

 System.getProperty("ENVFILE"); 

where ENVFILE is a name that we made up and used on the command line:

 $ java -DENVFILE=propertyfile MyClass 

We could also have used:

 $ java MyClass propertyfile 

so that args[0] ^[3] in the Java code to get the name of the file (see Section 4.2.1), but since we want to learn about properties, we'll use the property methods here.

^[3] In C language, the arg[0] is the command being invoked; not so in Java. In Java, the first element of the array is the first argument of the command line (propertyfile in our example).

Now let's open that property file (Example 4.3).

Example 4.3. Demonstrating the Properties class

 import java.io.*; import java.util.*; public class EnvFileIn {   public static void   main(String [] args)     throws IOException   {     String envfile = System.getProperty("ENVFILE", ".envfile");     BufferedInputStream bis = new BufferedInputStream(                                 new FileInputStream(envfile));     Properties prop = new Properties();     prop.load(bis);     bis.close();     prop.list(System.out); // dumps the whole list to System.out   } // main } // class EnvFileIn 

Notice the way that we got the value for the environment file's name. This form of the getProperty() call provides not only the name we are looking up (ENVFILE) but also lets us specify a default value in case the name is not found in the properties list. Here our default value is .envfile.

Just as it was a simple matter of using the load() method to read up an entire file of properties, so you can write out the entire list of properties to the screen with the list() method. The argument to list() is either a PrintStream or a PrintWriter. System.out is a PrintStream, so that will work.

The format of the properties file is name=value. But it is also possible to put comments in a properties file. Any line beginning with a "#" is ignored. Try it.

It's also easy to (re)write a file of properties with the store() method. The parameters are an OutputStream and a String; the latter will serve as a label for the parameters, written to an opening comment in the properties file.

If your program needs to examine the list of property names, you can get an Enumerator of the entire list via the propertyNames() method. Modify Example 4.3 to replace the list() call with a do-it-yourself version that uses the Enumerator returned from propertyNames() to list all the names and values. Hint: Use getProperty() on each name retrieved via the enumeration.

The Java Properties class extends the java.util.Hashtable class. This means, in part, that all the other Hashtable methods are available to a Properties class. Methods such as containsKey() or containsValue() can be helpful, as can isEmpty(). One caution, though. You should use setProperty() if you want to add values to Properties, rather than the Hashtable's put() method. They do largely the same thing, but setProperty() enforces that its parameters are Strings. This is important if you want to write out the properties to a file, as it's meant for Strings only.