java.util.prefs
类 Preferences

java.lang.Object
  java.util.prefs.Preferences

直接已知子类：

AbstractPreferences

public abstract class Preferences
     

      extends 
      Object
     

首选项数据的层次结构 collection 中的节点。此类允许应用程序存储和获取用户和系统首选项以及配置数据。此数据持久存储在依赖于实现的内部存储中。典型实现包括纯文本文件、特定于操作系统的注册表、目录服务器和 SQL 数据库。此类的用户无需关注内部存储的细节。

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

使用类似的方式将首选项树中的节点命名为层次结构文件系统中的目录。首选项树的每个节点都具有一个节点名（不必是唯一的）、一个唯一的绝对路径名 和一个相对于 每个祖先（包括它自己）的路径名。

根节点的节点名为空字符串 ("")。每个其他节点的节点名可以在创建时任意指定。此名称的唯一限制是，它不能是空字符串，也不能包含斜杠字符 ('/')。

根节点的绝对路径名为 "/"。根节点的子节点的绝对路径名是 "/" + <节点名>。所有其他节点的绝对路径名是<父节点的绝对路径名> + "/" + <节点名>。注意，所有绝对路径名的第一个字符都是斜杠。

节点 n 相对于其祖先 a 的路径名只是为了形成 n 的绝对路径名，而必须添加到 a 的绝对路径名的字符串，同时移除开头的斜杠字符（如果存在）。注意：

• 任何相对路径名的第一个字符都不能是斜杠。
• 每个节点相对于自身的路径名都是空字符串。
• 每个节点相对于父节点的路径名就是其节点名（根节点除外，因为它没有父节点）。
• 每个节点相对于根的路径名都是其移除开头斜杠的绝对路径名。

最后注意：

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

修改首选项数据的所有方法都允许进行异步操作；它们可能立即返回，但是更改最终将传播到持久内部存储中，其延迟取决于实现。可以使用 flush 方法同步地将更新强制同步到内部存储中。Java 虚拟机的正常终止不会 导致挂起更新的丢失，即在终止时不 需要进行显式 flush 调用来使挂起更新变得持久。

从 Preferences 对象读取首选项的所有方法都要求调用者提供一个默认值。如果以前没有设置任何值或者内部存储不可用，则会返回默认值。此默认值的目的是，即使内部存储不可用，应用程序也可以运行，只是功能稍微下降一点。在内部存储不可用的情况下，多个方法（如 flush）均包含阻止应用程序操作的语义。普通应用程序不必调用这些方法中的任何一个，它们可能以抛出 BackingStoreException 而告终。

单个 JVM 中的多个线程可以同时调用此类中的方法，无需进行外部同步，其结果等效于某些顺序执行。如果在同一个内部存储中存储其首选项数据的多个 JVM 同时使用此类，则数据存储也不会遭到破坏，但首选项数据的一致性难以得到保证。

此类包含导出/导入设施，允许将首选项“导出”到 XML 文档，将表示首选项的 XML 文档再“导入”回系统。可以使用此设施备份全部或部分首选项树，并在以后从备份中还原。

XML 文档具有以下 DOCTYPE 声明：

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.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 >
 

实现注意事项：在 Sun 的 JRE 中，PreferencesFactory 实现的位置如下：

1. 如果定义了系统属性 java.util.prefs.PreferencesFactory，则该属性名就会用作实现 PreferencesFactory 接口的类的完全限定名。加载并实例化该类；如果此进程失败，则抛出未指定的错误。

2. 如果在对系统类加载器可见的 jar 文件中安装了 PreferencesFactory 实现类文件，并且该 jar 文件在资源目录 META-INF/services 中包含名为 java.util.prefs.PreferencesFactory 的提供者配置文件，则采用在该文件中指定的第一个类名称。如果提供了一个以上这样的 jar 文件，则使用找到的第一个文件。加载并实例化该类；如果此进程失败，则抛出未指定的错误。

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

从以下版本开始：

1.4

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(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 将要关联的键。

value - 指定的 key 将要关联的值。

抛出：

NullPointerException - 如果 key 或 value 为 null。

IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH 或者 value.length 超过 MAX_VALUE_LENGTH。

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。

get

public abstract String get(String key,
                           String def)

返回与此首选项节点中指定键相关联的值。如果不存在与该键相关联的值或者内部存储不可访问，则返回指定的默认值。

有些实现可能将默认值存储在其内部存储中。如果不存在与指定键相关联的值，而只有存储的默认值，则系统优先返回存储的默认值（而不是指定的默认值）。

参数：

key - 要返回其相关值的键。

def - 此首选项节点不具有与 key 相关联的值时所要返回的值。

返回：

与 key 相关联的值；如果没有与 key 相关联的值或者内部存储不可用，则返回 def。

抛出：

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。

NullPointerException - 如果 key 为 null。（值 null 用于 def 是 允许的。）

remove

public abstract void remove(String key)

移除与此首选项节点中与指定键相关联的值（如果有）。

如果此实现支持存储的默认值，并且指定的首选项存在这样的默认值，则此调用将“公开”存储的默认值，这表示对 get 的后续调用将返回它。

参数：

key - 从首选项节点中移除其映射关系的键。

抛出：

NullPointerException - 如果 key 为 null。

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。

clear

public abstract void clear()
                    throws BackingStoreException

移除此首选项节点中的所有首选项（键-值关联）。此调用对此节点的所有子节点均没有影响。

如果此实现支持存储的默认值，并且首选项层次结构中的这一节点包含这样的默认值，则此调用将“公开”存储的默认值，这表示对 get 的后续调用将返回它。

抛出：

BackingStoreException - 如果由于内部存储的故障或未能通信而无法完成此操作。

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。

另请参见：

removeNode()

putInt

public abstract void putInt(String key,
                            int value)

将表示指定 int 值的字符串与此首选项节点中的指定键相关联。关联字符串是将 int 值传递给 Integer.toString(int) 时将返回的字符串。此方法与 getInt(java.lang.String, int) 一起使用。

参数：

key - 要与字符串形式的 value 相关联的键。

value - 要与 key 相关联的字符串形式的值。

抛出：

NullPointerException - 如果 key 为 null。

IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH。

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。

另请参见：

getInt(String,int)

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。

另请参见：

putInt(String,int), get(String,String)

putLong

public abstract void putLong(String key,
                             long value)

将表示指定 long 值的字符串与此首选项节点中的指定键相关联。关联字符串是将 long 值传递给 Long.toString(long) 时将返回的字符串。此方法与 getLong(java.lang.String, long) 一起使用。

参数：

key - 要与字符串形式的 value 相关联的键。

value - 要与 key 相关联的字符串形式的值。

抛出：

NullPointerException - 如果 key 为 null。

IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH。

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。

另请参见：

getLong(String,long)

getLong

public abstract long getLong(String key,
                             long def)

返回与此首选项节点中指定的键相关联的、由字符串表示的 long 值。该字符串由 Long.parseLong(String) 转换为 long。如果不存在与该键相关联的值，内部存储不可用，或者传递关联值时 Long.parseLong(String) 抛出 NumberFormatException，则返回指定的默认值。此方法与 putLong(java.lang.String, long) 一起使用。

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

参数：

key - 要作为 long 返回其关联值的键。

def - 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为 long 或者内部存储不可访问时要返回的值。

返回：

返回与此首选项节点的 key 相关联的字符串所表示的 long 值；如果关联值不存在或者无法将其解释为 long，则返回 def。

抛出：

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。

NullPointerException - 如果 key 为 null。

另请参见：

putLong(String,long), get(String,String)

putBoolean

public abstract void putBoolean(String key,
                                boolean value)

将表示指定 boolean 值的字符串与此首选项节点中的指定键相关联。如果该值为 true，则关联字符串为 "true"；如果其为 false，则关联字符串为 "false"。此方法与 getBoolean(java.lang.String, boolean) 一起使用。

参数：

key - 要与字符串形式的 value 相关联的键。

value - 要与 key 相关联的字符串形式的值。

抛出：

NullPointerException - 如果 key 为 null。

IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH。

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。

另请参见：

getBoolean(String,boolean), get(String,String)

getBoolean

public abstract boolean getBoolean(String key,
                                   boolean def)

返回与此首选项节点中指定的键相关联的、由字符串表示的 boolean 值。有效字符串是 "true"（表示真）和 "false"（表示假）。不区分大小写，例如， "TRUE" 和 "False" 也是有效的。此方法与 putBoolean(java.lang.String, boolean) 一起使用。

如果不存在与该键相关联的值或者内部存储不可访问或者关联值是 "true" 或 "false"（不区分大小写）之外的其他值，则返回指定默认值。

如果该实现支持存储的默认值，这样的默认值存在且可访问，则优先使用存储的默认值（而不是指定默认值）；但如果存储的默认值是 "true" 或 "false"（不区分大小写）之外的其他值，在这种情况下，则使用指定默认值。

参数：

key - 要作为 boolean 返回其关联值的键。

def - 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为 boolean 或者内部存储不可访问时要返回的值。

返回：

与此首选项节点的 key 相关联的字符串所表示的 boolean 值；如果该关联值不存在或无法被解释为 boolean，则返回 def。

抛出：

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先）。