preferences.java

java源代码 请看看啊 提点宝贵的意见

/*
 * @(#)Preferences.java	1.20 03/09/05
 *
 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package java.util.prefs;

import java.io.InputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.security.AccessController; 
import java.security.Permission;
import java.security.PrivilegedAction;


// These imports needed only as a workaround for a JavaDoc bug
import java.lang.RuntimePermission;
import java.lang.Integer;
import java.lang.Long;
import java.lang.Float;
import java.lang.Double;

/**
 * A node in a hierarchical collection of preference data.  This class
 * allows applications to store and retrieve user and system
 * preference and configuration data.  This data is stored
 * persistently in an implementation-dependent backing store.  Typical
 * implementations include flat files, OS-specific registries,
 * directory servers and SQL databases.  The user of this class needn't
 * be concerned with details of the backing store.
 * 
 * <p>There are two separate trees of preference nodes, one for user
 * preferences and one for system preferences.  Each user has a separate user
 * preference tree, and all users in a given system share the same system
 * preference tree.  The precise description of "user" and "system" will vary
 * from implementation to implementation.  Typical information stored in the
 * user preference tree might include font choice, color choice, or preferred
 * window location and size for a particular application.  Typical information
 * stored in the system preference tree might include installation
 * configuration data for an application.
 *
 * <p>Nodes in a preference tree are named in a similar fashion to
 * directories in a hierarchical file system.   Every node in a preference
 * tree has a <i>node name</i> (which is not necessarily unique),
 * a unique <i>absolute path name</i>, and a path name <i>relative</i> to each
 * ancestor including itself.
 *
 * <p>The root node has a node name of the empty string ("").  Every other
 * node has an arbitrary node name, specified at the time it is created.  The
 * only restrictions on this name are that it cannot be the empty string, and
 * it cannot contain the slash character ('/').
 *
 * <p>The root node has an absolute path name of <tt>"/"</tt>.  Children of
 * the root node have absolute path names of <tt>"/" + </tt><i>&lt;node
 * name&gt;</i>.  All other nodes have absolute path names of <i>&lt;parent's
 * absolute path name&gt;</i><tt> + "/" + </tt><i>&lt;node name&gt;</i>.
 * Note that all absolute path names begin with the slash character.
 *
 * <p>A node <i>n</i>'s path name relative to its ancestor <i>a</i>
 * is simply the string that must be appended to <i>a</i>'s absolute path name
 * in order to form <i>n</i>'s absolute path name, with the initial slash
 * character (if present) removed.  Note that:
 * <ul>
 * <li>No relative path names begin with the slash character.
 * <li>Every node's path name relative to itself is the empty string.
 * <li>Every node's path name relative to its parent is its node name (except
 * for the root node, which does not have a parent).
 * <li>Every node's path name relative to the root is its absolute path name
 * with the initial slash character removed.
 * </ul>
 *
 * <p>Note finally that:
 * <ul>
 * <li>No path name contains multiple consecutive slash characters.
 * <li>No path name with the exception of the root's absolute path name
 * ends in the slash character.
 * <li>Any string that conforms to these two rules is a valid path name.
 * </ul>
 *
 * <p>All of the methods that modify preferences data are permitted to operate
 * asynchronously; they may return immediately, and changes will eventually
 * propagate to the persistent backing store with an implementation-dependent
 * delay.  The <tt>flush</tt> method may be used to synchronously force
 * updates to the backing store.  Normal termination of the Java Virtual
 * Machine will <i>not</i> result in the loss of pending updates -- an explicit
 * <tt>flush</tt> invocation is <i>not</i> required upon termination to ensure
 * that pending updates are made persistent.
 * 
 * <p>All of the methods that read preferences from a <tt>Preferences</tt>
 * object require the invoker to provide a default value.  The default value is
 * returned if no value has been previously set <i>or if the backing store is
 * unavailable</i>.  The intent is to allow applications to operate, albeit
 * with slightly degraded functionality, even if the backing store becomes
 * unavailable.  Several methods, like <tt>flush</tt>, have semantics that
 * prevent them from operating if the backing store is unavailable.  Ordinary
 * applications should have no need to invoke any of these methods, which can
 * be identified by the fact that they are declared to throw {@link
 * BackingStoreException}.
 *
 * <p>The methods in this class may be invoked concurrently by multiple threads
 * in a single JVM without the need for external synchronization, and the
 * results will be equivalent to some serial execution.  If this class is used
 * concurrently <i>by multiple JVMs</i> that store their preference data in
 * the same backing store, the data store will not be corrupted, but no
 * other guarantees are made concerning the consistency of the preference
 * data.
 *
 * <p>This class contains an export/import facility, allowing preferences
 * to be "exported" to an XML document, and XML documents representing
 * preferences to be "imported" back into the system.  This facility
 * may be used to back up all or part of a preference tree, and
 * subsequently restore from the backup.
 *
 * <p>The XML document has the following DOCTYPE declaration:
 * <pre>
 * &lt;!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"&gt;
 * </pre>
 * Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is
 * <i>not</i> accessed when exporting or importing prefereneces; it merely
 * serves as a string to uniquely identify the DTD, which is:
 * <pre>
 *    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 *
 *    &lt;!-- DTD for a Preferences tree. --&gt;
 *
 *    &lt;!-- The preferences element is at the root of an XML document
 *         representing a Preferences tree. --&gt;
 *    &lt;!ELEMENT preferences (root)&gt;
 *  
 *    &lt;!-- The preferences element contains an optional version attribute,
 *          which specifies version of DTD. --&gt;
 *    &lt;!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" &gt  
 *
 *    &lt;!-- The root element has a map representing the root's preferences
 *         (if any), and one node for each child of the root (if any). --&gt;
 *    &lt;!ELEMENT root (map, node*) &gt;
 *
 *    &lt;!-- Additionally, the root contains a type attribute, which
 *         specifies whether it's the system or user root. --&gt;
 *    &lt;!ATTLIST root
 *              type (system|user) #REQUIRED &gt;
 *
 *    &lt;!-- Each node has a map representing its preferences (if any),
 *         and one node for each child (if any). --&gt;
 *    &lt;!ELEMENT node (map, node*) &gt;
 *
 *    &lt;!-- Additionally, each node has a name attribute --&gt;
 *    &lt;!ATTLIST node
 *              name CDATA #REQUIRED &gt;
 *
 *    &lt;!-- A map represents the preferences stored at a node (if any). --&gt;
 *    &lt;!ELEMENT map (entry*) &gt;
 *
 *    &lt;!-- An entry represents a single preference, which is simply
 *          a key-value pair. --&gt;
 *    &lt;!ELEMENT entry EMPTY &gt;
 *    &lt;!ATTLIST entry
 *              key   CDATA #REQUIRED
 *              value CDATA #REQUIRED &gt;
 * </pre>
 *
 * Every <tt>Preferences</tt> implementation must have an associated {@link
 * PreferencesFactory} implementation.  Every J2SE implementation must provide
 * some means of specifying which <tt>PreferencesFactory</tt> implementation
 * is used to generate the root preferences nodes.  This allows the
 * administrator to replace the default preferences implementation with an
 * alternative implementation.
 *
 * <p>Implementation note: In Sun's JRE, the <tt>PreferencesFactory</tt>
 * implementation is specified using the system property
 * <tt>java.util.prefs.PreferencesFactory</tt>, which must be set to the fully 
 * qualified name of a class implementing the <tt>PreferencesFactory</tt>.
 *
 * @author  Josh Bloch
 * @version 1.20, 09/05/03
 * @since   1.4
 */
public abstract class Preferences {
    /*
     * Initialize factory as specified by system property
     * java.util.prefs.PreferencesFactory.
     */
    private static final PreferencesFactory factory;

    static {
	PreferencesFactory factory0=null;
        String factoryName =
        (String) AccessController.doPrivileged(new PrivilegedAction() {
              public Object run() {
                  return System.getProperty(
                                        "java.util.prefs.PreferencesFactory");
              }
        });

        if (factoryName == null)
            throw new InternalError(
                "System property java.util.prefs.PreferencesFactory not set");

        try {
            factory0 = (PreferencesFactory)
               Class.forName(factoryName, false,
                             ClassLoader.getSystemClassLoader()).newInstance();
        } catch(Exception ex) {
	    try {
		//workaround for javaws, plugin, 
		//load factory class using non-system classloader
		//We enforce the security here to require All Permission
		SecurityManager sm = System.getSecurityManager();
		if (sm != null) {
		    sm.checkPermission(new java.security.AllPermission());
		}
	        factory0 = (PreferencesFactory)
                    Class.forName(factoryName, false,
                        Thread.currentThread().getContextClassLoader()).newInstance();
	    } catch (Exception e) {
                throw new InternalError(
                    "Can't instantiate Preferences factory " + e);
            }
        }
	finally {
	    factory = factory0;
	}
    }

    /**
     * Maximum length of string allowed as a key (80 characters).
     */
    public static final int MAX_KEY_LENGTH = 80;

    /**
     * Maximum length of string allowed as a value (8192 characters).
     */
    public static final int MAX_VALUE_LENGTH = 8*1024;

    /**
     * Maximum length of a node name (80 characters).
     */
    public static final int MAX_NAME_LENGTH = 80;

    /**
     * Returns the preference node from the calling user's preference tree
     * that is associated (by convention) with the specified class's package.
     * The convention is as follows: the absolute path name of the node is the
     * fully qualified package name, preceded by a slash (<tt>'/'</tt>), and
     * with each period (<tt>'.'</tt>) replaced by a slash.  For example the
     * absolute path name of the node associated with the class
     * <tt>com.acme.widget</tt> is <tt>/com/acme/widget</tt>.
     *
     * <p>This convention does not apply to the unnamed package, whose
     * associated preference node is <tt>&lt;unnamed&gt;</tt>.  This node
     * is not intended for long term use, but for convenience in the early
     * development of programs that do not yet belong to a package, and 
     * for "throwaway" programs.  <i>Valuable data should not be stored
     * at this node as it is shared by all programs that use it.</i>
     *
     * <p>A class <tt>Foo</tt> wishing to access preferences pertaining to its
     * package can obtain a preference node as follows: <pre>
     *    static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
     * </pre>
     * This idiom obviates the need for using a string to describe the
     * preferences node and decreases the likelihood of a run-time failure.
     * (If the class name is is misspelled, it will typically result in a
     * compile-time error.)
     *
     * <p>Invoking this method will result in the creation of the returned
     * node and its ancestors if they do not already exist.  If the returned
     * node did not exist prior to this call, this node and any ancestors that
     * were created by this call are not guaranteed to become permanent until
     * the <tt>flush</tt> method is called on the returned node (or one of its
     * ancestors or descendants).
     *
     * @param c the class for whose package a user preference node is desired.
     * @return the user preference node associated with the package of which
     *         <tt>c</tt> is a member.
     * @throws NullPointerException if <tt>c</tt> is <tt>null</tt>.
     * @throws SecurityException if a security manager is present and
     *         it denies <tt>RuntimePermission("preferences")</tt>.
     * @see    RuntimePermission
     */
    public static Preferences userNodeForPackage(Class c) {
        return userRoot().node(nodeName(c));
    }

    /**
     * Returns the preference node from the system preference tree that is
     * associated (by convention) with the specified class's package.  The
     * convention is as follows: the absolute path name of the node is the
     * fully qualified package name, preceded by a slash (<tt>'/'</tt>), and
     * with each period (<tt>'.'</tt>) replaced by a slash.  For example the
     * absolute path name of the node associated with the class
     * <tt>com.acme.widget</tt> is <tt>/com/acme/widget</tt>.
     *