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
Figure 38 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 save method. The
default properties don't need to be saved each time because they never
change.
FileOutputStream out = new FileOutputStream("appProperties");
applicationProps.save(out, "---No Comment---");
out.close();
The save method needs a stream to write to, as well as a
string that 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 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 Strings.
-
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 save 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 remove come from Hashtable
and thus take Objects. You
should pass in Strings.
A Real-Life Example
Putting It All Together ,
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.
|
