Module  java.prefs
软件包  java.util.prefs

Class Preferences

  • 已知直接子类：
    AbstractPreferences 

    public abstract class Preferences
extends Object
    优先级数据的分层收集中的节点。 该类允许应用程序存储和检索用户和系统首选项和配置数据。 该数据永久存储在实现相关的后备存储中。 典型的实现包括平面文件，特定于OS的注册表，目录服务器和SQL数据库。 该类的用户不需要关注后备存储的细节。

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

    优先树中的节点以类似于分层文件系统中的目录的方式命名。 在首选项树的每个节点都具有节点名称 （这不一定是唯一的），唯一的绝对路径名 ，并且相对于每个祖先的路径名，包括本身。

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

    根节点的绝对路径名为"/" 。 根节点的子节点的绝对路径名为"/" + <node name> 。 所有其他节点的绝对路径名称为<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实现类文件已经被安装在一个jar文件，它是可见的system class loader ，以及jar文件包含一个名为供应商的配置文件java.util.prefs.PreferencesFactory在资源目录META-INF/services ，然后在该文件中指定的第一个类名称取。 如果提供了多个这样的jar文件，那么将使用第一个。 该类被加载和实例化; 如果此过程失败，则抛出未指定的错误。

    3. 最后，如果既不提供上述系统属性也不提供扩展jar文件，则会为基础平台的系统级默认PreferencesFactory实现加载和实例化。

    从以下版本开始：
    1.4

    • Field Summary

      Fields  
      Modifier and Type Field 描述
      static int MAX_KEY_LENGTH
      字符串允许的最大长度（80个字符）。
      static int MAX_NAME_LENGTH
      节点名称的最大长度（80个字符）。
      static int MAX_VALUE_LENGTH
      字符串的最大长度允许为一个值（8192个字符）。

    • 构造方法摘要

      构造方法  
      Modifier Constructor 描述
      protected Preferences​()
      唯一的构造函数。

    • 方法摘要

      所有方法  静态方法  接口方法  抽象方法  具体的方法 
      Modifier and Type 方法 描述
      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)
      返回由此首选项节点中与指定键相关联的字符串表示的双精度值。
      abstract float getFloat​(String key, float def)
      返回由此首选项节点中与指定键相关联的字符串表示的浮点值。
      abstract int getInt​(String key, int def)
      返回由此首选项节点中与指定键相关联的字符串表示的int值。
      abstract long getLong​(String key, long def)
      返回由此首选项节点中与指定键相关联的字符串表示的长整型值。
      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)
      将表示指定双重值的字符串与此首选项节点中指定的键相关联。
      abstract void putFloat​(String key, float value)
      将表示指定浮点值的字符串与此首选项节点中指定的键相关联。
      abstract void putInt​(String key, int value)
      将表示指定int值的字符串与此首选项节点中的指定键相关联。
      abstract void putLong​(String key, long value)
      将表示指定长值的字符串与此首选项节点中指定的键相关联。
      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​(Class<?> c)
      从与指定类的包关联（按照约定）的系统首选项树返回首选项节点。
      static Preferences systemRoot​()
      返回系统的根首选项节点。
      abstract String toString​()
      返回此首选项节点的字符串表示形式，如同由以下表达式计算： (this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 。
      static Preferences userNodeForPackage​(Class<?> c)
      从调用用户的偏好树中返回偏好节点，该树通过指定的类的包（与约定）相关联。
      static Preferences userRoot​()
      返回主叫用户的根优先级节点。

    • 字段详细信息

      • MAX_KEY_LENGTH

        public static final int MAX_KEY_LENGTH
        字符串允许的最大长度（80个字符）。
        另请参见：
        Constant Field Values

      • MAX_VALUE_LENGTH

        public static final int MAX_VALUE_LENGTH
        字符串的最大长度允许为一个值（8192个字符）。
        另请参见：
        Constant Field Values

      • MAX_NAME_LENGTH

        public static final int MAX_NAME_LENGTH
        节点名称的最大长度（80个字符）。
        另请参见：
        Constant Field Values

    • 构造方法详细信息

      • Preferences

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

    • 方法详细信息

      • userNodeForPackage

        public static Preferences userNodeForPackage​(Class<?> 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​(Class<?> 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 - 如果键包含空控制字符，则代码点U + 0000。

      • remove

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

        如果此实现支持存储的默认值 ，并且对于指定的首选项具有这样的默认值，则由此呼叫将存储的默认值“暴露”，因为它将由后续调用返回get 。

        参数
        key - 要从偏好节点删除其映射的密钥。
        异常
        NullPointerException - 如果 key是 null 。
        IllegalStateException - 如果此节点（或祖先）已使用 removeNode()方法删除。
        IllegalArgumentException - 如果键包含空控制字符，则代码点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 - 如果键包含空控制字符，则代码点U + 0000。
        另请参见：
        putInt(String,int) ， get(String,String)

      • getLong

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

        如果实现支持存储的默认值，并且这样的默认值是可以访问的，并且可以使用Long.parseLong转换为long，这个长度优先于指定的默认值。

        参数
        key - 其关联值将作为长期返回的键。
        def - 如果此首选项节点没有与 key相关联的值或相关联的值不能被解释为长时间或后备存储无法访问，则返回值。
        结果
        由此偏好节点中与 key相关联的字符串表示的长值，如果相关联的值不存在或不能解释为长， def 。
        异常
        IllegalStateException - 如果此节点（或祖先）已使用 removeNode()方法删除。
        NullPointerException - 如果 key是 null 。
        IllegalArgumentException - 如果键包含空控制字符，则代码点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 - 如果键包含空值控制字符，则代码点U + 0000。
        另请参见：
        get(String,String) ， putBoolean(String,boolean)

      • getFloat

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

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

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

      • getDouble

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

        如果实现支持存储的默认值，并且这样的默认值存在，则可以访问，并且可以使用Double.parseDouble将其转换为双Double.parseDouble ，这个double值优先于指定的默认值。

        参数
        key - 其关联值将作为双重返回的键。
        def - 如果此首选项节点没有与 key相关联的值或相关联的值不能被解释为双 key值，或后备存储不可访问，则返回值。
        结果
        由此偏好节点中与 key相关联的字符串表示的双 def值，如果关联值不存在或不能解释为双 def值， def 。
        异常
        IllegalStateException - 如果此节点（或祖先）已使用 removeNode()方法删除。
        NullPointerException - 如果 key是 null 。
        IllegalArgumentException - 如果键包含空控制字符，则代码点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四分之三， 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 - 如果键包含空控制字符，则代码点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 - 如果键包含空控制字符，则代码点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（），但不调用其他节点。

        异常
        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