当前页面: 在线文档首页 > JavaTM 2 Platform Standard Edition 5.0 API 规范中文版

Preferences (Java 2 Platform SE 5.0) - JavaTM 2 Platform Standard Edition 5.0 API 规范中文版

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM 2 Platform Standard Ed. 5.0
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

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">
 

注意，导入或导出首选项时不 访问系统 URI (http://java.sun.com/dtd/preferences.dtd)；该系统 URI 仅作为一个惟一标识 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 实现。每个 J2SE 实现都必须提供一些方式，来指定将哪个 PreferencesFactory 实现用于生成根首选项节点。这允许管理员使用替代实现替换默认首选项实现。

实现注意事项：在 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

---

字段摘要
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)           返回与此首选项节点中指定的键相关联的、由字符串表示的 boolean 值。
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)           将表示指定 boolean 值的字符串与此首选项节点中的指定键相关联。
abstract  void	putByteArray(String key, byte[] value)           将表示指定字节数组的字符串与此首选项节点中的指定键相关联。
abstract  void	putDouble(String key, double value)           将表示指定 double 值的字符串与此首选项节点中的指定键相关联。
abstract  void	putFloat(String key, float value)           将表示指定 float 值的字符串与此首选项节点中的指定键相关联。
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(Class<?> c)           从系统首选项树（根据约定，它与指定类的包相关联）返回首选项节点。
static Preferences	systemRoot()           返回系统的根首选项节点。
abstract  String	toString()           返回此首选项节点的字符串表示形式，与通过表达式：(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 计算的结果一样。
static Preferences	userNodeForPackage(Class<?> c)           从调用用户首选项树（根据约定，它与指定类的包相关联）返回首选项节点。
static Preferences	userRoot()           返回调用用户的根首选项节点。

 

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

 

字段详细信息

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 关联的节点绝对路径名是 /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 关联的节点绝对路径名是 /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() 方法移除了此节点（或其祖先）。

NullPointerException - 如果 key 为 null。

另请参见：

get(String,String), putBoolean(String,boolean)

---

putFloat

public abstract void putFloat(String key,
                              float value)

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

参数：

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

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

抛出：

NullPointerException - 如果 key 为 null。

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

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

另请参见：

getFloat(String,float)

---

getFloat

public abstract float getFloat(String key,
                               float def)

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

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

参数：

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

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

返回：

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

抛出：

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

NullPointerException - 如果 key 为 null。

另请参见：

putFloat(String,float), get(String,String)

---

putDouble

public abstract void putDouble(String key,
                               double value)

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

参数：

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

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

抛出：

NullPointerException - 如果 key 为 null。

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

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

另请参见：

getDouble(String,double)

---

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（而不是指定默认值）。

参数：

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

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

返回：

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

抛出：

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

NullPointerException - 如果 key 为 null。

另请参见：

putDouble(String,double), get(String,String)

---

putByteArray

public abstract void putByteArray(String key,
                                  byte[] value)

将表示指定字节数组的字符串与此首选项节点中的指定键相关联。正如 RFC 2045，第 6.8 节中定义的那样，该关联字符串是 Base64 编码的字节数组，其中有一处小的改动：该字符串仅由 Base64 Alphabet 中的字符构成；它不包含任何新行符。注意，该字节数组的最大长度限制是 MAX_VALUE_LENGTH 的四分之三，因此，Base64 编码的 String 的长度不能超过 MAX_VALUE_LENGTH。此方法与 getByteArray(java.lang.String, byte[]) 一起使用。

参数：

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

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

抛出：

NullPointerException - 如果 key 或 value 为 null。

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

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

另请参见：

getByteArray(String,byte[]), get(String,String)

---

getByteArray

public abstract byte[] getByteArray(String key,
                                    byte[] def)

返回与此首选项节点中指定键相关联的、由字符串表示的字节数组。正如 RFC 2045，第 6.8 节中定义的那样，有效的字符串是 Base64 编码的二进制数据，其中有一处小的改动：该字符串必须仅包含 Base64 Alphabet 中的字符；不允许使用任何新行符或额外字符。此方法与 putByteArray(java.lang.String, byte[]) 一起使用。

如果没有与该键相关联的值或者内部存储不可访问或者关联值不是有效的 Base64 编码字节数组（根据上面的定义），则返回指定默认值。

如果该实现支持存储的默认值，这样的默认值存在且可访问，则优先使用存储的默认值（而不是指定默认值）；但如果存储的默认值不是有效的 Base64 编码的字节数组（根据上面的定义），在这种情况下，则使用指定默认值。

参数：

key - 要作为字节数组返回其关联值的键。

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

返回：

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

抛出：

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

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

另请参见：

get(String,String), putByteArray(String,byte[])

---

keys

public abstract String[] keys()
                       throws BackingStoreException

返回在此首选项节点中具有关联值的所有键。（如果此节点不具有任何首选项，则返回数组的大小将为 0。）

如果该实现支持存储的默认值，此节点中存在这样的默认值并且没有被显式首选项重写，则在数组中除了返回所有显式首选项外，还返回默认值。

返回：

在此首选项节点中具有关联值的键数组。

抛出：

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

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

---

childrenNames

public abstract String[] childrenNames()
                                throws BackingStoreException

返回此首选项节点相对于此节点的子节点名称。（如果此节点不具有任何子节点，则返回数组的大小将为 0。）

返回：

此首选项节点的子节点名称。

抛出：

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

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

---

parent

public abstract Preferences parent()

返回此首选项节点的父节点；如果此为根，则返回 null。

返回：

首选项节点的父节点。

抛出：

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

---

node

public abstract Preferences node(String pathName)

将指定首选项节点返回到此节点所在的同一树中，如果此节点及其祖先已经不存在，则创建它们。接受相对或绝对路径名。相对路径名（不以斜杠字符 ('/') 开头）是相对于此首选项节点解释的。

如果在此调用之前返回的节点不存在，那么在对返回节点（或者其某个祖先或子节点）调用 flush 方法之前，不能保证由此调用所创建的节点及其所有祖先是永久性的。

参数：

pathName - 要返回的首选项节点的路径名。

返回：

指定的首选项节点。

抛出：

IllegalArgumentException - 如果路径名无效（即它包含多个连续的斜杠字符，或者以斜杠字符结束并且大于一个 long 字符）。

NullPointerException - 如果路径名为 null。

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

另请参见：

flush()

---

nodeExists

public abstract boolean nodeExists(String pathName)
                            throws BackingStoreException

如果此节点所在的树中存在指定首选项节点，则返回 true。相对路径名（不以斜杠字符 ('/') 开头）是相对于此首选项节点解释的。

如果已经使用 removeNode() 方法移除了此节点（及其祖先），则调用此方法也是 合法的，只是需要使用路径名 ""；该调用返回 false。因此，可以使用语句 p.nodeExists("") 测试 p 是否已被移除。

参数：

pathName - 要检查其是否存在的节点路径名。

返回：

如果指定的节点存在，则返回 true。

抛出：

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

IllegalArgumentException - 如果路径名无效（即它包含多个连续的斜杠字符，或者以斜杠字符结束并且大于一个 long 字符）。

NullPointerException - 如果路径名为 null。

IllegalStateException - 如果已经使用 removeNode() 方法移除了此节点（或其祖先），并且 pathName 不是空字符串 ("")。

---

removeNode

public abstract void removeNode()
                         throws BackingStoreException

移除此首选项节点及其所有子节点，移除的节点中所包含的全部首选项都将失效。节点被移除后，针对相应 Preferences 实例尝试使用 name()、absolutePath()、isUserNode()、flush() 或 nodeExists("") 之外的任何方法都将失败并抛出 IllegalStateException。（节点被移除后，在该节点上仍然可以调用在 Object 上定义的方法，并且不抛出 IllegalStateException。）

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

如果此实现支持存储的默认值，则移除节点将公开此节点的或此节点下的所有存储的默认值。因此，对此节点的路径名后续调用 nodeExists 将返回 true，而对此路径名后续调用 node 则返回表示首选项和/或子首选项的非空 collection 的（不同）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() 计算的结果一样。

覆盖：

类 Object 中的 toString

返回：

该对象的字符串表示形式。

---

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 为 null。

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

另请参见：

removePreferenceChangeListener(PreferenceChangeListener), addNodeChangeListener(NodeChangeListener)

---

removePreferenceChangeListener

public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)

移除指定首选项更改侦听器，使其不再接收首选项更改事件。

参数：

pcl - 要移除的首选项更改侦听器。

抛出：

IllegalArgumentException - 如果 pcl 不是此节点上的已注册首选项更改侦听器。

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

另请参见：

addPreferenceChangeListener(PreferenceChangeListener)

---

addNodeChangeListener

public abstract void addNodeChangeListener(NodeChangeListener ncl)

注册指定侦听器以接收此节点的节点更改事件。在此节点中添加或删除子节点时，将生成节点更改事件。（单个 removeNode() 调用即可产生多个节点更改事件，每个都对应于以已移除节点为根的子树中的一个节点。）

尽管有些实现可以为在 JVM 外进行的更改生成事件，但只有在注册侦听器所在的 JVM 中所作的更改才能得到保证。事件可能是更改变得持久之前生成的。添加或移除此节点的间接子节点时不生成事件；需要此类事件的调用方必须在每个子节点中注册。

节点的创建难以得到保证。因为节点是基于访问隐式创建的，实现无法确定访问前内部存储中是否存在子节点（例如，内部存储不可访问或已缓存信息过期）。在这些情形下，实现既不要求生成节点更改事件也不禁止这样做。

参数：

ncl - 要添加的 NodeChangeListener。

抛出：

NullPointerException - 如果 ncl 为 null。

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

另请参见：

removeNodeChangeListener(NodeChangeListener), addPreferenceChangeListener(PreferenceChangeListener)

---

removeNodeChangeListener

public abstract void removeNodeChangeListener(NodeChangeListener ncl)

移除指定 NodeChangeListener，使其不再接收更改事件。

参数：

ncl - 要移除的 NodeChangeListener。

抛出：

IllegalArgumentException - 如果 ncl 不是此节点上的已注册 NodeChangeListener。

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

另请参见：

addNodeChangeListener(NodeChangeListener)

---

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

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM 2 Platform Standard Ed. 5.0
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。