|
|||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | ||||||||
java.util.prefs
类 Preferences
java.lang.Objectjava.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 实现的位置如下：
如果定义了系统属性 java.util.prefs.PreferencesFactory，则该属性名就会用作实现 PreferencesFactory 接口的类的完全限定名。加载并实例化该类；如果此进程失败，则抛出未指定的错误。
如果在对
系统类加载器可见的 jar 文件中安装了 PreferencesFactory 实现类文件，并且该 jar 文件在资源目录 META-INF/services 中包含名为 java.util.prefs.PreferencesFactory 的提供程序配置文件，则采用在该文件中指定的第一个类名称。如果提供了一个以上这样的 jar 文件，则使用找到的第一个文件。加载并实例化该类；如果此进程失败，则抛出未指定的错误。最后，如果既没有提供上述系统属性也没有提供扩展 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()方法移除了此节点（或其祖先）。
