The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: Essential Java Classes
Lesson: Setting Program Attributes

## Using Properties to Manage Program Attributes

> An attribute has two parts: a name and a value. For example, "`os.name`" is the name for one of the Java platform's system attributes; its value contains the name of the current operating system, such as "`Solaris`".

> The `Properties` class in the `java.util` package manages a set of key/value pairs. A key/value pair is like a dictionary entry: The key is the word, and the value is the definition. This is a perfect match for managing the names and values of attributes. Each `Properties` key contains the name of a system attribute, and its corresponding `Properties` value is the current value of that attribute.

> The `System` class uses a `Properties` object for managing system properties. Any Java program can use a `Properties` object to manage its program attributes. The `Properties` class itself provides methods for the following:

> - Loading key/value pairs into a `Properties` object from a stream
> - Retrieving a value from its key
> - Listing the keys and their values
> - Enumerating over the keys
> - Saving the properties to a stream
> `Properties` extends the `HashtableProperties` class and inherits methods from it for doing the following:
> - Testing to see if a particular key or value is in the `Properties` object
> - Getting the current number of key/value pairs
> - Removing a key and its value
> - Adding a key/value pair to the `Properties` list
> - Enumerating over the values or the keys
> - Retrieving a value by its key
> - Finding out if the `Properties` object is empty

> > Security Considerations: Access to properties is subject to approval by the current security manager. The example code segments in this section are assumed to be in standalone applications, which, by default, have no security manager. If you attempt to use this code in an applet, it may not work, depending on the browser or viewer in which it is running. See Security Restrictions for information about security restrictions on applets.

### The Life Cycle of a Program's `Properties`

> The following figure illustrates how a typical program might manage its attributes with a `Properties` object over the course of its execution.

> Starting Up
>   The actions given in the first three boxes occur when the program is starting up. First, the program loads the default properties from a well-known location into a `Properties` object. Normally, the default properties are stored in a file on disk along with the `.class` and other resource files for the program.

>   Next, the program creates another `Properties` object and loads the properties that were saved from the last time the program was run. Many applications store properties on a per-user basis, so the properties loaded in this step are usually in a specific file in a particular directory maintained by this application in the user's home directory. Finally, the program uses the default and remembered properties to initialize itself.

>   The key here is consistency. The application must always load and save properties to the same location so that it can find them the next time it's executed.

> Running
>   During the execution of the program, the user may change some settings, perhaps in a Preferences window, and the `Properties` object is updated to reflect these changes. For them to have a permanent effect, they must be saved.
> Exiting
>   Upon exiting, the program saves the properties to its well-known location, to be loaded again when the program is next started up.

### Setting Up Your `Properties` Object

> The following Java code performs the first two steps described in the previous section: loading the default properties and loading the remembered properties:

> >     . . .
> >     // create and load default properties
> >     Properties defaultProps = new Properties();
> >     FileInputStream in = new FileInputStream("defaultProperties");
> >     defaultProps.load(in);
> >     in.close();

> >     // create program properties with default
> >     Properties applicationProps = new Properties(defaultProps);

> >     // now load properties from last invocation
> >     in = new FileInputStream("appProperties");
> >     applicationProps.load(in);
> >     in.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. Then the load method reads the default values from a file on disk named `defaultProperties`.

> Next, the application uses a different constructor to create a second `Properties` object, `applicationProps`, whose default values are contained in `defaultProps`. The defaults come into play when a property is being retrieved. If the property can't be found in `applicationProps`, then its default list is searched.

> Finally, the code loads a set of properties into `applicationProps` from a file named `appProperties`. The properties in this file are those that were saved from the program the last time it was invoked (the next section shows you how this was done).

### Saving `Properties`

> The following example writes out the application properties from the previous example using `Properties`'s `store` method. The default properties don't need to be saved each time because they never change.

> >     FileOutputStream out = new FileOutputStream("appProperties");
> >     applicationProps.store(out, "---No Comment---");
> >     out.close();

> The `store` method needs a stream to write to, as well as a string that it uses as a comment at the top of the output.

> > Note: The `store` method was introduced to the `Properties` class in JDK 1.2. If you are using an earlier release, use the `save` method instead.

### Getting Property Information

> Once you've set up your `Properties` object, you can query it for information about various keys/values that it contains. An application gets information from a `Properties` object after start up so that it can initialize itself based on choices made by the user. The `Properties` class has several methods for getting property information:
> contains(Object value)
> containsKey(Object key)
>   Returns `true` if the value or the key is in the `Properties` object. `Properties` inherits these methods from `Hashtable`. Thus they accept `Object` arguments. You should pass in `String`s.
> getProperty(String key)
> getProperty(String key, String default)
>   Returns the value for the specified property. The second version allows you to provide a default value. If the key is not found, the default is returned.
> list(PrintStream s)
> list(PrintWriter w)
>   Writes all of the properties to the specified stream or writer. This is useful for debugging.
> elements()
> keys()
> propertyNames()
>   Returns an `Enumeration` containing the keys or values (as indicated by the method name) contained in the `Properties` object.
> size()
>   Returns the current number of key/value pairs.

### Setting `Properties`

> A user's interaction with a program during its execution may impact property settings. These changes should be reflected in the `Properties` object so that they are saved when the program exits (and calls the `store` method). You can use the following methods to change the properties in a `Properties` object:
> put(Object key, Object value)
>   Puts the key/value pair in the `Properties` object.
> remove(Object key)
>   Removes the key/value pair associated with key.
> Both `put` and `removeHashtable` and thus take `Objects`. You should pass in `Strings`.

### A Real-Life Example

> BINGO!, shows and documents a complete client/server application that implements the game of BINGO. Both the client and the server application in that example use `Properties` to maintain program attributes.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Copyright 1995-2004 Sun Microsystems, Inc. All rights reserved.