Preferences

Preferences

java.util.prefs

---

Java 1.4

A Preferences object represents a mapping between preference names , which are case-sensitive strings, and corresponding preference values. get( ) allows you to query the string value of a named preference, and put( ) allows you to set a string value for a named preference. Although all preference values are stored as strings, various convenience methods whose names begin with "get" and "put" exist to convert preference values of type boolean byte[ ] , double , float , int , and long to and from strings.

The remove( ) method allows you to delete a named preference altogether, and clear( ) deletes all preference values stored in a Preferences object. The keys( ) method returns an array of strings that specify the names of all preferences in the Preferences object.

Preference values are stored in some implementation-dependent back-end which may be a file, a LDAP directory server, the Windows Registry, or any other persistant "backing store". Note that all the get( ) methods of this class require a default value to be specified. They return this default if no value has been stored for the named preference, or if the backing store is unavailable for any reason. The Preferences class is completely independent of the underlying implementation, except that it enforces an 80-character limit for preference names and Preference node names (see below), and a 8192-character limit on preference value strings.

Preferences does not have a public construtor. To obtain a Preferences object for use in your application, you must must use one of the static methods described below. Each Preferences object is a node in a hierarchy of Preferences nodes. There are two distinct hierarchies: one stores user -specific preferences, and one stores system-wide preferences. All Preferences nodes (in either hierarchy) have a unique name and use the same naming convention that Unix filesystems use. Applications (and classes) may store their preferences in a Preferences node with any name, but the convention is to use a node name that corresponds to the package name of the application or class, with all "." characters in the package name converted to "/" characters . For example, the preferences node used by java.lang.System would be "/java/lang".

Preferences defines static methods that you can use to obtain the Preferences objects your application requires. Pass a Class object to systemNodeForPackage( ) and userNodeForPackage( ) to obtain the system and user Preferences objects that are specific to the package of that class. If you want a Preferences node specific to a single class rather than to the package, you can pass the class name to the node( ) method of the package-specific node returned by systemNodeForPackage( ) or userNodeForPackage( ) . If you want to navigate the entire tree of preferences nodes (which most applications never need to do) call systemRoot( ) and userRoot( ) to obtain the root node of the two hierarchies, and then use the node( ) method to look up child nodes of those roots.

Various Preferences methods allow you to traverse the preferences hierarchies. parent( ) returns the parent Preferences node. childrenNames( ) returns an array of the relative names of all children of a Preferences node. node( ) returns a named Preferences object from the hierarchy. If the specified node name begins with a slash, it is an absolute name and is interpreted relative to the root of the hierarchy. Otherwise, it is a relative name and is interpreted relative to the Preferences object on which node( ) was called. nodeExists( ) allows you to test whether a named node exists. removeNode( ) allows you to delete an entire Preferences node from the hierarchy (useful when uninstalling an application). name( ) returns the simple name of a Preferences node, relative to its parent. absoutePath( ) returns the full, absolute name of the node, relative to the root of the hierarchy. Finally, isUserNode( ) allows you to determine whether a Preferences object is part of the user or system hierarchies.

Many applications will simply read their preference values once at startup. Long-lived applications or applications that want to respond dynamically to modifications to preferences (such as applications that are tightly integrated with a graphical desktop) may use addPreferenceChangeListener( ) to register a PreferenceChangeListener to recieve notifications of preference changes (in the form of PreferenceChangeEvent objects). Applications that are interested in changes to the Preferences hierarchy itself can register a NodeChangeListener .

put( ) and the various type-specific put...( ) convenience methods may return asynchonously, before the new preference value is stored persistantly within the backing store. Call flush( ) to force any preference changes to this Preferences node (and any of its descendants in the hierarchy) to be stored persistantly. (Note that it is not necessary to call flush( ) before an application terminates: all preferences will eventually be made persistant.) More than one application (within more than one Java virtual machine) may set preference values in the same Preferences node at the same time. Call sync( ) to ensure that future calls to get( ) and its related convenience methods retrieve current preference values set by this or other virtual machines. Note that the flush( ) and sync( ) operations are typically much more expensive than get( ) and put( ) operations, and applications do not often need to use them.

Preferences implementations ensure that all the methods of this class are thread safe. If multiple threads or multiple VMs write store the same preferences concurrently, their values may overwrite one another, but the preference data will not be corrupted. Note that, for simplicity, Preferences does not define any way to set multiple preferences in a single atomic transaction. If you need to ensure atomicity for multiple preference values, define a data format that allows you to store all the requisite values in a single string, and set and query those values with a single call to put( ) or get( ) .

The contents of a Preferences node, or of a node and all of its descendants may be exported as an XML file with exportNode( ) and exportSubtree( ) . The static importPreferences( ) method reads an exported XML file back into the preferences hierarchy. These methods allow backups to be made of preference data, and allow preferences to be transferred between systems or between users.

Prior to Java 1.4, application preferences were sometimes managed with the java.util.Properties object.

 public abstract class  Preferences  {  // Protected Constructors  protected  Preferences  ( );  // Public Constants  public static final int  MAX_KEY_LENGTH  ;  =80  public static final int  MAX_NAME_LENGTH  ;  =80  public static final int  MAX_VALUE_LENGTH  ;  =8192   // Public Class Methods  public static void  importPreferences  (java.io.InputStream  is  )  throws java.io.IOException, InvalidPreferencesFormatException;        public static Preferences  systemNodeForPackage  (Class<?>  c  );        public static Preferences  systemRoot  ( );        public static Preferences  userNodeForPackage  (Class<?>  c  );        public static Preferences  userRoot  ( );  // Event Registration Methods (by event name)  public abstract void  addNodeChangeListener  (NodeChangeListener  ncl  );        public abstract void  removeNodeChangeListener  (NodeChangeListener  ncl  );        public abstract void  addPreferenceChangeListener  (PreferenceChangeListener  pcl  );        public abstract void  removePreferenceChangeListener  (PreferenceChangeListener  pcl  );  // Public Instance Methods  public abstract String  absolutePath  ( );        public abstract String[ ]  childrenNames  ( ) throws BackingStoreException;        public abstract void  clear  ( ) throws BackingStoreException;        public abstract void  exportNode  (java.io.OutputStream  os  ) throws java.io.IOException,          BackingStoreException;        public abstract void  exportSubtree  (java.io.OutputStream  os  ) throws java.io.IOException,          BackingStoreException;        public abstract void  flush  ( ) throws BackingStoreException;        public abstract String  get  (String  key  , String  def  );        public abstract boolean  getBoolean  (String  key  , boolean  def  );        public abstract byte[ ]  getByteArray  (String  key  , byte[ ]  def  );        public abstract double  getDouble  (String  key  , double  def  );        public abstract float  getFloat  (String  key  , float  def  );        public abstract int  getInt  (String  key  , int  def  );        public abstract long  getLong  (String  key  , long  def  );        public abstract boolean  isUserNode  ( );        public abstract String[ ]  keys  ( ) throws BackingStoreException;        public abstract String  name  ( );        public abstract Preferences  node  (String  pathName  );        public abstract boolean  nodeExists  (String  pathName  ) throws BackingStoreException;        public abstract Preferences  parent  ( );        public abstract void  put  (String  key  , String  value  );        public abstract void  putBoolean  (String  key  , boolean  value  );        public abstract void  putByteArray  (String  key  , byte[ ]  value  );        public abstract void  putDouble  (String  key  , double  value  );        public abstract void  putFloat  (String  key  , float  value  );        public abstract void  putInt  (String  key  , int  value  );        public abstract void  putLong  (String  key  , long  value  );        public abstract void  remove  (String  key  );        public abstract void  removeNode  ( ) throws BackingStoreException;        public abstract void  sync  ( ) throws BackingStoreException;  // Public Methods Overriding Object  public abstract String  toString  ( );   } 

Subclasses

AbstractPreferences

Passed To

NodeChangeEvent.NodeChangeEvent( ) , PreferenceChangeEvent.PreferenceChangeEvent( )

Returned By

AbstractPreferences.{node( ) , parent( )} , NodeChangeEvent.{getChild( ) , getParent( )} , PreferenceChangeEvent.getNode( ) , PreferencesFactory.{systemRoot( ) , userRoot( )}