Most visited

Recently visited

Results for

Added in API level 1

Summary: Constants | Protected Ctors | Methods | Inherited Methods | [Expand All]

Preferences

public abstract class Preferences
extends Object

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

Known Direct Subclasses

AbstractPreferences

偏好数据分层集合中的节点。该类允许应用程序存储和检索用户和系统首选项和配置数据。这些数据永久存储在一个依赖于实现的后台存储中。典型的实现包括平面文件，特定于操作系统的注册表，目录服务器和SQL数据库。这个类的用户不需要关心后备存储的细节。

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

偏好树中的节点以与分层文件系统中的目录类似的方式命名。首选项树中的每个节点都有一个节点名称 （不一定是唯一的），唯一的绝对路径名称以及相对于每个祖先（包括其自身）的路径名称。

根节点具有空字符串（“”）的节点名称。每个其他节点都有一个任意的节点名称，在创建时指定。此名称的唯一限制是它不能是空字符串，也不能包含斜线字符（'/'）。

根节点的绝对路径名称为"/" 。根节点的子节点的绝对路径名称为"/" + <节点名称> 。所有其他节点的绝对路径名称都是<父节点的绝对路径名称> + "/" + <节点名称> 。请注意，所有绝对路径名都以斜杠字符开头。

节点n的相对路径名到它的祖先一个仅仅是必须附加到字符串的绝对路径名，以便以形成n的绝对路径名，与初始斜杠字符（如果存在的话）中除去。注意：

No relative path names begin with the slash character.
Every node's path name relative to itself is the empty string.
Every node's path name relative to its parent is its node name (except for the root node, which does not have a parent).
Every node's path name relative to the root is its absolute path name with the initial slash character removed.

最后要注意的是：

No path name contains multiple consecutive slash characters.
No path name with the exception of the root's absolute path name ends in the slash character.
Any string that conforms to these two rules is a valid path name.

所有修改偏好数据的方法都允许异步操作; 它们可能会立即返回，并且更改最终会传播到持久性后备存储，并带有实现相关延迟。 flush方法可用于同步强制对后备存储的更新。 Java虚拟机的正常终止不会导致挂起更新的损失-明确flush调用不需要终止时，确保挂起更新变得持久。

所有从Preferences对象中读取首选项的方法都需要调用者提供默认值。如果先前未设置任何值或后备存储不可用，则返回默认值。目的是允许应用程序运行，尽管功能略有降低，即使后备存储变得不可用。有些方法（如flush ）具有语义，在后备存储不可用时阻止它们运行。普通应用程序不需要调用任何这些方法，这些方法可以通过它们被声明为抛出BackingStoreException的事实来识别。

这个类中的方法可以由单个JVM中的多个线程同时调用，而不需要外部同步，并且结果将等同于某些串行执行。如果此类由多个JVM同时使用，这些JVM将它们的首选项数据存储在同一个后备存储中，则数据存储不会被破坏，但不会对首选数据的一致性做出其他保证。

这个类包含一个导出/导入工具，允许首选项被“导出”到XML文档中，并且XML文档表示首选项被“导入”回系统。该工具可用于备份所有或部分偏好树，并随后从备份中恢复。

XML文档具有以下DOCTYPE声明：

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is not accessed when exporting or importing preferences; it merely serves as a string to uniquely identify the DTD, which is:

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

Every Preferences implementation must have an associated PreferencesFactory implementation. Every Java(TM) SE implementation must provide some means of specifying which PreferencesFactory implementation is used to generate the root preferences nodes. This allows the administrator to replace the default preferences implementation with an alternative implementation.

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

如果定义了系统属性java.util.prefs.PreferencesFactory ，则将其视为实现PreferencesFactory接口的类的完全限定名称。该类被加载并实例化; 如果此过程失败，则会引发未指定的错误。
如果PreferencesFactory实现类文件已安装在对system class loader可见的jar文件中，并且该jar文件在资源目录META-INF/services中包含名为java.util.prefs.PreferencesFactory的提供程序配置文件，则将采用该文件中指定的第一个类名称。如果提供了多个这样的jar文件，则会使用找到的第一个jar文件。该类被加载并实例化; 如果此过程失败，则会引发未指定的错误。
最后，如果既没有提供上述系统属性也没有提供扩展jar文件，则加载并实例化底层平台的系统范围默认 PreferencesFactory实现。

Summary

Constants
`int`	`MAX_KEY_LENGTH` 字符串允许的最大长度（80个字符）。
`int`	`MAX_NAME_LENGTH` 节点名称的最大长度（80个字符）。
`int`	`MAX_VALUE_LENGTH` 字符串允许的最大长度（8192个字符）。

Protected constructors
`Preferences()` 唯一的构造函数。

Public methods
`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)` 返回此首选项节点中与指定键相关联的字符串所表示的double值。
`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()` 返回 `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)` 将表示指定布尔值的字符串与此首选节点中指定的键关联。
`abstract void`	`putByteArray(String key, byte[] value)` 将表示指定字节数组的字符串与此首选节点中指定的键关联。
`abstract void`	`putDouble(String key, double value)` 将表示指定double值的字符串与此首选项节点中指定的键关联。
`abstract void`	`putFloat(String key, float value)` 将表示指定浮点值的字符串与此首选项节点中指定的键关联。
`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)` 警告：在Android上，与“系统”和“用户”首选项对应的首选项节点存储在应用程序无法访问的文件系统部分中。
`static Preferences`	`systemRoot()` 警告：在Android上，与“系统”和“用户”首选项对应的首选项节点存储在应用程序无法访问的文件系统部分中。
`abstract String`	`toString()` 返回此首选项节点的字符串表示形式，就像通过表达式计算的那样： `(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath()` 。
`static Preferences`	`userNodeForPackage(Class<?> c)` 警告：在Android上，与“系统”和“用户”首选项对应的首选项节点存储在应用程序无法访问的文件系统部分中。
`static Preferences`	`userRoot()` 警告：在Android上，与“系统”和“用户”首选项对应的首选项节点存储在应用程序无法访问的文件系统部分中。

Inherited methods

From class java.lang.Object

Constants

MAX_KEY_LENGTH

Added in API level 1

int MAX_KEY_LENGTH

字符串允许的最大长度（80个字符）。

常数值：80（0x00000050）

MAX_NAME_LENGTH

Added in API level 1

int MAX_NAME_LENGTH

节点名称的最大长度（80个字符）。

常数值：80（0x00000050）

MAX_VALUE_LENGTH

Added in API level 1

int MAX_VALUE_LENGTH

字符串允许的最大长度（8192个字符）。

常量值：8192（0x00002000）

Protected constructors

Preferences

Added in API level 1

Preferences ()

唯一的构造函数。（对于子类构造函数的调用，通常是隐式的。）

Public methods

absolutePath

Added in API level 1

String absolutePath ()

返回此首选项节点的绝对路径名称。

Returns
`String`	this preference node's absolute path name.

addNodeChangeListener

Added in API level 1

void addNodeChangeListener (NodeChangeListener ncl)

注册指定的侦听器以接收此节点的节点更改事件 。将子节点添加到此节点或从中删除时，会生成节点更改事件。（单个removeNode()调用会导致多个节点更改事件 ，其中一个用于以已除去的节点为根的子树中的每个节点。）

事件只能保证在与注册监听器相同的JVM中进行的更改，尽管某些实现可能会生成事件以便在此JVM之外进行更改。事件可能会在更改变为永久之前生成。当添加或删除此节点的间接后代时，不会生成事件; 希望发生此类事件的来电者必须向每个后代登记。

几乎没有关于节点创建的保证。由于节点是在访问时隐式创建的，因此实现可能无法确定子节点在访问之前是否存在于后备存储中（例如，因为后备存储无法访问或缓存的信息已过期）。在这些情况下，实现既不需要生成节点更改事件也不被禁止。

Parameters
`ncl`	`NodeChangeListener`: The `NodeChangeListener` to add.

Throws
`NullPointerException`	if `ncl` is null.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

addPreferenceChangeListener

Added in API level 1

void addPreferenceChangeListener (PreferenceChangeListener pcl)

注册指定的侦听器以接收此首选项节点的首选项更改事件 。当首选项添加到此节点，从此节点中删除或与首选项关联的值发生更改时，会生成首选项更改事件。（偏好改变事件不会由所产生的removeNode()方法，该方法生成事件。优选变化事件是由clear方法生成的节点的变化 。）

事件只能保证在与注册监听器相同的JVM中进行的更改，尽管某些实现可能会生成事件以便在此JVM之外进行更改。事件可能在变更持续之前生成。在此节点的后代中修改首选项时不会生成事件; 希望发生此类事件的来电者必须向每个后代登记。

Parameters
`pcl`	`PreferenceChangeListener`: The preference change listener to add.

Throws
`NullPointerException`	if `pcl` is null.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

childrenNames

Added in API level 1

String[] childrenNames ()

返回此首选项节点相对于此节点的子项的名称。（如果此节点没有子节点，则返回的数组的大小为零）。

Returns
`String[]`	the names of the children of this preference node.

Throws
`BackingStoreException`	if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

clear

Added in API level 1

void clear ()

删除此首选项节点中的所有首选项（键值关联）。这个调用对这个节点的任何后代都没有影响。

如果此实现支持 存储的默认值 ，并且首选项层次结构中的此节点包含任何此类默认值，则存储的默认值将由此调用“暴露”，因为它们将在后续调用 get时返回。

Throws
`BackingStoreException`	if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

removeNode()

exportNode

Added in API level 1

void exportNode (OutputStream os)

在指定的输出流上发出一个XML文档，表示该节点中包含的所有首选项（但不包含其后代）。该XML文档实际上是该节点的离线备份。

XML文档将具有以下DOCTYPE声明：

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

The UTF-8 character encoding will be used.

此方法是一般规则的例外，即在此类中同时执行多个方法的结果会产生与某些串行执行相当的结果。如果在调用此方法的同时修改此节点上的首选项，则导出的首选项将包含该节点中包含的首选项的“模糊快照” 某些并发修改可能会反映在导出的数据中，而其他修改则可能不会。

Parameters
`os`	`OutputStream`: the output stream on which to emit the XML document.

Throws
`IOException`	if writing to the specified output stream results in an `IOException`.
`BackingStoreException`	if preference data cannot be read from backing store.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

importPreferences(InputStream)

exportSubtree

Added in API level 1

void exportSubtree (OutputStream os)

发出表示此节点及其所有后代中包含的所有首选项的XML文档。实际上，该XML文档是以该节点为根的子树的离线备份。

XML文档将具有以下DOCTYPE声明：

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

The UTF-8 character encoding will be used.

此方法是一般规则的例外，即在此类中同时执行多个方法的结果会产生与某些串行执行相当的结果。如果以此方法为根的子树中的首选项或节点与此方法的调用同时进行修改，则导出的首选项将包含子树的“模糊快照” 某些并发修改可能会反映在导出的数据中，而其他修改则可能不会。

Parameters
`os`	`OutputStream`: the output stream on which to emit the XML document.

Throws
`IOException`	if writing to the specified output stream results in an `IOException`.
`BackingStoreException`	if preference data cannot be read from backing store.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

flush

Added in API level 1

void flush ()

强制将此首选节点及其后代的内容更改为持久性存储。一旦此方法成功返回，就可以安全地假定在方法调用之前以此节点为根的子树中所做的所有更改都已成为永久性的。

实现可随时将更改刷新到持久存储中。他们不需要等待这种方法被调用。

当在新创建的节点上发生刷新时，它会被持久化，任何尚未被持久化的祖先（和后代）也会被持久化。但请注意，祖先中的任何偏好值更改不保证持久。

如果在使用 removeNode()方法删除的节点上调用此方法，则会在此节点上调用flushSpi（），但在其他节点上调用flushSpi（）。

Throws
`BackingStoreException`	if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

也可以看看：

sync()

get

Added in API level 1

String get (String key, 
                String def)

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

某些实现可能会将默认值存储在其后备存储中。如果没有与指定键关联的值，但存在这样的存储默认值 ，则优先返回指定的默认值。

Parameters
`key`	`String`: key whose associated value is to be returned.
`def`	`String`: the value to be returned in the event that this preference node has no value associated with `key`.

Returns
`String`	the value associated with `key`, or `def` if no value is associated with `key`, or the backing store is inaccessible.

Throws
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.
`NullPointerException`	if `key` is `null`. (A `null` value for `def` is permitted.)

getBoolean

Added in API level 1

boolean getBoolean (String key, 
                boolean def)

返回此首选项节点中与指定键相关联的字符串表示的布尔值。有效的字符串是"true" （表示true），而"false" （表示false）。情况被忽略，因此，例如， "TRUE"和"False"也是有效的。此方法旨在与putBoolean(String, boolean)结合使用。

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

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

Parameters
`key`	`String`: key whose associated value is to be returned as a boolean.
`def`	`boolean`: the value to be returned in the event that this preference node has no value associated with `key` or the associated value cannot be interpreted as a boolean, or the backing store is inaccessible.

Returns
`boolean`	the boolean value represented by the string associated with `key` in this preference node, or `def` if the associated value does not exist or cannot be interpreted as a boolean.

Throws
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.
`NullPointerException`	if `key` is `null`.

也可以看看：

getByteArray

Added in API level 1

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

返回此首选项节点中与指定键相关联的字符串表示的字节数组值。有效的字符串是Base64编码的二进制数据，如RFC 2045的 6.8节中所定义的那样，只有一点小改动：该字符串必须仅由来自Base64字母的字符组成; 不允许换行符或无关字符。此方法旨在与putByteArray(String, byte[])结合使用。

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

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

Parameters
`key`	`String`: key whose associated value is to be returned as a byte array.
`def`	`byte`: the value to be returned in the event that this preference node has no value associated with `key` or the associated value cannot be interpreted as a byte array, or the backing store is inaccessible.

Returns
`byte[]`	the byte array value represented by the string associated with `key` in this preference node, or `def` if the associated value does not exist or cannot be interpreted as a byte array.

Throws
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.
`NullPointerException`	if `key` is `null`. (A `null` value for `def` is permitted.)

也可以看看：

getDouble

Added in API level 1

double getDouble (String key, 
                double def)

返回此首选项节点中与指定键相关联的字符串所表示的double值。该字符串被转换为一个整数，如parseDouble(String) 。返回指定的默认值，如果没有与该键关联的值，后备存储不可访问，或者Double.parseDouble(String)会在传递关联值时抛出NumberFormatException 。此方法旨在与putDouble(String, double)结合使用。

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

Parameters
`key`	`String`: key whose associated value is to be returned as a double.
`def`	`double`: the value to be returned in the event that this preference node has no value associated with `key` or the associated value cannot be interpreted as a double, or the backing store is inaccessible.

Returns
`double`	the double value represented by the string associated with `key` in this preference node, or `def` if the associated value does not exist or cannot be interpreted as a double.

Throws
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.
`NullPointerException`	if `key` is `null`.

也可以看看：

getFloat

Added in API level 1

float getFloat (String key, 
                float def)

返回此首选项节点中与指定键相关联的字符串表示的浮点值。字符串被转换为一个整数，如parseFloat(String) 。返回指定的默认值，如果没有与该键关联的值，则后备存储不可访问，或者Float.parseFloat(String)会在传递关联值时抛出NumberFormatException 。此方法旨在与putFloat(String, float)结合使用。

如果实现支持 存储的默认值并存在这样的默认值，并且可以将其转换为带有 Float.parseFloat的浮动 值 ，则该浮动值优先于指定的默认值返回。

Parameters
`key`	`String`: key whose associated value is to be returned as a float.
`def`	`float`: the value to be returned in the event that this preference node has no value associated with `key` or the associated value cannot be interpreted as a float, or the backing store is inaccessible.

Returns
`float`	the float value represented by the string associated with `key` in this preference node, or `def` if the associated value does not exist or cannot be interpreted as a float.

Throws
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.
`NullPointerException`	if `key` is `null`.

也可以看看：

getInt

Added in API level 1

int getInt (String key, 
                int def)

返回此首选节点中与指定键相关联的字符串表示的int值。该字符串被转换为一个整数，如parseInt(String) 。返回指定的默认值，如果没有与该键关联的值，则后备存储不可访问，或者如果传递关联值NumberFormatException将抛出NumberFormatException 。此方法旨在与putInt(String, int)结合使用。

如果实现支持 存储的默认值，并且存在这样的默认值，可以访问，并且可以使用 Integer.parseInt将其转换为int，则此int将优先返回到指定的默认值。

Parameters
`key`	`String`: key whose associated value is to be returned as an int.
`def`	`int`: the value to be returned in the event that this preference node has no value associated with `key` or the associated value cannot be interpreted as an int, or the backing store is inaccessible.

Returns
`int`	the int value represented by the string associated with `key` in this preference node, or `def` if the associated value does not exist or cannot be interpreted as an int.

Throws
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.
`NullPointerException`	if `key` is `null`.

也可以看看：

getLong

Added in API level 1

long getLong (String key, 
                long def)

返回此首选项节点中与指定键相关联的字符串所表示的长整型值。该字符串转换为长parseLong(String) 。返回指定的默认值，如果没有与该键关联的值，后备存储不可访问，或者Long.parseLong(String)在传递关联值时抛出NumberFormatException 。此方法旨在与putLong(String, long)结合使用。

如果实现支持 存储的默认值并且存在这样的默认值，可以访问，并且可以使用 Long.parseLong将其转换为long，则优先返回此长度，优先于指定的默认值。

Parameters
`key`	`String`: key whose associated value is to be returned as a long.
`def`	`long`: the value to be returned in the event that this preference node has no value associated with `key` or the associated value cannot be interpreted as a long, or the backing store is inaccessible.

Returns
`long`	the long value represented by the string associated with `key` in this preference node, or `def` if the associated value does not exist or cannot be interpreted as a long.

Throws
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.
`NullPointerException`	if `key` is `null`.

也可以看看：

importPreferences

Added in API level 1

void importPreferences (InputStream is)

在指定的输入流中导入由XML文档表示的所有首选项。该文件可以代表用户偏好或系统偏好。如果它表示用户偏好，则首选项将被导入到主叫用户的偏好树中（即使它们最初来自不同用户的偏好树）。如果文档描述的任何首选项都包含不存在的首选节点，则会创建节点。

XML文档必须具有以下DOCTYPE声明：

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

(This method is designed for use in conjunction with exportNode(OutputStream) and exportSubtree(OutputStream).

此方法是一般规则的例外，即在此类中同时执行多个方法的结果会产生与某些串行执行相当的结果。该方法的行为如同在该类的其他公共方法之上执行，特别是node(String)和put(String, String) 。

Parameters
`is`	`InputStream`: the input stream from which to read the XML document.

Throws
`IOException`	if reading from the specified input stream results in an `IOException`.
`InvalidPreferencesFormatException`	Data on input stream does not constitute a valid XML document with the mandated document type.
`SecurityException`	If a security manager is present and it denies `RuntimePermission("preferences")`.

也可以看看：

RuntimePermission

isUserNode

Added in API level 1

boolean isUserNode ()

返回 true如果此首选项节点位于用户首选项树 ，false，如果它在系统首选项树。

Returns
`boolean`	`true` if this preference node is in the user preference tree, `false` if it's in the system preference tree.

keys

Added in API level 1

String[] keys ()

返回此首选项节点中具有关联值的所有键。（如果此节点没有首选项，则返回的数组的大小为零）。

如果实现支持 存储的默认值，并且此节点上有任何默认值尚未被覆盖，则通过显式偏好设置，除了任何显式偏好设置之外，还会在数组中返回默认值。

Returns
`String[]`	an array of the keys that have an associated value in this preference node.

Throws
`BackingStoreException`	if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

name

Added in API level 1

String name ()

返回此首选项节点的名称，相对于其父级。

Returns
`String`	this preference node's name, relative to its parent.

node

Added in API level 1

Preferences node (String pathName)

在与此节点相同的树中返回指定的首选项节点，如果它尚不存在，则将其创建并创建它的任何祖先。接受相对或绝对路径名称。相对路径名称（不以斜杠字符('/')开头 ）相对于此首选项节点进行解释。

如果在此调用之前返回的节点不存在，则不会保证此节点以及由此调用创建的所有祖先变为永久的，直到在返回的节点（或其祖先或后代之一）上调用 flush方法为止。

Parameters
`pathName`	`String`: the path name of the preference node to return.

Returns
`Preferences`	the specified preference node.

Throws
`IllegalArgumentException`	if the path name is invalid (i.e., it contains multiple consecutive slash characters, or ends with a slash character and is more than one character long).
`NullPointerException`	if path name is `null`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

flush()

nodeExists

Added in API level 1

boolean nodeExists (String pathName)

如果指定的首选项节点与此节点位于同一棵树中，则返回true。相对路径名称（不以斜杠字符('/')开头 ）相对于此首选项节点进行解释。

如果此节点（或祖先）已使用removeNode()方法删除，则调用此方法是合法的，但仅适用于路径名称"" ; 该调用将返回false 。因此，可以使用习语p.nodeExists("")来测试p是否已被移除。

Parameters
`pathName`	`String`: the path name of the node whose existence is to be checked.

Returns
`boolean`	true if the specified node exists.

Throws
`BackingStoreException`	if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
`IllegalArgumentException`	if the path name is invalid (i.e., it contains multiple consecutive slash characters, or ends with a slash character and is more than one character long).
`NullPointerException`	if path name is `null`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method and `pathName` is not the empty string (`""`).

parent

Added in API level 1

Preferences parent ()

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

Returns
`Preferences`	the parent of this preference node.

Throws
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

put

Added in API level 1

void put (String key, 
                String value)

将指定的值与此首选项节点中的指定键关联。

Parameters
`key`	`String`: key with which the specified value is to be associated.
`value`	`String`: value to be associated with the specified key.

Throws
`NullPointerException`	if key or value is `null`.
`IllegalArgumentException`	if `key.length()` exceeds `MAX_KEY_LENGTH` or if `value.length` exceeds `MAX_VALUE_LENGTH`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

putBoolean

Added in API level 1

void putBoolean (String key, 
                boolean value)

将表示指定布尔值的字符串与此首选节点中指定的键关联。相关的字符串是"true"如果值为true，并且"false"如果是假的。此方法旨在与getBoolean(String, boolean)结合使用。

Parameters
`key`	`String`: key with which the string form of value is to be associated.
`value`	`boolean`: value whose string form is to be associated with key.

Throws
`NullPointerException`	if `key` is `null`.
`IllegalArgumentException`	if `key.length()` exceeds `MAX_KEY_LENGTH`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

putByteArray

Added in API level 1

void putByteArray (String key, 
                byte[] value)

将表示指定字节数组的字符串与此首选节点中指定的键关联。关联的字符串是字节数组的Base64编码，如第10节中的RFC 2045中所定义的那样，只有一点小改动：该字符串将仅由来自Base64字母的字符组成; 它不会包含任何换行符。请注意，字节数组的最大长度限制为MAX_VALUE_LENGTH的四分之三，以便Base64编码的字符串的长度不超过MAX_VALUE_LENGTH 。此方法旨在与getByteArray(String, byte[])结合使用。

Parameters
`key`	`String`: key with which the string form of value is to be associated.
`value`	`byte`: value whose string form is to be associated with key.

Throws
`NullPointerException`	if key or value is `null`.
`IllegalArgumentException`	if key.length() exceeds MAX_KEY_LENGTH or if value.length exceeds MAX_VALUE_LENGTH*3/4.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

putDouble

Added in API level 1

void putDouble (String key, 
                double value)

将表示指定double值的字符串与此首选项节点中指定的键关联。如果将double值传递给toString(double)则关联的字符串将返回。此方法旨在与getDouble(String, double)结合使用。

Parameters
`key`	`String`: key with which the string form of value is to be associated.
`value`	`double`: value whose string form is to be associated with key.

Throws
`NullPointerException`	if `key` is `null`.
`IllegalArgumentException`	if `key.length()` exceeds `MAX_KEY_LENGTH`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

getDouble(String, double)

putFloat

Added in API level 1

void putFloat (String key, 
                float value)

将表示指定浮点值的字符串与此首选项节点中指定的键关联。如果浮点值传递给toString(float)则关联的字符串将返回。此方法旨在与getFloat(String, float)结合使用。

Parameters
`key`	`String`: key with which the string form of value is to be associated.
`value`	`float`: value whose string form is to be associated with key.

Throws
`NullPointerException`	if `key` is `null`.
`IllegalArgumentException`	if `key.length()` exceeds `MAX_KEY_LENGTH`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

getFloat(String, float)

putInt

Added in API level 1

void putInt (String key, 
                int value)

将表示指定int值的字符串与此首选项节点中的指定键关联。如果int值传递给toString(int) ，那么关联的字符串就是返回的toString(int) 。此方法旨在与getInt(String, int)一起使用。

Parameters
`key`	`String`: key with which the string form of value is to be associated.
`value`	`int`: value whose string form is to be associated with key.

Throws
`NullPointerException`	if `key` is `null`.
`IllegalArgumentException`	if `key.length()` exceeds `MAX_KEY_LENGTH`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

getInt(String, int)

putLong

Added in API level 1

void putLong (String key, 
                long value)

将表示指定long值的字符串与此首选项节点中指定的键关联。如果long值传递给toString(long) ，那么关联的字符串就是返回的toString(long) 。此方法旨在与getLong(String, long)结合使用。

Parameters
`key`	`String`: key with which the string form of value is to be associated.
`value`	`long`: value whose string form is to be associated with key.

Throws
`NullPointerException`	if `key` is `null`.
`IllegalArgumentException`	if `key.length()` exceeds `MAX_KEY_LENGTH`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

getLong(String, long)

remove

Added in API level 1

void remove (String key)

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

如果此实现支持 存储的默认值 ，并且指定的首选项有这样的默认值，则存储的默认值将由此调用“暴露”，这意味着将通过后续调用 get来返回。

Parameters
`key`	`String`: key whose mapping is to be removed from the preference node.

Throws
`NullPointerException`	if `key` is `null`.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

removeNode

Added in API level 1

void removeNode ()

删除此首选项节点及其所有后代，使已删除节点中包含的所有首选项失效。一旦节点已被去除，试图比其他任何方法name() ， absolutePath() ， isUserNode() ， flush()或nodeExists("")在相应Preferences实例将失败，并IllegalStateException。 （在Object定义的方法在Object仍然可以在节点上调用;它们不会抛出IllegalStateException。 ）

除非在此节点（或祖先）上调用 flush方法， 否则删除不保证持久。

如果此实现支持存储的默认值 ，则删除节点将公开此节点或其下的任何存储的默认值。因此，为nodeExists的后续调用这个节点的路径名称可能会返回true，并node后续调用这个路径名称可能返回表示首选项和/或儿童的非空集（不同的）Preferences实例。

Throws
`BackingStoreException`	if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
`IllegalStateException`	if this node (or an ancestor) has already been removed with the `removeNode()` method.
`UnsupportedOperationException`	if this method is invoked on the root node.

也可以看看：

flush()

removeNodeChangeListener

Added in API level 1

void removeNodeChangeListener (NodeChangeListener ncl)

删除指定的 NodeChangeListener ，因此它不再收到更改事件。

Parameters
`ncl`	`NodeChangeListener`: The `NodeChangeListener` to remove.

Throws
`IllegalArgumentException`	if `ncl` was not a registered `NodeChangeListener` on this node.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

addNodeChangeListener(NodeChangeListener)

removePreferenceChangeListener

Added in API level 1

void removePreferenceChangeListener (PreferenceChangeListener pcl)

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

Parameters
`pcl`	`PreferenceChangeListener`: The preference change listener to remove.

Throws
`IllegalArgumentException`	if `pcl` was not a registered preference change listener on this node.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

addPreferenceChangeListener(PreferenceChangeListener)

sync

Added in API level 1

void sync ()

确保将来自此首选项节点及其后代的未来读取反映在调用sync之前已提交给永久存储（来自任何VM）的任何更改。作为副作用，强制将此首选项节点及其后代的内容更改为持久性存储，就好像在此节点上调用了flush方法一样。

Throws
`BackingStoreException`	if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
`IllegalStateException`	if this node (or an ancestor) has been removed with the `removeNode()` method.

也可以看看：

flush()

systemNodeForPackage

Added in API level 1

Preferences systemNodeForPackage (Class<?> c)

警告：在Android上，与“系统”和“用户”首选项对应的首选项节点存储在应用程序无法访问的文件系统部分中。此外，允许应用程序设置“系统范围”偏好与android的安全模型相反。返回与指定类的包关联（按照约定）的系统首选项树中的首选项节点。约定如下：节点的绝对路径名是完全限定的包名称，前面是斜线（ '/' ），每个句点（ '.' ）都用斜线替代。例如，与类com.acme.widget.Foo关联的节点的绝对路径名是/com/acme/widget 。

此惯例不适用于未命名的软件包，其关联首选节点为<unnamed> 。这个节点并不打算长期使用，而是为了方便早期开发尚未属于软件包的程序和“一次性”程序。 有价值的数据不应该存储在该节点上，因为它被所有使用它的程序共享。

希望访问与其包有关的首选项的类 Foo可以获得如下的首选节点：

  static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);

This idiom obviates the need for using a string to describe the preferences node and decreases the likelihood of a run-time failure. (If the class name is misspelled, it will typically result in a compile-time error.)

调用此方法将导致创建返回的节点及其祖先，如果它们不存在的话。如果返回的节点在此调用之前不存在，则不会保证此节点以及由此调用创建的所有祖先永远不会成为永久的，除非在返回的节点（或其祖先或后代之一）上调用flush方法。

Parameters
`c`	`Class`: the class for whose package a system preference node is desired.

Returns
`Preferences`	the system preference node associated with the package of which `c` is a member.

Throws
`NullPointerException`	if `c` is `null`.
`SecurityException`	if a security manager is present and it denies `RuntimePermission("preferences")`.

也可以看看：

RuntimePermission

systemRoot

Added in API level 1

Preferences systemRoot ()

警告：在Android上，与“系统”和“用户”首选项对应的首选项节点存储在应用程序无法访问的文件系统部分中。此外，允许应用程序设置“系统范围”偏好与android的安全模型相反。返回系统的根偏好节点。

Returns
`Preferences`	the root preference node for the system.

Throws
`SecurityException`	If a security manager is present and it denies `RuntimePermission("preferences")`.

也可以看看：

RuntimePermission

toString

Added in API level 1

String toString ()

返回此首选项节点的字符串表示形式，就像通过表达式计算的那样： (this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 。

Returns
`String`	a string representation of the object.

userNodeForPackage

Added in API level 1

Preferences userNodeForPackage (Class<?> c)

警告：在Android上，与“系统”和“用户”首选项对应的首选项节点存储在应用程序无法访问的文件系统部分中。此外，允许应用程序设置“系统范围”偏好与android的安全模型相反。返回与指定类的包关联（通过约定）的调用用户首选项树中的首选项节点。约定如下所示：节点的绝对路径名称是完全限定的包名称，前面加斜线（ '/' ），每个句点（ '.' ）都用斜线替代。例如，与类com.acme.widget.Foo关联的节点的绝对路径名称为/com/acme/widget 。

该约定不适用于未命名的包，其关联的首选节点为<unnamed> 。这个节点并不打算长期使用，而是为了方便早期开发尚未属于软件包的程序和“一次性”程序。 有价值的数据不应该存储在该节点上，因为它被所有使用它的程序共享。

希望访问与其包有关的首选项的类 Foo可以获得如下的首选节点：

    static Preferences prefs = Preferences.userNodeForPackage(Foo.class);

调用此方法将导致创建返回的节点及其祖先，如果它们不存在的话。如果在此调用之前返回的节点不存在，则不会保证此节点以及由此调用创建的所有祖先在返回的节点（或其祖先或后代之一）上调用flush方法之前永久保留 。

Parameters
`c`	`Class`: the class for whose package a user preference node is desired.

Returns
`Preferences`	the user preference node associated with the package of which `c` is a member.

Throws
`NullPointerException`	if `c` is `null`.
`SecurityException`	if a security manager is present and it denies `RuntimePermission("preferences")`.

也可以看看：

RuntimePermission

userRoot

Added in API level 1

Preferences userRoot ()

警告：在Android上，与“系统”和“用户”首选项对应的首选项节点存储在应用程序无法访问的文件系统部分中。此外，允许应用程序设置“系统范围”偏好与android的安全模型相反。返回主叫用户的根偏好节点。

Returns
`Preferences`	the root preference node for the calling user.

Throws
`SecurityException`	If a security manager is present and it denies `RuntimePermission("preferences")`.

也可以看看：

RuntimePermission