Presents your 
JAVA E-NEWSLETTER for May 19, 2003

<------------------------------------------->

SAMPLE THE PREFERENCES API

Managing preferences can be frustrating. There are so many decisions to
make, and you usually make changes each time you try to solve a problem
on your journey to preference perfection.

The new preferences package in Java 1.4 tries to solve the standard
problems of where to store preferences and how to access them. The
Preferences API is not a perfect solution, but it's a great start.

Preferences are divided into two types: user preferences, which are
managed on a per-user basis, and system preferences, for which there is only
one set. Preferences are managed in a tree of nodes, analogous to a file
system. There is a system root node and a user root node.

Let's examine the Preferences package steps needed to retrieve and store
preferences. In the interest of simplicity, this tip will only cover
system preferences. However, the mechanics for using user preferences are
exactly the same.

Before you can access a preference, you must first access the
java.util.pref.Preferences node that contains the setting you need. To accomplish
this, call one of the static methods of the Preferences class. There are
two types of static methods that return Preference nodes: One takes a
java.lang.Class object and the other takes no arguments and returns the root node:

Preferences prefs = Preferences.systemNodeForPackage(PreferencesTip.class);
Preferences prefs = Preferences.systemRoot();

If you use the root method, you'll have to make another call to get the
node you want based on its path name:

Preferences prefs = Preferences.systemRoot().node(pathName);

Once you have the node, retrieving a property is simple:

String value = prefs.get(preferenceName, defaultValue);

Notice that the get method takes two arguments: a String that is the
name of the preference you want to access, and a defaultValue that will be
returned if the preference you are requesting can't be found. All of the
get methods of the Preferences class are implemented this way. Here's the
list of get methods from the Preferences javadoc:

getBoolean(String key, boolean def)
getByteArray(String key, byte[] def)
getDouble(String key, double def)
getFloat(String key, float def)
getInt(String key, int def)
getLong(String key, long def)

Setting a preference is as simple as retrieving one. To set a
preference, call the appropriate put method. There is a reciprocal put method for
each get method. Here's an example of setting a preference:

prefs.putInt(preferenceName,1234);

Before you start using the Preferences API, consider how you'll name
your Preferences nodes. Naming nodes based on packages, the default if you
retrieve nodes via a Class object, is completely appropriate. If you ever
change package names, though, you may need to take steps to migrate old
preferences to the new node name.

The Preferences API solves a longstanding problem in an elegant manner.
Take a look at the javadoc because there's a lot more in there. In
addition to storing and retrieving properties, you can also export and import
nodes, remove nodes, monitor preference changes, and more.

----------------------------------------