模块  java.prefs
软件包  java.util.prefs

Class Preferences

  • 已知直接子类：
    AbstractPreferences 
    public abstract class Preferencesextends Object
    偏好数据的分层集合中的节点。 此类允许应用程序存储和检索用户和系统首选项和配置数据。 此数据持久存储在依赖于实现的后备存储中。 典型的实现包括平面文件，特定于操作系统的注册表，目录服务器和SQL数据库。 此类的用户无需关心后备存储的详细信息。

    有两个独立的优先节点树，一个用于用户首选项，另一个用于系统首选项。 每个用户都有一个单独的用户首选项树，并且给定系统中的所有用户共享相同的系统首选项树。 “用户”和“系统”的精确描述将因实现而异。 存储在用户偏好树中的典型信息可以包括特定应用的字体选择，颜色选择或优选窗口位置和大小。 存储在系统首选项树中的典型信息可能包括应用程序的安装配置数据。

    偏好树中的节点以与分层文件系统中的目录类似的方式命名。 首选项树中的每个节点都有一个节点名称 （不一定是唯一的），一个唯一的绝对路径名 ，以及一个相对于每个祖先（包括它自己）的路径名。

    根节点的节点名称为空字符串（“”）。 每个其他节点都有一个任意节点名称，在创建时指定。 对此名称的唯一限制是它不能是空字符串，并且它不能包含斜杠字符（'/'）。

    根节点的绝对路径名称为"/" 。 根节点的子节点的绝对路径名为"/" + <节点名称> 。 所有其他节点的绝对路径名称为<parent的绝对路径名> + "/" + <node name> 。 请注意，所有绝对路径名都以斜杠字符开头。

    节点n的相对路径名到它的祖先一个仅仅是必须附加到字符串的绝对路径名，以便以形成n的绝对路径名，与初始斜杠字符（如果存在的话）中除去。 注意：

    • 没有相对路径名以斜杠字符开头。
    • 每个节点相对于自身的路径名称都是空字符串。
    • 每个节点相对于其父节点的路径名称是其节点名称（根节点除外，它没有父节点）。
    • 每个节点相对于根的路径名是其绝对路径名，并删除了初始斜杠字符。

    最后注意：

    • 没有路径名包含多个连续的斜杠字符。
    • 除了根的绝对路径名外，没有路径名以斜杠字符结尾。
    • 符合这两个规则的任何字符串都是有效的路径名。

    所有修改首选项数据的方法都允许异步操作; 它们可能会立即返回，并且更改最终将传播到具有依赖于实现的延迟的持久性后备存储。 flush方法可用于同步强制更新到后备存储。 Java虚拟机的正常终止不会导致挂起更新的损失-明确flush 不需要终止时调用，以确保挂起更新变得持久。

    从Preferences对象读取首选项的所有方法都需要调用者提供默认值。 如果先前未设置任何值或后备存储不可用，则返回默认值。 目的是允许应用程序运行，即使功能稍有降级，即使后备存储变得不可用。 有些方法（如flush ）具有语义，如果后备存储不可用，则会阻止它们运行。 普通应用程序不应该调用任何这些方法，这些方法可以通过声明它们被抛出BackingStoreException来识别 。

    此类中的方法可以由单个JVM中的多个线程同时调用，而无需外部同步，结果将等效于某些串行执行。 如果多个JVM同时使用此类将其首选项数据存储在同一个后备存储中，则数据存储不会被破坏，但不会对优先级数据的一致性做出其他保证。

    此类包含导出/导入工具，允许将首选项“导出”到XML文档，并将表示首选项的XML文档“导入”回系统。 此工具可用于备份全部或部分首选项树，然后从备份中恢复。

    XML文档具有以下DOCTYPE声明： 

       <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
    请注意，导出或导入首选项时不会访问系统URI（http://java.sun.com/dtd/preferences.dtd）; 它只是作为一个字符串来唯一标识DTD，它是： 
       <?xml version="1.0" encoding="UTF-8"?> <!-- DTD for a Preferences tree. --> <!-- The preferences element is at the root of an XML document representing a Preferences tree. --> <!ELEMENT preferences (root)> <!-- The preferences element contains an optional version attribute, which specifies version of DTD. --> <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" > <!-- The root element has a map representing the root's preferences (if any), and one node for each child of the root (if any). --> <!ELEMENT root (map, node*) > <!-- Additionally, the root contains a type attribute, which specifies whether it's the system or user root. --> <!ATTLIST root type (system|user) #REQUIRED > <!-- Each node has a map representing its preferences (if any), and one node for each child (if any). --> <!ELEMENT node (map, node*) > <!-- Additionally, each node has a name attribute --> <!ATTLIST node name CDATA #REQUIRED > <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT map (entry*) > <!-- An entry represents a single preference, which is simply a key-value pair. --> <!ELEMENT entry EMPTY > <!ATTLIST entry key CDATA #REQUIRED value CDATA #REQUIRED >
    每个Preferences实现必须具有关联的PreferencesFactory实现。 每个Java（TM）SE实现必须提供指定的一些装置，它PreferencesFactory实现用于生成根偏好节点。 这允许管理员使用替代实现替换默认首选项实现。
    Implementation Note:
    PreferencesFactory实施位置如下：

    1. 如果定义了系统属性java.util.prefs.PreferencesFactory ，则它将被视为实现PreferencesFactory接口的类的完全限定名称。 该类被加载并实例化; 如果此过程失败，则抛出未指定的错误。

    2. 如果PreferencesFactory实现类文件已安装在system class loader可见的jar文件中，并且该jar文件在资源目录META-INF/services包含名为java.util.prefs.PreferencesFactory的提供程序配置文件，则会获取该文件中指定的第一个类名。 如果提供了多个这样的jar文件，将使用找到的第一个jar文件。 该类被加载并实例化; 如果此过程失败，则抛出未指定的错误。

    3. 最后，如果既没有提供上述的系统属性，也不是一个扩展jar文件，则系统级默认PreferencesFactory实施底层平台被加载和实例化。

    从以下版本开始：
    1.4

    • 字段汇总

      字段  
      变量和类型 字段 描述
      static int MAX_KEY_LENGTH
      允许作为键的最大字符串长度（80个字符）。
      static int MAX_NAME_LENGTH
      节点名称的最大长度（80个字符）。
      static int MAX_VALUE_LENGTH
      允许的最大字符串长度值（8192个字符）。

    • 构造方法摘要

      构造方法  
      变量 构造器 描述
      protected Preferences()
      唯一的构造函数。

    • 方法摘要

      所有方法  静态方法  实例方法 抽象方法  具体的方法 
      变量和类型 方法 描述
      abstract String absolutePath()
      返回此首选项节点的绝对路径名。
      abstract void addNodeChangeListener​(NodeChangeListener ncl)
      注册指定的侦听器以接收此节点的 节点更改事件 。
      abstract void addPreferenceChangeListener​(PreferenceChangeListener pcl)
      注册指定的侦听器以接收此首选项节点的 首选项更改事件 。
      abstract String[] childrenNames()
      返回此首选项节点的子节点相对于此节点的名称。
      abstract void clear()
      删除此首选项节点中的所有首选项（键值关联）。
      abstract void exportNode​(OutputStream os)
      在指定的输出流上发出一个XML文档，表示此节点中包含的所有首选项（但不包括其后代）。
      abstract void exportSubtree​(OutputStream os)
      发出一个XML文档，表示此节点及其所有后代中包含的所有首选项。
      abstract void flush()
      强制将此首选项节点及其后代的内容更改为持久性存储。
      abstract String get​(String key, String def)
      返回与此首选项节点中的指定键关联的值。
      abstract boolean getBoolean​(String key, boolean def)
      返回与此首选项节点中指定键关联的字符串表示的布尔值。
      abstract byte[] getByteArray​(String key, byte[] def)
      返回由此首选项节点中与指定键关联的字符串表示的字节数组值。
      abstract double getDouble​(String key, double def)
      返回与此首选项节点中指定键关联的字符串表示的double值。
      abstract float getFloat​(String key, float def)
      返回与此首选项节点中指定键关联的字符串表示的float值。
      abstract int getInt​(String key, int def)
      返回与此首选项节点中指定键关联的字符串表示的int值。
      abstract long getLong​(String key, long def)
      返回与此首选项节点中指定键关联的字符串表示的long值。
      static void importPreferences​(InputStream is)
      在指定的输入流上导入XML文档表示的所有首选项。
      abstract boolean isUserNode()
      返回 true如果此首选项节点位于用户首选项树， false ，如果它在系统首选项树。
      abstract String[] keys()
      返回此首选项节点中具有关联值的所有键。
      abstract String name()
      返回此首选项节点相对于其父节点的名称。
      abstract Preferences node​(String pathName)
      返回与此节点在同一树中的命名首选项节点，创建它及其任何祖先（如果它们尚不存在）。
      abstract boolean nodeExists​(String pathName)
      如果指定的首选项节点与此节点位于同一树中，则返回true。
      abstract Preferences parent()
      返回此首选项节点的父节点，如果这是根节点，则返回 null 。
      abstract void put​(String key, String value)
      将指定的值与此首选项节点中的指定键相关联。
      abstract void putBoolean​(String key, boolean value)
      将表示指定布尔值的字符串与此首选项节点中的指定键相关联。
      abstract void putByteArray​(String key, byte[] value)
      将表示指定字节数组的字符串与此首选项节点中的指定键相关联。
      abstract void putDouble​(String key, double value)
      将表示指定double值的字符串与此首选项节点中的指定键相关联。
      abstract void putFloat​(String key, float value)
      将表示指定浮点值的字符串与此首选项节点中的指定键关联。
      abstract void putInt​(String key, int value)
      将表示指定int值的字符串与此首选项节点中的指定键关联。
      abstract void putLong​(String key, long value)
      将表示指定long值的字符串与此首选项节点中的指定键相关联。
      abstract void remove​(String key)
      删除与此首选项节点中指定键关联的值（如果有）。
      abstract void removeNode()
      删除此首选项节点及其所有后代，从而使已删除节点中包含的任何首选项无效。
      abstract void removeNodeChangeListener​(NodeChangeListener ncl)
      删除指定的 NodeChangeListener ，因此不再接收更改事件。
      abstract void removePreferenceChangeListener​(PreferenceChangeListener pcl)
      删除指定的首选项更改侦听器，因此它不再接收首选项更改事件。
      abstract void sync()
      确保将来从此首选项节点及其后代读取将反映在 sync调用之前提交到持久性存储（来自任何VM）的任何更改。
      static Preferences systemNodeForPackage​(类<?> c)
      从系统首选项树返回首选项节点，该首选项树（按照惯例）与指定的类的包关联。
      static Preferences systemRoot()
      返回系统的根首选项节点。
      abstract String toString()
      返回此首选项节点的字符串表示形式，如同通过表达式计算： (this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 。
      static Preferences userNodeForPackage​(类<?> c)
      从调用用户的首选项树返回首选项节点，该首选项树（按照惯例）与指定的类的包关联。
      static Preferences userRoot()
      返回调用用户的根首选项节点。

    • 字段详细信息

      • MAX_KEY_LENGTH

        public static final int MAX_KEY_LENGTH
        允许作为键的最大字符串长度（80个字符）。
        另请参见：
        常数字段值

      • MAX_VALUE_LENGTH

        public static final int MAX_VALUE_LENGTH
        允许的最大字符串长度值（8192个字符）。
        另请参见：
        常数字段值

      • MAX_NAME_LENGTH

        public static final int MAX_NAME_LENGTH
        节点名称的最大长度（80个字符）。
        另请参见：
        常数字段值

    • 构造方法详细信息

      • Preferences

        protected Preferences()
        唯一的构造函数。 （对于子类构造函数的调用，通常是隐式的。）

    • 方法详细信息

      • userNodeForPackage

        public static Preferences userNodeForPackage​(类<?> c)
        从调用用户的首选项树返回首选项节点，该首选项树（按照惯例）与指定的类的包关联。 约定如下：节点的绝对路径名是完全限定的包名，前面有斜杠（ '/' ），每个句点（ '.' ）替换为斜杠。 例如，与类com.acme.widget.Foo关联的节点的绝对路径名是/com/acme/widget 。

        此约定不适用于未命名的包，其关联的首选项节点为<unnamed> 。 此节点不是为了长期使用，而是为了方便早期开发尚未属于软件包的程序，以及“一次性”程序。 有价值的数据不应存储在此节点，因为它由所有使用它的程序共享。

        希望访问与其包有关的偏好的类Foo可以获得如下的偏好节点： 

          static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
        这个习惯用法不需要使用字符串来描述首选项节点，并减少运行时失败的可能性。 （如果类名拼写错误，通常会导致编译时错误。）

        调用此方法将导致创建返回的节点及其祖先（如果它们尚不存在）。 如果在此调用之前返回的节点不存在，则在返回的节点（或其祖先或后代之一）上调用flush方法之前，不保证此节点和此调用创建的任何祖先都是永久的。

        参数
        c - 需要其用户首选项节点的类的类。
        结果
        与 c的包相关联的用户首选项节点。
        异常
        NullPointerException - 如果 c是 null 。
        SecurityException - 如果存在安全管理器且它拒绝 RuntimePermission("preferences") 。
        另请参见：
        RuntimePermission

      • systemNodeForPackage

        public static Preferences systemNodeForPackage​(类<?> c)
        从系统首选项树返回首选项节点，该首选项树（按照惯例）与指定的类的包关联。 约定如下：节点的绝对路径名是完全限定的包名，前面有斜杠（ '/' ），每个句点（ '.' ）替换为斜杠。 例如，与类com.acme.widget.Foo关联的节点的绝对路径名是/com/acme/widget 。

        此约定不适用于未命名的包，其关联的首选项节点为<unnamed> 。 此节点不是为了长期使用，而是为了方便早期开发尚未属于软件包的程序，以及“一次性”程序。 有价值的数据不应存储在此节点，因为它由所有使用它的程序共享。

        希望访问与其包有关的首选项的类Foo可以获得如下的首选节点： 

          static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);
        这个习惯用法不需要使用字符串来描述首选项节点，并减少运行时失败的可能性。 （如果类名拼写错误，通常会导致编译时错误。）

        调用此方法将导致创建返回的节点及其祖先（如果它们尚不存在）。 如果在此调用之前返回的节点不存在，则在返回的节点（或其祖先或后代之一）上调用flush方法之前，不保证此节点和此调用创建的任何祖先都是永久的。

        参数
        c - 需要其系统首选项节点的类的类。
        结果
        与 c的包相关联的系统首选项节点。
        异常
        NullPointerException - 如果 c是 null 。
        SecurityException - 如果存在安全管理器并且它拒绝 RuntimePermission("preferences") 。
        另请参见：
        RuntimePermission

      • userRoot

        public static Preferences userRoot()
        返回调用用户的根首选项节点。
        结果
        调用用户的根首选项节点。
        异常
        SecurityException - 如果存在安全管理器且它拒绝 RuntimePermission("preferences") 。
        另请参见：
        RuntimePermission

      • systemRoot

        public static Preferences systemRoot()
        返回系统的根首选项节点。
        结果
        系统的根首选项节点。
        异常
        SecurityException - 如果存在安全管理器且它拒绝 RuntimePermission("preferences") 。
        另请参见：
        RuntimePermission

      • put

        public abstract void put​(String key,                         String value)
        将指定的值与此首选项节点中的指定键相关联。
        参数
        key - 与指定值关联的键。
        value - 与指定键关联的值。
        异常
        NullPointerException - 如果密钥或值为 null 。
        IllegalArgumentException - 如果 key.length()超过 MAX_KEY_LENGTH或者如果 value.length超过 MAX_VALUE_LENGTH 。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        IllegalArgumentException - 如果任一键或值包含空控制字符，则代码点U + 0000。

      • get

        public abstract String get​(String key,                           String def)
        返回与此首选项节点中的指定键关联的值。 如果没有与键关联的值，或者后备存储不可访问，则返回指定的默认值。

        某些实现可以在其后备存储中存储默认值。 如果没有与指定键关联的值但存在这样的存储默认值 ，则优先返回指定的默认值。

        参数
        key - 要返回其关联值的键。
        def - 如果此首选项节点没有与 key关联的值，则返回的值。
        结果
        值相关联的 key ，或 def如果没有值相关联 key ，或后备存储器是不可访问的。
        异常
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        NullPointerException - 如果key是null 。 （A null为值def 是允许的。）
        IllegalArgumentException - 如果key包含空控制字符，则代码点U + 0000。

      • remove

        public abstract void remove​(String key)
        删除与此首选项节点中指定键关联的值（如果有）。

        如果此实现支持存储的默认值 ，并且指定的首选项存在此类默认值，则此调用将“暴露”存储的默认值，因为它将由后续调用get 。

        参数
        key - 要从首选项节点中删除其映射的密钥。
        异常
        NullPointerException - 如果 key是 null 。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        IllegalArgumentException - 如果key包含空控制字符，则代码点为U + 0000。

      • clear

        public abstract void clear()                    throws BackingStoreException
        删除此首选项节点中的所有首选项（键值关联）。 此调用对此节点的任何后代没有影响。

        如果此实现支持存储的默认值 ，并且首选项层次结构中的此节点包含任何此类默认值，则此调用将“暴露”存储的默认值，因为它们将通过后续调用get返回。

        异常
        BackingStoreException - 如果由于后备存储中的故障或无法与之通信而无法完成此操作。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        另请参见：
        removeNode()

      • getInt

        public abstract int getInt​(String key,                           int def)
        返回与此首选项节点中指定键关联的字符串表示的int值。 该字符串将转换为Integer.parseInt(String)之间的整数。 如果没有与键关联的值，后备存储不可访问，或者如果传递关联值， Integer.parseInt(String)将抛出NumberFormatException，则返回指定的默认值。 此方法旨在与putInt(java.lang.String, int)一起使用。

        如果实现支持存储的默认值并且存在这样的默认值，可以访问，并且可以使用Integer.parseInt转换为int，则优先返回此int，而不是指定的默认值。

        参数
        key - 其关联值将作为int返回的键。
        def - 在此首选项节点没有与 key关联的值的情况下要返回的值，或者关联的值不能解释为int，或者后备存储不可访问。
        结果
        此偏好节点中与 key关联的字符串表示的int值，如果关联值不存在或不能解释为int， def 。
        异常
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        NullPointerException - 如果 key是 null 。
        IllegalArgumentException - 如果key包含空控制字符，则代码点为U + 0000。
        另请参见：
        putInt(String,int) ， get(String,String)

      • getLong

        public abstract long getLong​(String key,                             long def)
        返回与此首选项节点中指定键关联的字符串表示的long值。 该字符串将转换为Long.parseLong(String) 。 如果没有与键关联的值，后备存储不可访问，或者如果传递关联值， Long.parseLong(String)将抛出NumberFormatException，则返回指定的默认值。 此方法旨在与putLong(java.lang.String, long)一起使用。

        如果实现支持存储的默认值并且存在这样的默认值，可以访问，并且可以使用Long.parseLong转换为long， Long.parseLong优先返回此long，而不是指定的默认值。

        参数
        key - 其关联值将作为long返回的键。
        def - 在此首选项节点没有与 key关联的值的情况下要返回的值，或者关联的值不能解释为long，或者后备存储不可访问。
        结果
        此首选项节点中与 key关联的字符串表示的long值，如果关联值不存在或不能解释为long， def 。
        异常
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        NullPointerException - 如果 key是 null 。
        IllegalArgumentException - 如果key包含空控制字符，则代码点为U + 0000。
        另请参见：
        putLong(String,long) ， get(String,String)

      • getBoolean

        public abstract boolean getBoolean​(String key,                                   boolean def)
        返回与此首选项节点中指定键关联的字符串表示的布尔值。 有效字符串为"true" ，表示true， "false" ，表示false。 大小写被忽略，例如， "TRUE"和"False"也是有效的。 此方法旨在与putBoolean(java.lang.String, boolean)一起使用。

        如果没有与键关联的值，后备存储不可访问，或者关联值不是"true"或"false" ，则返回指定的默认值，忽略大小写。

        如果实现支持存储的默认值并且这样的默认值存在且可访问，则优先使用它来指定默认值，除非存储的默认值不是"true"或"false" ，忽略大小写，在这种情况下使用指定的默认值。

        参数
        key - 其关联值将作为布尔值返回的键。
        def - 在此首选项节点没有与 key关联的值的情况下要返回的值，或者关联的值不能解释为布尔值，或者后备存储不可访问。
        结果
        此首选项节点中与 key关联的字符串表示的布尔值，如果关联值不存在或不能解释为布尔值， def 。
        异常
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        NullPointerException - 如果 key是 null 。
        IllegalArgumentException - 如果key包含空控制字符，则代码点为U + 0000。
        另请参见：
        get(String,String) ， putBoolean(String,boolean)

      • getFloat

        public abstract float getFloat​(String key,                               float def)
        返回与此首选项节点中指定键关联的字符串表示的float值。 该字符串将转换为Float.parseFloat(String)之间的整数。 如果没有与键关联的值，后备存储不可访问，或者如果传递关联值， Float.parseFloat(String)将抛出NumberFormatException，则返回指定的默认值。 此方法旨在与putFloat(java.lang.String, float)一起使用。

        如果实现支持存储的默认值并且存在这样的默认值，可以访问，并且可以使用Float.parseFloat转换为浮点数，则优先返回此浮点数以指定默认值。

        参数
        key - 其关联值将作为float返回的键。
        def - 在此首选项节点没有与 key关联的值的情况下要返回的值，或者关联的值不能解释为float，或者后备存储不可访问。
        结果
        此偏好节点中与 key关联的字符串表示的float值，如果关联值不存在或不能解释为float， def 。
        异常
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        NullPointerException - 如果 key是 null 。
        IllegalArgumentException - 如果key包含空控制字符，则代码点为U + 0000。
        另请参见：
        putFloat(String,float) ， get(String,String)

      • getDouble

        public abstract double getDouble​(String key,                                 double def)
        返回与此首选项节点中指定键关联的字符串表示的double值。 该字符串将转换为Double.parseDouble(String)之间的整数。 如果没有与键关联的值，后备存储不可访问，或者如果传递关联值， Double.parseDouble(String)将抛出NumberFormatException，则返回指定的默认值。 此方法旨在与putDouble(java.lang.String, double)一起使用。

        如果实现支持存储的默认值并且存在这样的默认值，可以访问，并且可以使用Double.parseDouble转换为double， Double.parseDouble优先返回此double，而不是指定的默认值。

        参数
        key - 其关联值将作为double返回的键。
        def - 在此首选项节点没有与 key关联的值的情况下要返回的值，或者关联的值不能解释为double，或者后备存储不可访问。
        结果
        此首选项节点中与 key关联的字符串表示的double值，如果关联值不存在或不能解释为double， def 。
        异常
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        NullPointerException - 如果 key是 null 。
        IllegalArgumentException - 如果key包含空控制字符，则代码点为U + 0000。
        另请参见：
        putDouble(String,double) ， get(String,String)

      • putByteArray

        public abstract void putByteArray​(String key,                                  byte[] value)
        将表示指定字节数组的字符串与此首选项节点中的指定键相关联。 关联的字符串是字节数组的Base64编码，如RFC 2045第6.8节中所定义，只有一个小的改动：字符串将仅由Base64字母表中的字符组成; 它不包含任何换行符。 请注意，字节数组的最大长度限制为MAX_VALUE_LENGTH四分之三，因此Base64编码的字符串的长度不超过MAX_VALUE_LENGTH 。 此方法旨在与getByteArray(java.lang.String, byte[])一起使用。
        参数
        key - 与字符串形式的值相关联的键。
        value - 其字符串形式与密钥关联的值。
        异常
        NullPointerException - 如果密钥或值为 null 。
        IllegalArgumentException - 如果key.length（）超过MAX_KEY_LENGTH或者value.length超过MAX_VALUE_LENGTH * 3/4。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        IllegalArgumentException - 如果key包含空控制字符，则代码点为U + 0000。
        另请参见：
        getByteArray(String,byte[]) ， get(String,String)

      • getByteArray

        public abstract byte[] getByteArray​(String key,                                    byte[] def)
        返回由此首选项节点中与指定键关联的字符串表示的字节数组值。 有效字符串是Base64编码的二进制数据，如RFC 2045第6.8节中所定义，只有一个小的改动：字符串必须仅由Base64字母表中的字符组成; 不允许使用换行符或无关字符。 此方法旨在与putByteArray(java.lang.String, byte[])一起使用。

        如果没有与键关联的值，后备存储不可访问，或者关联值不是有效的Base64编码字节数组（如上所述），则返回指定的默认值。

        如果实现支持存储的默认值并且这样的默认值存在且可访问，则优先使用它来指定默认值，除非存储的默认值不是有效的Base64编码字节数组（如上所定义），在这种情况下指定的默认值为用过的。

        参数
        key - 其关联值将作为字节数组返回的键。
        def - 在此首选项节点没有与 key关联的值的情况下要返回的值，或者关联的值不能解释为字节数组，或者后备存储不可访问。
        结果
        此首选项节点中与 key关联的字符串表示的字节数组值，如果关联值不存在或无法解释为字节数组， def 。
        异常
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        NullPointerException - 如果key是null 。 （A null为值def 是允许的。）
        IllegalArgumentException - 如果key包含空控制字符，则代码点为U + 0000。
        另请参见：
        get(String,String) ， putByteArray(String,byte[])

      • keys

        public abstract String[] keys()                       throws BackingStoreException
        返回此首选项节点中具有关联值的所有键。 （如果此节点没有首选项，则返回的数组大小为零。）

        如果实现支持存储的默认值，并且此节点上有任何未被覆盖的默认值，则通过显式首选项，除了任何显式首选项之外，还会在数组中返回默认值。

        结果
        在此首选项节点中具有关联值的键的数组。
        异常
        BackingStoreException - 如果由于后备存储中的故障或无法与其通信而无法完成此操作。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。

      • childrenNames

        public abstract String[] childrenNames()                                throws BackingStoreException
        返回此首选项节点的子节点相对于此节点的名称。 （如果此节点没有子节点，则返回的数组大小为零。）
        结果
        此首选项节点的子节点的名称。
        异常
        BackingStoreException - 如果由于后备存储中的故障或无法与之通信而无法完成此操作。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。

      • parent

        public abstract Preferences parent()
        返回此首选项节点的父节点，如果是根节点，则返回 null 。
        结果
        此首选项节点的父节点。
        异常
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。

      • node

        public abstract Preferences node​(String pathName)
        返回与此节点在同一树中的命名首选项节点，创建它及其任何祖先（如果它们尚不存在）。 接受相对或绝对路径名称。 相对路径名（不以斜杠字符('/') ）将相对于此首选项节点进行解释。

        如果在此调用之前返回的节点不存在，则在返回的节点（或其祖先或后代之一）上调用flush方法之前，不保证此节点和此调用创建的任何祖先都是永久的。

        参数
        pathName - 要返回的首选项节点的路径名。
        结果
        指定的首选项节点。
        异常
        IllegalArgumentException - 如果路径名无效（即，它包含多个连续的斜杠字符，或以斜杠字符结尾且长度超过一个字符）。
        NullPointerException - 如果路径名是 null 。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        另请参见：
        flush()

      • nodeExists

        public abstract boolean nodeExists​(String pathName)                            throws BackingStoreException
        如果指定的首选项节点与此节点位于同一树中，则返回true。 相对路径名称（不以斜杠字符('/') ）相对于此首选项节点进行解释。

        如果已使用removeNode()方法删除此节点（或祖先），则调用此方法是合法的，但仅限于路径名"" ; 调用将返回false 。 因此，成语p.nodeExists("")可用于测试是否已移除p 。

        参数
        pathName - 要检查其存在的节点的路径名。
        结果
        如果指定的节点存在，则为true。
        异常
        BackingStoreException - 如果由于后备存储中的故障或无法与之通信而无法完成此操作。
        IllegalArgumentException - 如果路径名无效（即，它包含多个连续的斜杠字符，或以斜杠字符结尾且长度超过一个字符）。
        NullPointerException - 如果路径名是 null 。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先），并且 pathName不是空字符串（ "" ）。

      • removeNode

        public abstract void removeNode()                         throws BackingStoreException
        删除此首选项节点及其所有后代，从而使已删除节点中包含的任何首选项无效。 一旦节点已被去除，试图比其他任何方法name() ， absolutePath() ， isUserNode() ， flush()或nodeExists("")在相应Preferences实例将失败，并IllegalStateException 。 （在删除之后，仍然可以在节点上调用Object上定义的方法;它们不会抛出IllegalStateException ）

        在此节点（或祖先）上调用flush方法之前，不保证删除是持久的。

        如果此实现支持存储的默认值 ，则删除节点会在此节点或其下方公开任何存储的默认值。 因此，在随后的电话nodeExists在这个节点的路径名称可能会返回true ，以及后续调用node在这个路径名称可能会返回（不同） Preferences代表的偏好和/或儿童的非空的集合实例。

        异常
        BackingStoreException - 如果由于后备存储中的故障或无法与之通信而无法完成此操作。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        UnsupportedOperationException - 如果在根节点上调用此方法。
        另请参见：
        flush()

      • name

        public abstract String name()
        返回此首选项节点相对于其父节点的名称。
        结果
        此首选项节点的名称，相对于其父节点。

      • absolutePath

        public abstract String absolutePath()
        返回此首选项节点的绝对路径名。
        结果
        此首选项节点的绝对路径名称。

      • isUserNode

        public abstract boolean isUserNode()
        返回 true如果此首选项节点位于用户首选项树， false ，如果它在系统首选项树。
        结果
        true如果此首选项节点位于用户首选项树中， false如果它位于系统首选项树中）。

      • toString

        public abstract String toString()
        返回此首选项节点的字符串表示形式，如同通过表达式计算： (this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 。
        重写：
        toString在类 Object
        结果
        对象的字符串表示形式。

      • flush

        public abstract void flush()                    throws BackingStoreException
        强制将此首选项节点及其后代的内容更改为持久性存储。 一旦此方法成功返回，就可以安全地假设在方法调用之前以此节点为根的子树中所做的所有更改都已成为永久更改。

        实现可以随时将更改刷新到持久性存储中。 他们不需要等待调用此方法。

        当在新创建的节点上发生刷新时，它会被持久化，就像任何尚未持久化的祖先（和后代）一样。 但请注意，祖先中的任何首选项值更改都不能保证是持久的。

        如果在使用removeNode()方法删除的节点上调用此方法，则在此节点上调用flushSpi（），但在其他节点上不调用flushSpi（）。

        异常
        BackingStoreException - 如果由于后备存储中的故障或无法与之通信而无法完成此操作。
        另请参见：
        sync()

      • sync

        public abstract void sync()                   throws BackingStoreException
        确保将来从此首选项节点及其后代读取将反映在sync调用之前（从任何VM）提交到持久性存储的任何更改。 作为副作用，强制将此首选项节点及其后代的内容中的任何更改强制到持久性存储，就像在此节点上调用了flush方法一样。
        异常
        BackingStoreException - 如果由于后备存储中的故障或无法与之通信而无法完成此操作。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        另请参见：
        flush()

      • addPreferenceChangeListener

        public abstract void addPreferenceChangeListener​(PreferenceChangeListener pcl)
        注册指定的侦听器以接收此首选项节点的首选项更改事件 。 将首选项添加到此节点，从此节点中删除，或者更改与首选项关联的值时，将生成首选项更改事件。 （偏好改变事件不会由所产生的removeNode()方法，该方法生成事件 。优选变化事件是由所生成的节点改变 clear方法）。

        事件仅保证在与注册的侦听器相同的JVM中进行的更改，但某些实现可能会为在此JVM之外进行的更改生成事件。 可以在更改持久之前生成事件。 在此节点的后代中修改首选项时，不会生成事件; 希望此类事件的来电者必须向每个后代登记。

        参数
        pcl - 要添加的首选项更改侦听器。
        异常
        NullPointerException - 如果 pcl为空。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        另请参见：
        removePreferenceChangeListener(PreferenceChangeListener) ， addNodeChangeListener(NodeChangeListener)

      • addNodeChangeListener

        public abstract void addNodeChangeListener​(NodeChangeListener ncl)
        注册指定的侦听器以接收此节点的节点更改事件 。 将子节点添加到此节点或从中删除子节点时，将生成节点更改事件。 （单个removeNode()调用会导致多个节点更改事件 ，一个用于以已删除节点为根的子树中的每个节点。）

        事件仅保证在与注册的侦听器相同的JVM中进行的更改，但某些实现可能会为在此JVM之外进行的更改生成事件。 可以在更改成为永久更改之前生成事件。 添加或删除此节点的间接后代时，不会生成事件; 希望此类事件的来电者必须向每个后代登记。

        关于节点创建，几乎没有保证。 由于节点是在访问时隐式创建的，因此实现在访问之前确定子节点是否存在于后备存储中可能是不可行的（例如，因为后备存储无法访问或缓存信息已过期）。 在这些情况下，实现既不需要生成节点更改事件也不禁止这样做。

        参数
        ncl - 要添加的 NodeChangeListener 。
        异常
        NullPointerException - 如果 ncl为空。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        另请参见：
        removeNodeChangeListener(NodeChangeListener) ， addPreferenceChangeListener(PreferenceChangeListener)

      • exportNode

        public abstract void exportNode​(OutputStream os)                         throws IOException,                                BackingStoreException
        在指定的输出流上发出一个XML文档，表示此节点中包含的所有首选项（但不包括其后代）。 实际上，此XML文档是节点的脱机备份。

        XML文档将具有以下DOCTYPE声明： 

           <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
        将使用UTF-8字符编码。

        此方法是一般规则的一个例外，即在此类中并发执行多个方法的结果会产生与某些串行执行相当的结果。 如果在调用此方法的同时修改此节点的首选项，则导出的首选项包含节点中包含的首选项的“模糊快照”; 某些并发修改可能会反映在导出的数据中，而其他修改可能不会。

        参数
        os - 要在其上发出XML文档的输出流。
        异常
        IOException - 如果写入指定的输出流，则会产生 IOException 。
        BackingStoreException - 如果无法从后备存储中读取首选项数据。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        另请参见：
        importPreferences(InputStream)

      • exportSubtree

        public abstract void exportSubtree​(OutputStream os)                            throws IOException,                                   BackingStoreException
        发出一个XML文档，表示此节点及其所有后代中包含的所有首选项。 实际上，此XML文档是以节点为根的子树的脱机备份。

        XML文档将具有以下DOCTYPE声明： 

           <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
        将使用UTF-8字符编码。

        此方法是一般规则的一个例外，即在此类中并发执行多个方法的结果会产生与某些串行执行相当的结果。 如果以此方法的调用同时修改以此节点为根的子树中的首选项或节点，则导出的首选项包括子树的“模糊快照”; 某些并发修改可能会反映在导出的数据中，而其他修改可能不会。

        参数
        os - 要在其上发出XML文档的输出流。
        异常
        IOException - 如果写入指定的输出流，则会产生 IOException 。
        BackingStoreException - 如果无法从后备存储读取首选项数据。
        IllegalStateException - 如果已使用 removeNode()方法删除此节点（或祖先）。
        另请参见：
        importPreferences(InputStream) ， exportNode(OutputStream)

      • importPreferences

        public static void importPreferences​(InputStream is)                              throws IOException,                                     InvalidPreferencesFormatException
        在指定的输入流上导入XML文档表示的所有首选项。 该文档可以表示用户偏好或系统偏好。 如果它表示用户首选项，则首选项将导入到主叫用户的首选项树中（即使它们最初来自不同用户的首选项树）。 如果文档描述的任何首选项存在于不存在的首选节点中，则将创建节点。

        XML文档必须具有以下DOCTYPE声明： 

           <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
        （此方法旨在与exportNode(OutputStream)和exportSubtree(OutputStream)一起使用。

        此方法是一般规则的一个例外，即在此类中并发执行多个方法的结果会产生与某些串行执行相当的结果。 该方法的行为就像在此类中的其他公共方法之上实现，特别是node(String)和put(String, String) 。

        参数
        is - 从中读取XML文档的输入流。
        异常
        IOException - 如果从指定的输入流读取，则会产生 IOException 。
        InvalidPreferencesFormatException - 有关输入流的数据不构成具有强制文档类型的有效XML文档。
        SecurityException - 如果存在安全管理器且它拒绝 RuntimePermission("preferences") 。
        另请参见：
        RuntimePermission