compact3

java.util.prefs

Class Preferences

java.lang.Object

java.util.prefs.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实现来生成根首选项节点。 这允许管理员用替代实现来替换默认首选项实现。

实施说明：在Sun的JRE中， PreferencesFactory的实现位置如下：

1. 如果系统属性java.util.prefs.PreferencesFactory定义，那么它被认为是实现PreferencesFactory接口的类的完全限定名称。 该类被加载和实例化; 如果此过程失败，则抛出未指定的错误。

2. 如果一个PreferencesFactory实现类文件已经被安装在一个jar文件，它是可见的system class loader ，以及jar文件包含在资源目录META-INF/services名为java.util.prefs.PreferencesFactory提供者配置文件，然后在该文件中指定的第一个类名取。 如果提供了多个这样的jar文件，那么将使用第一个。 该类被加载和实例化; 如果此过程失败，则抛出未指定的错误。

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

从以下版本开始：

1.4

Field Summary

Fields

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

构造方法摘要

构造方法

Modifier	Constructor and Description
protected	Preferences() 唯一的构造函数。

方法摘要

Modifier and Type	Method and Description
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() 如果此首选项节点位于用户首选项树 false（如果它在系统首选项树中），则返回 true 。
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(类<?> c) 从与指定类的包关联（按照约定）的系统首选项树返回首选项节点。
static Preferences	systemRoot() 返回系统的根首选项节点。
abstract String	toString() 返回此首选项节点的字符串表示形式，就好像以下表达式计算： (this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 。
static Preferences	userNodeForPackage(类<?> c) 从调用用户的偏好树中返回偏好节点，该树通过指定的类的包（与约定）相关联。
static Preferences	userRoot() 返回主叫用户的根优先级节点。

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

字段详细信息

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(类<?> 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(类<?> 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()方法删除。

get

public abstract String get(String key,
                           String def)

返回与此首选项节点中指定键相关联的值。 如果没有与密钥相关联的值，或者后台存储不可访问，则返回指定的默认值。

一些实现可以在其后备存储中存储默认值。 如果没有与指定键相关联的值，但存在这样的存储缺省值 ，则优先于指定的默认值返回。

参数

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

def - 在此首选项节点没有与 key相关联的值的情况下返回的值。

结果

与key相关 联的值，或 def，如果没有值与 key相关联 ，或后备存储不可访问。

异常

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

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

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 - 其字符串形式与键关联的值。

异常

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)一起使用 。

如果实现支持存储的默认值 ，这样的默认值存在，是可访问的，并且可以转换为int与Integer.parseInt，这个中断返回优先于指定的默认。

参数

key - 其关联值将作为int返回的键。

def - 如果此首选项节点没有与 key相关联的值或相关联的值不能被解释为int，或者后台存储不可访问，则返回值。

结果

通过如果相关联的值不存在，或者可以不被解释为一个int与 key此首选项节点，或 def相关联的字符串所表示的int值。

异常

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

NullPointerException - 如果 key是 null 。

另请参见：

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

putLong

public abstract void putLong(String key,
                             long value)

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

参数

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

value - 其字符串形式与键相关联的值。

异常

NullPointerException - 如果 key是 null 。

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

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

另请参见：

getLong(String,long)

getLong

public abstract long getLong(String key,
                             long def)

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

如果实现支持存储的默认值 ，这样的默认值存在，是可访问的，并且可以转换为长着Long.parseLong，这漫长的返回优先于指定的默认。

参数

key - 其关联值将作为长期返回的键。

def - 如果此首选项节点没有与 key关联的值或相关联的值不能被解释为长时间，或后备存储不可访问，则返回值。

结果

通过如果相关联的值不存在，或者可以不被解释为长与 key此首选项节点，或 def相关联的字符串所表示的长值。

异常

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

NullPointerException - 如果 key是 null 。

另请参见：

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

putBoolean

public abstract void putBoolean(String key,
                                boolean value)

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

参数

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

value - 其字符串形式与键相关联的值。

异常

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)

返回由此首选项节点中与指定键相关联的字符串表示的布尔值。 有效的字符串为"true"，它代表真实的，"false"，表示假的。 情况被忽略，所以例如"TRUE"和"False"也是有效的。 此方法适用于putBoolean(java.lang.String, boolean) 。

如果没有与密钥相关联的值，后台存储不可访问，或者如果相关值不是"true"或"false" ，则返回指定的默认值，忽略大小写。

如果实现支持存储的默认值 ，并且这样的默认值存在并且可访问，则优先于指定的默认值，除非存储的默认值不是"true"或"false" ， 否则忽略大小写，在这种情况下使用指定的默认值。

参数

key - 其关联值将作为布尔值返回的键。

def - 如果此首选项节点没有与 key相关联的值或相关联的值不能被解释为布尔值，或后备存储是不可访问的，则返回值。

结果

通过如果相关联的值不存在或不能被解释为一个布尔与 key此首选项节点，或 def相关联的字符串所表示的布尔值。

异常

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

NullPointerException - 如果 key是 null 。

另请参见：

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

putFloat

public abstract void putFloat(String key,
                              float value)

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

参数

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

value - 其字符串形式与键关联的值。

异常

NullPointerException - 如果 key是 null 。

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

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

另请参见：

getFloat(String,float)

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相关联的值或相关联的值不能被解释为浮点型或后备存储不可访问，则返回值。

结果

通过如果相关联的值不存在或不能被解释为float与 key此首选项节点，或 def相关联的字符串所表示的浮点值。

异常

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

NullPointerException - 如果 key是 null 。

另请参见：

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

putDouble

public abstract void putDouble(String key,
                               double value)

将表示指定双重值的字符串与此首选项节点中指定的键相关联。 如果双重值传递给Double.toString(double) ，则相关联的字符串将返回。 此方法适用于getDouble(java.lang.String, double) 。

参数

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

value - 其字符串形式与键关联的值。

异常

NullPointerException - 如果 key是 null 。

IllegalArgumentException - key.length()是否超过 MAX_KEY_LENGTH 。

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

另请参见：

getDouble(String,double)

getDouble

public abstract double getDouble(String key,
                                 double def)

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

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

参数

key - 其关联值将作为双重返回的键。

def - 如果此首选项节点没有与 key关联的值或相关联的值不能被解释为双精度值，或后备存储不可访问，则返回的值。

结果

通过如果相关联的值不存在，或者可以不被解释为一个双用 key此首选项节点，或 def相关联的字符串所表示的双值。

异常

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

NullPointerException - 如果 key是 null 。

另请参见：

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

putByteArray

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

将表示指定字节数组的字符串与此首选项节点中指定的键相关联。 相关联的字符串是字节数组的Base64编码，如RFC 2045第6.8节中定义的，其中一个较小的更改：字符串将仅由Base64 Alphabet的字符组成; 它不会包含任何换行符。 请注意，字节数组的最大长度限制为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()方法删除。

另请参见：

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 。 （为def甲null值是允许的。）

另请参见：

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()

如果此首选项节点在用户首选项树 false（如果它在系统首选项树中），则返回 true 。

结果

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)

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

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