- 直接已知的子类:
-
AbstractPreferences
有两个独立的首选项节点树，一个用于用户首选项，一个用于系统首选项。每个用户都有一个单独的用户首选项树，给定系统中的所有用户共享相同的系统首选项树。"用户"和"系统"的确切描述将因实现而异。存储在用户首选项树中的典型信息可能包括特定应用程序的字体选择、颜色选择或首选窗口位置和大小。存储在系统首选项树中的典型信息可能包括应用程序的安装配置数据。
首选项树中的节点的命名方式类似于层次文件系统中的目录。首选项树中的每个节点都有一个节点名称（不一定是唯一的）、一个唯一的绝对路径名称和相对于每个祖先（包括自身）的路径名称。
根节点的节点名称为空字符串("")。其他每个节点都有一个在创建时指定的任意节点名称。对此名称的唯一限制是它不能是空字符串，也不能包含斜杠字符('/')。
根节点的绝对路径名称为"/"。根节点的子节点的绝对路径名称为"/" + <节点名称>。所有其他节点的绝对路径名称为<父节点的绝对路径名称> + "/" + <节点名称>。请注意，所有绝对路径名称都以斜杠字符开头。
节点n相对于其祖先a的路径名称简单地是必须附加到a的绝对路径名称以形成n的绝对路径名称的字符串，如果存在初始斜杠字符，则将其删除。请注意:
- 没有相对路径名称以斜杠字符开头。
- 每个节点相对于自身的路径名称为空字符串。
- 每个节点相对于其父节点的路径名称是其节点名称（根节点除外，根节点没有父节点）。
- 每个节点相对于根节点的路径名称是其绝对路径名称，初始斜杠字符被删除。
最后请注意:
- 没有路径名称包含多个连续的斜杠字符。
- 除了根的绝对路径名称外，没有路径名称以斜杠字符结尾。
- 符合这两个规则的任何字符串都是有效的路径名称。
所有修改首选项数据的方法都允许异步操作；它们可能会立即返回，并且更改将以实现相关的延迟最终传播到持久后备存储。可以使用flush方法同步强制更新到后备存储。Java虚拟机的正常终止不会导致待处理更新的丢失——在终止时不需要显式调用flush以确保待处理更新持久化。
从Preferences对象读取首选项的所有方法都要求调用者提供默认值。如果之前未设置值或后备存储不可用，则返回默认值。意图是允许应用程序在后备存储不可用时仍能运行，尽管功能略有降级。一些方法，如flush，具有语义，如果后备存储不可用，则无法操作。普通应用程序不应该需要调用这些方法，可以通过它们声明将抛出BackingStoreException来识别这些方法。
此类中的方法可以由单个JVM中的多个线程并发调用，无需外部同步，结果将等效于某些串行执行。如果此类被多个JVM并发使用，这些JVM将其首选项数据存储在相同的后备存储中，数据存储将不会损坏，但不保证首选项数据的一致性。
此类包含导出/导入功能，允许将首选项"导出"到XML文档，并将表示首选项的XML文档"导入"回系统。此功能可用于备份首选项树的全部或部分内容，并随后从备份中恢复。
XML文档具有以下DOCTYPE声明:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<!-- 用于首选项树的DTD。 -->
<!-- preferences元素位于表示首选项树的XML文档的根部。 -->
<!ELEMENT preferences (root)>
<!-- preferences元素包含一个可选的version属性，指定DTD的版本。 -->
<!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" >
<!-- 根元素具有表示根首选项（如果有）的映射，以及每个子节点的一个节点（如果有）。 -->
<!ELEMENT root (map, node*) >
<!-- 此外，根包含一个type属性，指定它是系统根还是用户根。 -->
<!ATTLIST root
type (system|user) #REQUIRED >
<!-- 每个节点具有表示其首选项（如果有）的映射，以及每个子节点（如果有）。 -->
<!ELEMENT node (map, node*) >
<!-- 此外，每个节点具有一个name属性 -->
<!ATTLIST node
name CDATA #REQUIRED >
<!-- 映射表示存储在节点中的首选项（如果有）。 -->
<!ELEMENT map (entry*) >
<!-- 条目表示一个简单的键-值对首选项。 -->
<!ELEMENT entry EMPTY >
<!ATTLIST entry
key CDATA #REQUIRED
value CDATA #REQUIRED >
Preferences实现必须有一个关联的PreferencesFactory实现。每个Java(TM) SE实现必须提供某种方式来指定用于生成根首选项节点的PreferencesFactory实现。这允许管理员用替代实现替换默认首选项实现。
- 实现注意:
-
PreferencesFactory实现的位置如下:-
如果定义了系统属性
java.util.prefs.PreferencesFactory，则将其视为实现PreferencesFactory接口的类的完全限定名称。加载并实例化该类；如果此过程失败，则会抛出未指定的错误。 -
如果已在对
系统类加载器可见的jar文件中安装了PreferencesFactory实现类文件，并且该jar文件包含一个名为java.util.prefs.PreferencesFactory的提供程序配置文件，位于资源目录META-INF/services中，则将采用该文件中指定的第一个类名。如果提供了多个此类jar文件，则将使用找到的第一个。加载并实例化该类；如果此过程失败，则会抛出未指定的错误。 -
最后，如果既未提供上述系统属性，也未提供扩展jar文件，则将加载和实例化基础平台的系统默认
PreferencesFactory实现。
-
- 自版本:
- 1.4
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int键的最大长度（80个字符）。static final int节点名称的最大长度（80个字符）。static final int值的最大长度（8192个字符）。 -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract String返回此首选项节点的绝对路径名称。abstract void注册指定的侦听器以接收此节点的节点更改事件。abstract void注册指定的侦听器以接收此首选项节点的首选项更改事件。abstract String[]返回此首选项节点的子节点名称，相对于此节点。abstract voidclear()删除此首选项节点中的所有首选项（键-值关联）。abstract void在指定的输出流上发出表示此节点中包含的所有首选项的XML文档（但不包括其后代）。abstract void发出表示此节点及其所有后代中包含的所有首选项的XML文档。abstract voidflush()强制将此首选项节点及其后代内容的任何更改传递到持久存储。abstract String返回与此首选项节点中指定键关联的值。abstract booleangetBoolean(String key, boolean def) 返回与此首选项节点中指定键关联的字符串表示的布尔值。abstract byte[]getByteArray(String key, byte[] def) 返回与此首选项节点中指定键关联的字符串表示的字节数组值。abstract double返回与此首选项节点中指定键关联的字符串表示的双精度值。abstract float返回与此首选项节点中指定键关联的字符串表示的浮点值。abstract int返回与此首选项节点中指定键关联的字符串表示的整数值。abstract long返回与此首选项节点中指定键关联的字符串表示的长整数值。static void导入由指定输入流上的XML文档表示的所有首选项。abstract boolean如果此首选项节点在用户首选项树中，则返回true，如果在系统首选项树中，则返回false。abstract String[]keys()返回在此首选项节点中具有关联值的所有键。abstract Stringname()返回此首选项节点的名称，相对于其父节点。abstract Preferences返回与此节点相同树中的命名首选项节点，如果它们尚不存在，则创建它及其任何祖先。abstract booleannodeExists(String pathName) 如果与此节点相同树中存在命名首选项节点，则返回true。abstract Preferencesparent()返回此首选项节点的父节点，如果这是根节点，则返回null。abstract void将指定的值与此首选项节点中的指定键关联。abstract voidputBoolean(String key, boolean value) 将表示指定布尔值的字符串与此首选项节点中的指定键关联。abstract voidputByteArray(String key, byte[] value) 将表示指定字节数组的字符串与此首选项节点中的指定键关联。abstract void将表示指定双精度值的字符串与此首选项节点中的指定键关联。abstract void将表示指定浮点值的字符串与此首选项节点中的指定键关联。abstract void将表示指定整数值的字符串与此首选项节点中的指定键关联。abstract void将表示指定长整数值的字符串与此首选项节点中的指定键关联。abstract void如果存在，则删除与此首选项节点中的指定键关联的值。abstract void删除此首选项节点及其所有后代，使包含在已删除节点中的任何首选项无效。abstract void删除指定的NodeChangeListener，使其不再接收更改事件。abstract void删除指定的首选项更改监听器，使其不再接收首选项更改事件。abstract voidsync()确保从此首选项节点及其后代进行的任何更改在sync调用之前提交到持久存储（从任何VM）后，未来从中读取的值反映这些更改。static PreferencessystemNodeForPackage(Class<?> c) 返回与指定类的包关联（按约定）的系统首选项树中的首选项节点。static Preferences返回系统的根首选项节点。abstract StringtoString()返回此首选项节点的字符串表示形式，如以下表达式计算的：(this.isUserNode() ? "用户" : "系统") + "首选项节点：" + this.absolutePath()。static PreferencesuserNodeForPackage(Class<?> c) 返回与调用用户的首选项树中的指定类的包关联（按约定）的首选项节点。static PreferencesuserRoot()返回调用用户的根首选项节点。
-
Field Details
-
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个字符）。- 参见：
-
-
Constructor Details
-
Preferences
protected Preferences()唯一构造函数。（通常由子类构造函数隐式调用。）
-
-
Method Details
-
userNodeForPackage
返回与调用用户的首选项树中的指定类的包关联（按约定）的首选项节点。约定如下：节点的绝对路径名是完全限定的包名，前面带有斜杠（'/'），每个句点（'.'）替换为斜杠。例如，与类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")。 - 参见：
-
systemNodeForPackage
返回与系统首选项树中的指定类的包关联（按约定）的首选项节点。约定如下：节点的绝对路径名是完全限定的包名，前面带有斜杠（'/'），每个句点（'.'）替换为斜杠。例如，与类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")。 - 参见：
-
userRoot
返回调用用户的根首选项节点。- 返回：
- 调用用户的根首选项节点。
- 抛出：
-
SecurityException- 如果存在安全管理器并且它拒绝RuntimePermission("preferences")。 - 参见：
-
systemRoot
返回系统的根首选项节点。- 返回：
- 系统的根首选项节点。
- 抛出：
-
SecurityException- 如果存在安全管理器并且它拒绝RuntimePermission("preferences")。 - 参见：
-
put
将指定的值与此首选项节点中的指定键关联。- 参数：
-
key- 要与指定值关联的键。 -
value- 要与指定键关联的值。 - 抛出：
-
NullPointerException- 如果键或值为null。 -
IllegalArgumentException- 如果key.length()超过MAX_KEY_LENGTH或如果value.length超过MAX_VALUE_LENGTH。 -
IllegalStateException- 如果此节点（或祖先）已使用removeNode()方法移除。 -
IllegalArgumentException- 如果键或值包含空控制字符，代码点U+0000。
-
get
返回与此偏好节点中指定键关联的值。如果没有与该键关联的值，或者无法访问后备存储，则返回指定的默认值。某些实现可能会将默认值存储在其后备存储中。如果指定键没有关联值，但存在这样一个存储的默认值，则优先返回存储的默认值，而不是指定的默认值。
- 参数：
-
key- 要返回其关联值的键。 -
def- 如果此偏好节点与key没有关联值，则返回的值。 - 返回：
-
与
key关联的值，如果没有与key关联的值，或者无法访问后备存储，则返回def。 - 抛出：
-
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 -
NullPointerException- 如果key为null。（对于def的null值是允许的。） -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。
-
remove
删除此偏好节点中与指定键关联的值（如果有）。如果此实现支持存储的默认值，并且对于指定的偏好设置存在这样一个默认值，则此调用将“公开”存储的默认值，意味着在后续调用
get时将返回存储的默认值。- 参数：
-
key- 要从偏好节点中删除其映射的键。 - 抛出：
-
NullPointerException- 如果key为null。 -
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。
-
clear
删除此偏好节点中的所有偏好设置（键值关联）。此调用不会影响此节点的任何后代。如果此实现支持存储的默认值，并且偏好设置层次结构中的此节点包含任何此类默认值，则此调用将“公开”存储的默认值，意味着在后续调用
get时将返回存储的默认值。- 抛出：
-
BackingStoreException- 如果由于后备存储中的故障或无法与其通信而无法完成此操作。 -
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 - 参见：
-
putInt
将表示指定int值的字符串与此偏好节点中的指定键关联。关联的字符串是如果将int值传递给Integer.toString(int)将返回的字符串。此方法旨在与getInt(java.lang.String, int)一起使用。- 参数：
-
key- 要关联值的字符串形式与之关联的键。 -
value- 要将其字符串形式与键关联的值。 - 抛出：
-
NullPointerException- 如果key为null。 -
IllegalArgumentException- 如果key.length()超过MAX_KEY_LENGTH。 -
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。 - 参见：
-
getInt
返回与此偏好节点中与指定键关联的字符串表示的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值，如果关联值不存在或无法解释为int，则返回def。 - 抛出：
-
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 -
NullPointerException- 如果key为null。 -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。 - 参见：
-
putLong
将表示指定long值的字符串与此偏好节点中的指定键关联。关联的字符串是如果将long值传递给Long.toString(long)将返回的字符串。此方法旨在与getLong(java.lang.String, long)一起使用。- 参数：
-
key- 要关联值的字符串形式与之关联的键。 -
value- 要将其字符串形式与键关联的值。 - 抛出：
-
NullPointerException- 如果key为null。 -
IllegalArgumentException- 如果key.length()超过MAX_KEY_LENGTH。 -
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。 - 参见：
-
getLong
返回与此偏好节点中与指定键关联的字符串表示的long值。字符串将转换为long，如Long.parseLong(String)。如果没有与该键关联的值，无法访问后备存储，或者如果Long.parseLong(String)会抛出NumberFormatException，则返回指定的默认值。此方法旨在与putLong(java.lang.String, long)一起使用。如果实现支持存储的默认值，并且存在这样一个默认值，可以访问并且可以使用
Long.parseLong转换为long，则优先返回此long，而不是指定的默认值。- 参数:
-
key- 要返回其关联值的键，作为长整型。 -
def- 如果此首选项节点没有与key关联的值，或者关联值无法解释为长整型，或者后备存储不可访问，则返回的值。 - 返回:
-
此首选项节点中与
key关联的字符串表示的长整型值，如果关联值不存在或无法解释为长整型，则返回def。 - 抛出:
-
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 -
NullPointerException- 如果key为null。 -
IllegalArgumentException- 如果key包含空控制字符，代码点U+0000。 - 参见:
-
putBoolean
在此首选项节点中，将表示指定布尔值的字符串与指定键关联。如果值为true，则关联字符串为"true"，如果值为false，则为"false"。此方法旨在与getBoolean(java.lang.String, boolean)一起使用。- 参数:
-
key- 要关联值的字符串形式与之关联的键。 -
value- 要与键关联的值的字符串形式。 - 抛出:
-
NullPointerException- 如果key为null。 -
IllegalArgumentException- 如果key.length()超过MAX_KEY_LENGTH。 -
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 -
IllegalArgumentException- 如果key包含空控制字符，代码点U+0000。 - 参见:
-
getBoolean
返回此首选项节点中与指定键关联的字符串表示的布尔值。有效字符串为"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。 - 参见:
-
putFloat
在此首选项节点中，将表示指定浮点值的字符串与指定键关联。关联的字符串是如果浮点值传递给Float.toString(float)将返回的字符串。此方法旨在与getFloat(java.lang.String, float)一起使用。- 参数:
-
key- 要关联值的字符串形式与之关联的键。 -
value- 要与键关联的值的字符串形式。 - 抛出:
-
NullPointerException- 如果key为null。 -
IllegalArgumentException- 如果key.length()超过MAX_KEY_LENGTH。 -
IllegalStateException- 如果使用removeNode()方法删除了此节点（或祖先）。 -
IllegalArgumentException- 如果key包含空控制字符，代码点U+0000。 - 参见:
-
getFloat
返回此首选项节点中与指定键关联的字符串表示的浮点值。字符串将转换为整数，如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- 如果key包含空控制字符，代码点U+0000。 - 参见:
-
putDouble
在此首选项节点中，将表示指定双精度值的字符串与指定键关联。关联的字符串是如果双精度值传递给Double.toString(double)将返回的字符串。此方法旨在与getDouble(java.lang.String, double)一起使用。- 参数:
-
key- 要与值的字符串形式关联的键。 -
value- 要与键关联的字符串形式的值。 - 抛出:
-
NullPointerException- 如果key为null。 -
IllegalArgumentException- 如果key.length()超过MAX_KEY_LENGTH。 -
IllegalStateException- 如果此节点（或祖先节点）已使用removeNode()方法移除。 -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。 - 参见:
-
getDouble
返回此首选项节点中与指定键关联的字符串表示的双精度值。该字符串将被转换为整数，如Double.parseDouble(String)。如果与键关联的值不存在，后备存储不可访问，或者如果Double.parseDouble(String)会抛出NumberFormatException，则返回指定的默认值。此方法旨在与putDouble(java.lang.String, double)一起使用。如果实现支持存储的默认值，并且存在这样的默认值，可访问，并且可以使用
Double.parseDouble将其转换为双精度值，则优先返回此双精度值，而不是指定的默认值。- 参数:
-
key- 要作为双精度值返回的关联值的键。 -
def- 如果此首选项节点与key关联的值不存在或无法解释为双精度值，或者后备存储不可访问，则将返回的值。 - 返回:
-
此首选项节点中与
key关联的字符串表示的双精度值，如果关联值不存在或无法解释为双精度值，则返回def。 - 抛出:
-
IllegalStateException- 如果此节点（或祖先节点）已使用removeNode()方法移除。 -
NullPointerException- 如果key为null。 -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。 - 参见:
-
putByteArray
将表示指定字节数组的字符串与此首选项节点中的指定键关联。关联的字符串是字节数组的Base64编码，如RFC 2045第6.8节中定义的，只有一个小改变：字符串将完全由Base64字母表中的字符组成；它不会包含任何换行符。请注意，字节数组的最大长度限制为MAX_VALUE_LENGTH的四分之三，以使Base64编码的字符串长度不超过MAX_VALUE_LENGTH。此方法旨在与getByteArray(java.lang.String, byte[])一起使用。- 参数:
-
key- 要与值的字符串形式关联的键。 -
value- 要与键关联的字符串形式的值。 - 抛出:
-
NullPointerException- 如果键或值为null。 -
IllegalArgumentException- 如果键.length()超过MAX_KEY_LENGTH或值.length超过MAX_VALUE_LENGTH*3/4。 -
IllegalStateException- 如果此节点（或祖先节点）已使用removeNode()方法移除。 -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。 - 参见:
-
getByteArray
返回此首选项节点中与指定键关联的字符串表示的字节数组值。有效字符串是Base64编码的二进制数据，如RFC 2045第6.8节中定义的，只有一个小改变：字符串必须完全由Base64字母表中的字符组成；不允许换行字符或多余字符。此方法旨在与putByteArray(java.lang.String, byte[])一起使用。如果与键关联的值不存在，后备存储不可访问，或者关联值不是有效的Base64编码的字节数组（如上所定义），则返回指定的默认值。
如果实现支持存储的默认值，并且存在这样的默认值且可访问，则优先使用该默认值，除非存储的默认值不是有效的Base64编码的字节数组（如上所定义），在这种情况下将使用指定的默认值。
- 参数:
-
key- 要作为字节数组返回的关联值的键。 -
def- 如果此首选项节点与key关联的值不存在或无法解释为字节数组，或者后备存储不可访问，则将返回的值。 - 返回:
-
此首选项节点中与
key关联的字符串表示的字节数组值，如果关联值不存在或无法解释为字节数组，则返回def。 - 抛出:
-
IllegalStateException- 如果此节点（或祖先节点）已使用removeNode()方法移除。 -
NullPointerException- 如果key为null。（对于def的null值是允许的。） -
IllegalArgumentException- 如果键包含空控制字符，代码点U+0000。 - 参见:
-
keys
返回此首选项节点中具有关联值的所有键。（如果此节点没有首选项，则返回的数组大小为零。）如果实现支持存储的默认值，并且在此节点存在任何未被显式首选项覆盖的这样的默认值，则默认值将在数组中返回，除了任何显式首选项。
- 返回:
- 具有关联值的键数组。
- 抛出:
-
BackingStoreException- 如果由于后备存储中的故障或无法与其通信而无法完成此操作。 -
IllegalStateException- 如果此节点（或祖先节点）已使用removeNode()方法移除。
-
childrenNames
返回此首选项节点的子项的名称，相对于此节点。（如果此节点没有子项，则返回的数组大小为零。）- 返回:
- 此首选项节点的子项的名称。
- 抛出:
-
BackingStoreException- 如果由于后备存储中的故障或无法与其通信而无法完成此操作。 -
IllegalStateException- 如果此节点（或祖先节点）已使用removeNode()方法移除。
-
parent
返回此首选项节点的父节点，如果这是根节点，则返回null。- 返回:
- 此首选项节点的父节点。
- 抛出:
-
IllegalStateException- 如果此节点（或祖先节点）已使用removeNode()方法移除。
-
node
返回与此节点相同树中的命名首选项节点，如果它们尚不存在，则创建它及其任何祖先。接受相对或绝对路径名。相对路径名（不以斜杠字符('/')开头）将相对于此首选项节点进行解释。如果返回的节点在此调用之前不存在，则通过调用返回的节点（或其祖先或后代之一）上的
flush方法，不保证此节点及由此调用创建的任何祖先将变为永久。- 参数:
-
pathName- 要返回的首选项节点的路径名。 - 返回:
- 指定的首选项节点。
- 抛出:
-
IllegalArgumentException- 如果路径名无效（即，它包含多个连续的斜杠字符，或以斜杠字符结尾且长度超过一个字符）。 -
NullPointerException- 如果路径名为null。 -
IllegalStateException- 如果此节点（或祖先）已使用removeNode()方法移除。 - 参见:
-
nodeExists
如果命名的首选项节点在与此节点相同树中存在，则返回true。相对路径名（不以斜杠字符('/')开头）将相对于此首选项节点进行解释。如果此节点（或祖先）已使用
removeNode()方法移除，则调用此方法是合法的，但只能使用路径名""；调用将返回false。因此，习语p.nodeExists("")可用于测试p是否已被移除。- 参数:
-
pathName- 要检查其存在性的节点的路径名。 - 返回:
-
如果指定的节点存在，则返回
true。 - 抛出:
-
BackingStoreException- 如果由于后备存储中的故障或无法与其通信而无法完成此操作。 -
IllegalArgumentException- 如果路径名无效（即，它包含多个连续的斜杠字符，或以斜杠字符结尾且长度超过一个字符）。 -
NullPointerException- 如果路径名为null。 -
IllegalStateException- 如果此节点（或祖先）已使用removeNode()方法移除，并且pathName不是空字符串（""）。
-
removeNode
移除此首选项节点及其所有后代，使包含在已移除节点中的任何首选项无效。一旦移除节点，尝试在相应的Preferences实例上调用name()、absolutePath()、isUserNode()、flush()或nodeExists("")之外的任何方法将导致IllegalStateException。 （在已移除节点之后，仍然可以在节点上调用Object定义的方法；它们不会抛出IllegalStateException。）在调用此节点（或祖先）上的
flush方法之前，不能保证移除是持久的。如果此实现支持存储的默认值，则移除节点会公开此节点或以下节点处的任何存储的默认值。因此，对此节点路径名的后续调用
nodeExists可能返回true，对此路径名的node的后续调用可能返回表示非空首选项集合和/或子项的（不同的）Preferences实例。- 抛出:
-
BackingStoreException- 如果由于后备存储中的故障或无法与其通信而无法完成此操作。 -
IllegalStateException- 如果此节点（或祖先）已使用removeNode()方法移除。 -
UnsupportedOperationException- 如果在根节点上调用此方法。 - 参见:
-
name
返回此首选项节点相对于其父节点的名称。- 返回:
- 此首选项节点相对于其父节点的名称。
-
absolutePath
返回此首选项节点的绝对路径名。- 返回:
- 此首选项节点的绝对路径名。
-
isUserNode
public abstract boolean isUserNode()如果此首选项节点在用户首选项树中，则返回true，如果在系统首选项树中，则返回false。- 返回:
-
如果此首选项节点在用户首选项树中，则返回
true，如果在系统首选项树中，则返回false。
-
toString
返回此首选项节点的字符串表示形式，如通过表达式计算：(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath()。 -
flush
强制将此首选项节点及其后代内容中的任何更改写入持久存储。一旦此方法成功返回，可以安全地假定在方法调用之前在以此节点为根的子树中所做的所有更改已变为永久。实现可以随时将更改刷新到持久存储。它们不需要等待调用此方法。
在新创建的节点上发生刷新时，它将变为持久节点，尚未变为持久的任何祖先（和后代）也将变为持久。但请注意，祖先中的任何首选项值更改不保证会变为持久。
如果在已使用
removeNode()方法移除的节点上调用此方法，则会在此节点上调用flushSpi()，但不会在其他节点上调用。- 抛出:
-
BackingStoreException- 如果由于后备存储中的故障或无法与其通信而无法完成此操作。 - 参见:
-
sync
确保从此首选项节点及其后代进行的任何读取反映在sync调用之前（从任何VM）提交到持久存储的更改。作为副作用，强制将此首选项节点及其后代内容中的任何更改写入持久存储，就好像在此节点上调用了flush方法一样。- 抛出:
-
BackingStoreException- 如果由于后备存储中的故障或无法与其通信而无法完成此操作。 -
IllegalStateException- 如果此节点（或祖先）已使用removeNode()方法移除。 - 参见:
-
addPreferenceChangeListener
注册指定的监听器以接收此首选项节点的首选项更改事件。当向此节点添加首选项、从此节点中移除首选项或更改与首选项关联的值时，将生成首选项更改事件。（首选项更改事件不是由removeNode()方法生成的，该方法生成节点更改事件。首选项更改事件由clear方法生成。）仅对在与注册监听器相同的JVM中进行的更改才保证生成事件，尽管一些实现可能会为在此JVM之外进行的更改生成事件。事件可能在更改变得持久之前生成。当在此节点的后代中修改首选项时，不会生成事件；希望生成此类事件的调用者必须向每个后代注册。
- 参数:
-
pcl- 要添加的首选项更改监听器。 - 抛出:
-
NullPointerException- 如果pcl为null。 -
IllegalStateException- 如果此节点（或祖先）已使用removeNode()方法移除。 - 参见:
-
removePreferenceChangeListener
移除指定的首选项更改监听器，使其不再接收首选项更改事件。- 参数:
-
pcl- 要移除的首选项更改监听器。 - 抛出:
-
IllegalArgumentException- 如果pcl不是在此节点上注册的首选项更改监听器。 -
IllegalStateException- 如果使用removeNode()方法移除了此节点（或祖先）。 - 参见:
-
addNodeChangeListener
注册指定的监听器以接收此节点的节点更改事件。当向此节点添加或移除子节点时，将生成节点更改事件。（单个removeNode()调用会导致多个节点更改事件，每个事件对应于从已移除节点为根的子树中的每个节点。）仅对在与注册监听器相同的JVM中进行的更改才能保证生成事件，尽管一些实现可能会对在此JVM之外进行的更改生成事件。事件可能在更改变为永久之前生成。当添加或移除此节点的间接后代时不会生成事件；希望接收此类事件的调用者必须向每个后代注册。
关于节点创建很少能提供保证。因为节点在访问时隐式创建，所以对于实现来说确定在访问之前后端存储中是否存在子节点可能是不可行的（例如，因为无法访问后端存储或缓存的信息已过时）。在这种情况下，实现既不需要生成节点更改事件，也不禁止这样做。
- 参数:
-
ncl- 要添加的NodeChangeListener。 - 抛出:
-
NullPointerException- 如果ncl为null。 -
IllegalStateException- 如果使用removeNode()方法移除了此节点（或祖先）。 - 参见:
-
removeNodeChangeListener
移除指定的NodeChangeListener，使其不再接收更改事件。- 参数:
-
ncl- 要移除的NodeChangeListener。 - 抛出:
-
IllegalArgumentException- 如果ncl不是在此节点上注册的NodeChangeListener。 -
IllegalStateException- 如果使用removeNode()方法移除了此节点（或祖先）。 - 参见:
-
exportNode
在指定的输出流上发出代表此节点中包含的所有首选项（但不包括其后代）的XML文档。这个XML文档实际上是节点的离线备份。XML文档将具有以下DOCTYPE声明：
将使用UTF-8字符编码。<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">此方法是对在此类中同时执行多个方法的结果等效于某些串行执行的一般规则的例外。如果在调用此方法时同时修改了此节点上的首选项，导出的首选项将包含节点中包含的首选项的“模糊快照”；一些并发修改可能会反映在导出的数据中，而其他修改可能不会。
- 参数:
-
os- 要发出XML文档的输出流。 - 抛出:
-
IOException- 如果写入指定的输出流导致IOException。 -
BackingStoreException- 如果无法从后备存储读取首选项数据。 -
IllegalStateException- 如果使用removeNode()方法移除了此节点（或祖先）。 - 参见:
-
exportSubtree
发出代表此节点及其所有后代节点中包含的所有首选项的XML文档。这个XML文档实际上是以该节点为根的子树的离线备份。XML文档将具有以下DOCTYPE声明：
将使用UTF-8字符编码。<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">此方法是对在此类中同时执行多个方法的结果等效于某些串行执行的一般规则的例外。如果在调用此方法时同时修改了此节点的首选项或节点的后代，导出的首选项将包含子树中的并发修改的“模糊快照”；一些并发修改可能会反映在导出的数据中，而其他修改可能不会。
- 参数:
-
os- 要发出XML文档的输出流。 - 抛出:
-
IOException- 如果写入指定的输出流导致IOException。 -
BackingStoreException- 如果无法从后备存储读取首选项数据。 -
IllegalStateException- 如果使用removeNode()方法移除了此节点（或祖先）。 - 参见:
-
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")。 - 参见:
-