Section 1: Identification

This JSR is submitted jointly by Sun Microsystems, Inc. (Sun) and the International Business Machines Corporation (IBM).

Contact information:

Joshua Bloch, Java Software, Sun Microsystems, Inc. e-mail: joshua.bloch@eng.sun.com voice: 408-343-1833

Mark Pozefsky, International Business Machines Corporation (IBM) e-mail: poz@us.ibm.com voice: 919-254-6051

This submission is endorsed by the Network Computer Management Group (NCMG).

Section 2: Request

Need that the work addresses - The proposed specification adds a simple API for managing user preference data and configuration data. Applications require preference and configuration data to adapt to different users, environments and needs. Applications need a way to store, retrieve, and modify this data.

Why the need isn't met by existing specifications - Currently, developers have two choices: either they make do without preference and configuration data (leading to reduced functionality), or they manage it in an ad hoc fashion. Often (though not always) preference and configuration data is stored in Properties Files, accessed through the java.util.Properties API. There are no standards as to where these files should reside on disk, or what they should be called. This makes it extremely difficult to backup a user's preference data, or transfer it from one machine to another. As the number of applications increases, the possibility of file name conflicts looms large. Further, this mechanism is of no help on platforms that lack a local disk, or where it is desirable that the data be stored in an external data store (such as an enterprise-wide LDAP directory service).

Less frequently, developers store user preference and configuration data in a directory service, accessed through the Java Naming and Directory Interface (JNDI) API. Unlike Properties, JNDI allows the use of arbitrary data stores (back-end neutrality). While JNDI is extremely powerful, it is also rather large, consisting of 5 packages and 83 classes. Further, JNDI does not provide any policy as to where in the directory name space the preference data should be stored, or in which name space.

In sum, neither Properties nor JNDI provide a simple, ubiquitous, back-end neutral preferences management facility. This JSR proposes such a facility, combining the simplicity of Properties with the back-end neutrality of JNDI. Further, it provides sufficient built-in policy to prevent name clashes, foster consistency, and encourage robustness in the face of inaccessibility of the backing data store.

Specification to be developed: Scope and Content - The specification will consist of the JavaDoc for a small package consisting of a single Preferences class and a few helper classes. The API will provide a simple mechanism for applications to store, retrieve, and modify user preference data, independent of the backing store.

Underlying technologies - Possible implementations of the API include: JNDI, flat files, OS-specific registries, and SQL databases. It is up to each JRE vendor to pick an appropriate default mechanism (or mechanisms) to ship with their JRE.

Proposed package name - javax.prefs. While this facility is destined for inclusion in the "core" JRE, it must also be usable as an extension, so the javax prefix is appropriate.

Possible platform dependencies - Each JRE implementor would have to choose an appropriate "backing store" for the preferences data, and write a Preferences implementation for that backing store if one were not already available. Some implementations (such as an OS-specific registry) will require native code.

Security implications - In some environments, it will be desirable to control access to preference data. The Preferences API will not mandate such access control, or specify it in detail, but it will be compatible with such access control.

Internationalization and localization dependencies - None.

Risk assessment - Providing this API will cause a certain amount of confusion among developers who have grown used to coping with Properties Files or the direct use of JNDI. The level of chaos may temporarily increase as preference data migrates from Properties files to Preferences. Failing to provide this API may hinder adoption of the platform (as competing platforms do provide such a mechanism, and it is widely used). Further, failing to provide this API may increase the profusion of ad hoc solutions, leading to a permanent increase in the level of chaos and difficulty of administration.

Existing specifications that might be rendered obsolete or deprecated by this work - This API would further reduce the applicability of java.util.Properties.

Existing specifications that might need revisions as a result of this work - Many existing facilities (for example, The Java Cryptography Extension) store preference or configuration data in properties files. Over time, these facilites should migrate their data into the Preferences mechanism.

Section 3: Contributions

Section 4: Frequently Asked Questions (FAQ) about the proposed Preferences API

Here are a few frequently asked questions about the proposed Preferences API that reviewers might find useful.

1. Why doesn't the proposed API use the Java 2 Collections Framework?

   Because it must be usable with JDK1.1. However, note that Preferences is compatible with the Map interface, with every instance of Object replaced by String. Thus, the interface will be familiar to users of the Collections Framework, and could in the future be made to implement the Map interface directly if the Java Platform were to be extended with generic types.
    

2. Why doesn't the proposed API have calls to examine defaults?

   Two reasons:

   1. Not every preferences data store that supports defaults will necessarily permit them to be queried directly.
   2. To the best of our knowledge, this functionality is not required in order to fulfill the requirements of the API, and would contribute unneeded complexity to the API.
   
    
3. Why doesn't the proposed API contain methods to read and write byte arrays?

   In facilities that store preferences for C and C++ applications (for example, the Windows registry) this functionality was generally used to store the Byte representations of structs, so the structs could be re-constituted after reading them from the repository. If we were to provide this functionality in the Java Platform, we'd do it by allowing serializable objects to be read and written to the repository, thus eliminating the manual serialization/deserialization step.
    

4. Why doesn't the proposed API contain methods to read and write arbitrary serializable objects?

   Serialized objects are somewhat fragile: if the version of the program that reads such a property differs from the version that wrote it, the object may not deserialize properly (or at all). We haven't made it impossible to store serialized objects in the repository, but at the same time, we haven't encouraged it by providing convenience methods.
    

5. Why doesn't the proposed API provide the ability to access per-system data, in addition to per-user?

   We believe that this functionality is required, and we plan to provide it in the final API.
    

6. Why doesn't the proposed API contain administrative methods (for example, to set defaults, or to manipulate other users' preferences)?

   It was felt that this sort of functionality is not necessary for a "first out." We may add it in a future version as we develop experience with the API.
    

7. Why do all of the get methods require the caller to pass in a default?

   This forces the authors of applications to provide reasonable default values, so that applications have a reasonable shot at running even if the repository is unavailable.
    

8. Why is Preferences an abstract class rather than an interface?

   It was felt that the ability to add new methods in an upward compatible fashion outweighed the disadvantage that Preferences can not be used as a "mixin."