Setting Up and Using Properties

In Java, program attributes are represented by the Properties class in the java.util package. A Properties object contains a set of key/value pairs. The key/value pairs are like dictionary entries: the key is the word, and the value is the definition.
Both the key and the value are Strings. For example, os.name is the key for one of Java's default system properties--its value contains the name of the current operating system. You use a key to look up a property in the properties list and get its value. On my system, when I look up the os.name property, its value is Solaris. Yours will likely be different.
Properties specific to your Java program are maintained by your program. System properties are maintained by the java.lang.System class. For information about system properties, refer to System Properties in the Using System Resources lesson.
You can use the Properties class from java.util to manage attributes specific to your Java programs. You can load key/value pairs into a Properties object from a stream, save the properties to a stream, and get information about the properties represented by the Properties object.
Setting up Your Properties Object
Often when a program starts up, it will use code similar to the following to set up the properties object:
. . .
    // set up default properties
Properties defaultProps = new Properties();
FileInputStream defaultStream = new FileInputStream("defaultProperties");
defaultProps.load(defaultStream);
defaultsStream.close();

    // set up real properties
Properties applicationProps = new Properties(defaultProps);
FileInputStream appStream = new FileInputStream("appProperties");
applicationProps.load(appStream);
appStream.close();
. . .
First the application sets up a default Properties object. This object contains the set of properties to use if values are not explicitly set elsewhere. This code snippet uses the load() method to read the default values from a file on disk named defaultProperties. Applications usually save and restore properties to files on the disk.
Next, the application uses a different constructor to create a second Properties object, applicationProps. This object uses defaultProps to provide its default values.
Then the code snippet loads a set of properties into applicationProps from a file named appProperties. The properties loaded into appProperties can be set on a per user basis, a per site basis, or whatever is appropriate for the current program. What's important is that the program saves the Properties to a "well-known" location so that the next invocation of the program can retrieve them. For example, the HotJava browser saves properties on a per user basis and saves the properties to a file in the user's home directory.
You use the save() method to write properties to a stream:
FileOutputStream defaultsOut = new FileOutputStream("defaultProperties");
applicationProps.save(defaultsOut, "---No Comment---");
defaultsOut.close();
The save() method needs a stream to write to, and a string which it uses as a comment at the top of the output.
Getting Property Information

Once you've set up your Properties object, you can query it for information about various properties it contains. The Properties class provides several methods for getting property information:

getProperty() (2 versions)
returns the value for the specified property. One version allows you to provide a default value--if the key is not found the default is returned.
list()
writes all the properties to the specified stream. This is useful for debugging.
propertyNames()
returns an Enumeration containing all of the keys contained in the Properties object.

Security Considerations: Note that access to properties are subject to approval by the current security manager. The example programs contained here are stand alone applications, which by default have no security manager. If you attempt to use this code in an applet, it might not work depending on the browser or viewer it's running in. See Understanding Applet Capabilities and Restrictions for information about the security restrictions placed on applets.

See also

java.util.Properties

Setting Program Attributes