Changes to Preferences API Between Public Review and Proposed Final Draft

Several typos were corrected. In addition there was one API change affecting two methods, and two clarifications:

API Change

1. Users of the preferences facility typically get a preferences node using one of two static factories: Preferences.nodeForPackage or Preferences.userNodeForPackage. There were several problems with these methods. They were convenient only from within a non-static context, as they rely on the presence of an object whose class belongs to the package in question. The suggested usage was:

       Preferences prefs = Preferences.userNodeForPackage(this);
   

   One typically wants to obtain a preferences node in a static context, as part of the initialization of the class that requires access to preferences. With the API in the Public Review draft, this left the programmer with little choice but to use the "root factory" and specify the node name explicitly using a string:

       Preferences prefs = Preferences.userRootForPackage().node(
                                "/com/acme/widget");
   

   If the string is wrong, compilation proceeds normally and you use the wrong preferences at runtime.

   A second problem is that subclasses of base types using preferences would not have easy access to the parent's preferences if the parent and child were in different packages. If the child used the suggested usage (above) it would get a node corresponding to its package rather than its parent's.

   To solve both of these problems, we are changing the argument type of the two static factories from Object to Class. The suggested usage becomes:

       Preferences prefs = Preferences.userNodeForPackage(Widget.class);
   

Clarifications

1. The public review draft could have been interpreted to suggest that the use of PreferencesFactory to designate a Preferences implementation was optional. The documentation has been clarified to indicate that it is mandatory, though J2SE implementations can differ on how the PreferencesFactory implementation is specified.
    
2. An implementation note has been added to AbstractPreferences discussing the implementation of Preferences for use in server environments, where the a single VM operates on behalf of multiple users. Authors of such implementations are strongly encouraged to determine the user at the time preferences are accessed (for example by the get or set method) rather than permanently associating a user with each Preferences instance. The latter technique conflicts with normal Preferences usage and would lead to great confusion.

   The usage notes have been amended to reflect this clarification.

Other

1. Added "Saving and Restoring Preferences" to usage notes.

Copyright 2000 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303 U.S.A. All rights reserved.