java.util.prefs
类 AbstractPreferences

java.lang.Object
  java.util.prefs.Preferences
      java.util.prefs.AbstractPreferences

public abstract class AbstractPreferences
extends Preferences

此类提供了 Preferences 类的骨干实现，从而大大简化了实现此类的任务。

此类仅供 Preferences 实现者使用。Preferences 设施的普通用户无需参考此文档。Preferences 文档已经足够了。

实现者必须重写九个抽象服务提供者接口 (SPI) 方法：getSpi(String)、putSpi(String,String)、removeSpi(String)、childSpi(String)、removeNodeSpi()、keysSpi()、childrenNamesSpi()、syncSpi() 和 flushSpi()。所有的具体方法都精确指定它们如何在这些 SPI 方法上实现。如果出于某种考虑（如性能）对默认实现不满意，则实现者可能决定重写一个或多个具体方法。

SPI 方法按异常行为可分为三个组。getSpi 方法应该永远不抛出异常，但是对性能丝毫不会产生影响，因为 get(String,String) 会拦截此方法所抛出的任何异常，并对调用者返回指定的默认值。removeNodeSpi、keysSpi、childrenNamesSpi、syncSpi 和 flushSpi 方法被指定抛出 BackingStoreException；如果实现无法执行操作，则需要抛出此经过检查的异常。该异常向外传播，导致相应的 API 方法失败。

其余的 SPI 方法 putSpi(String,String)、removeSpi(String) 和 childSpi(String) 具有更加复杂的异常行为。未指定它们抛出 BackingStoreException，因为即使内部存储不可用，它们通常也遵守其协定。之所以这样是因为它们不返回任何信息，并且在进行对 Preferences.flush() 或 Preferences.sync() 的后续调用之前，不要求其结果是持久的。一般而言，这些 SPI 方法不应抛出异常。在某些实现中，可能存在这些调用甚至无法对后续处理的请求操作进行排队的情形。即使在这些情形下，最好的做法也是忽略该调用并返回，而不是抛出异常。但是，在这些情形下，所有 flush() 和 sync 的后续调用应该返回 false，因为返回 true 意味着以前的所有操作都已成功地成为持久性操作。

有一种情况下 putSpi、removeSpi 和 childSpi 应该 抛出异常：如果调用者在底层操作系统上不具备执行请求操作的足够权限。例如，如果非特权用户尝试修改系统首选项，则在大多数系统上都会发生这种情况。（这要求特权随实现而变化。在有些实现中，需要修改文件系统中某些目录内容的特权；而在另外一些实现中，则需要修改注册表中某些键的内容。）在上述任何情形下，通常让程序继续执行并不合乎需要，就好像这些操作在以后会成为持久操作一样。虽然在这些情形下不要求实现抛出异常，但还是鼓励这样做。SecurityException 就是合适的选择。

大多数 SPI 方法都要求实现在首选项节点上读取或写入信息。实现者需要注意一种情况，即另一个 VM 当前可能已经从内部存储删除了此节点。如果该节点已经删除了，则实现有责任重新创建它。

实现注意事项：在 Sun 的默认 Preferences 实现中，用户的身份是从底层操作系统继承的，在虚拟机的生命周期中不能更改。在服务器端的 Preferences 实现中，用户身份可以随请求而更改，并通过使用静态 ThreadLocal 实例隐式传递给 Preferences 方法。大力 提倡这种实现的设计者在访问首选项时确定用户（例如，使用 get(String,String) 或 put(String,String) 方法），而不是将用户与每个 Preferences 实例永久关联。后一种行为与通常的 Preferences 用法有冲突，将带来很大的混乱。

从以下版本开始：

1.4

另请参见：

Preferences

newNode

protected boolean newNode

如果在创建此对象前内部存储中不存在此节点，则该字段为 true。该字段被初始化为 false，但是子类构造方法可以将其设置为 true（并且以后不应再修改）。此字段指示创建完成时是否激活节点更改事件。

lock

protected final Object lock

使用其监视器锁定此节点的对象。使用此对象（优先于节点本身）来减少由于锁定节点而有意或无意拒绝服务的可能性。为了避免死锁，永远 不要让保持该节点后代上的锁定的线程锁定节点。

AbstractPreferences

protected AbstractPreferences(AbstractPreferences parent,
                              String name)

用指定的父节点和与其父节点相关的指定名称创建首选项节点。

参数：

parent - 此首选项节点的父节点；如果此首选项是根，则为 null。

name - 此首选项节点相对于其父节点的名称，如果此首选项是根，则为 ""。

抛出：

IllegalArgumentException - 如果 name 包含一个斜杠 ('/') 或者 parent 为 null 且名称不是 ""。

put

public void put(String key,
                String value)

根据 Preferences.put(String,String) 中的规范实现 put 方法。

此实现检查键和值是否合法，获取此首选项节点的锁定，检查该节点是否未被移除，调用 putSpi(String,String)，并且如果存在首选项更改侦听器，则将由事件指派线程所处理的通知事件加入队列。

指定者：

类 Preferences 中的 put

参数：

key - 指定的 value 将要关联的键。

value - 指定的 key 将要关联的值。

抛出：

NullPointerException - 如果 key 或 value 为 null。

IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH，或者 value.length 超过 MAX_VALUE_LENGTH。

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

get

public String get(String key,
                  String def)

根据 Preferences.get(String,String) 中的规范实现 get 方法。

此实现首先检查 key 是否为 null；如果是，则抛出 NullPointerException。然后，它获取此首选项节点的锁，检查该节点是否未被移除，调用 getSpi(String) 并返回结果，除非 getSpi 调用返回 null 或抛出异常，在这种情况下此调用返回 def。

指定者：

类 Preferences 中的 get

参数：

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

def - 此首选项节点不具有与 key 相关联的值时所要返回的值。

返回：

与 key 相关联的值；如果没有与 key 相关联的值，则返回 def。

抛出：

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

NullPointerException - 如果 key 为 null。（默认值 null 是 允许的。）

remove

public void remove(String key)

根据 Preferences.remove(String) 中的规范实现 remove(String) 方法。

此实现获取首选项节点的锁，检查该节点是否未被移除，调用 removeSpi(String)，并且如果存在首选项更改侦听器，则将由事件指派线程所处理的通知事件加入队列。

指定者：

类 Preferences 中的 remove

参数：

key - 从首选项节点中移除其映射关系的键。

抛出：

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

clear

public void clear()
           throws BackingStoreException

根据 Preferences.clear() 中的规范实现 clear 方法。

此实现获取首选项节点的锁，调用 keys() 以获取键的数组，并且对每个键调用 remove(String)，从而在数组上进行迭代。

指定者：

类 Preferences 中的 clear

抛出：

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

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

另请参见：

Preferences.removeNode()

putInt

public void putInt(String key,
                   int value)

根据 Preferences.putInt(String,int) 中的规范实现 putInt 方法。

此实现使用 Integer.toString(int) 将 value 转换为一个字符串，并在结果上调用 put(String,String)。

指定者：

类 Preferences 中的 putInt

参数：

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

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

抛出：

NullPointerException - 如果 key 为 null。

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

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

另请参见：

Preferences.getInt(String,int)

getInt

public int getInt(String key,
                  int def)

根据 Preferences.getInt(String,int) 中的规范实现 getInt 方法。

此实现调用 get(key, null)。如果返回值为非 null，则实现尝试使用 Integer.parseInt(String) 将其转换为 int。如果尝试成功，则此方法返回得到的值。否则返回 def。

指定者：

类 Preferences 中的 getInt

参数：

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

def - 此首选项节点不具有与 key 相关联的值或无法将该关联值解释为 int 时要返回的值。

返回：

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

抛出：

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

NullPointerException - 如果 key 为 null。

另请参见：

Preferences.putInt(String,int), Preferences.get(String,String)

putLong

public void putLong(String key,
                    long value)

根据 Preferences.putLong(String,long) 中的规范实现 putLong 方法。

此实现使用 Long.toString(long) 将 value 转换为字符串，并在结果上调用 put(String,String)。

指定者：

类 Preferences 中的 putLong

参数：

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

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

抛出：

NullPointerException - 如果 key 为 null。

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

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

另请参见：

Preferences.getLong(String,long)

getLong

public long getLong(String key,
                    long def)

根据 Preferences.getLong(String,long) 中的规范实现 getLong 方法。

此实现调用 get(key, null)。如果返回值为非 null，则实现尝试尝试使用 Long.parseLong(String) 将其转换为 long。如果尝试成功，则此方法返回得到的值。否则返回 def。

指定者：

类 Preferences 中的 getLong

参数：

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

def - 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为 long 时要返回的值。

返回：

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

抛出：

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

NullPointerException - 如果 key 为 null。

另请参见：

Preferences.putLong(String,long), Preferences.get(String,String)

putBoolean

public void putBoolean(String key,
                       boolean value)

根据 Preferences.putBoolean(String,boolean) 中的规范实现 putBoolean 方法。

此实现使用 String.valueOf(boolean) 将 value 转换为字符串，并在结果上调用 put(String,String)。

指定者：

类 Preferences 中的 putBoolean

参数：

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

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

抛出：

NullPointerException - 如果 key 为 null。

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

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

另请参见：

Preferences.getBoolean(String,boolean), Preferences.get(String,String)

getBoolean

public boolean getBoolean(String key,
                          boolean def)

根据 Preferences.getBoolean(String,boolean) 中的规范实现 getBoolean 方法。

此实现调用 get(key, null)。如果返回值为非 null，则使用 String.equalsIgnoreCase(String) 将其与 "true" 相比较。如果比较返回 true，则此调用返回 true。否则，再次使用 String.equalsIgnoreCase(String) 将初始值与 "false" 相比较。如果比较返回 true，则此调用返回 false。否则此调用返回 def。

指定者：

类 Preferences 中的 getBoolean

参数：

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

def - 此首选项节点不具有与 key 相关联的值或无法将该关联值解释为 boolean 时要返回的值。

返回：

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

抛出：

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

NullPointerException - 如果 key 为 null。

另请参见：

Preferences.get(String,String), Preferences.putBoolean(String,boolean)

putFloat

public void putFloat(String key,
                     float value)

根据 Preferences.putFloat(String,float) 中的规范实现 putFloat 方法。

此实现使用 Float.toString(float) 将 value 转换为字符串，并在结果上调用 put(String,String)。

指定者：

类 Preferences 中的 putFloat

参数：

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

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

抛出：

NullPointerException - 如果 key 为 null。

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

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

另请参见：

Preferences.getFloat(String,float)

getFloat

public float getFloat(String key,
                      float def)

根据 Preferences.getFloat(String,float) 中的规范实现 getFloat 方法。

此实现调用 get(key, null)。如果返回值为非 null，则实现尝试使用 Float.parseFloat(String) 将其转换为 float。如果尝试成功，则此方法返回得到的值。否则返回 def。

指定者：

类 Preferences 中的 getFloat

参数：

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

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

返回：

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

抛出：

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

NullPointerException - 如果 key 为 null。

另请参见：

Preferences.putFloat(String,float), Preferences.get(String,String)

putDouble

public void putDouble(String key,
                      double value)

根据 Preferences.putDouble(String,double) 中的规范实现 putDouble 方法。

此实现使用 Double.toString(double) 将 value 转换为字符串，并在结果上调用 put(String,String)。

指定者：

类 Preferences 中的 putDouble

参数：

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

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

抛出：

NullPointerException - 如果 key 为 null。

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

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

另请参见：

Preferences.getDouble(String,double)

getDouble

public double getDouble(String key,
                        double def)

根据 Preferences.getDouble(String,double) 中的规范实现 getDouble 方法。

此实现调用 get(key, null)。如果返回值为非 null，则实现尝试使用 Double.parseDouble(String) 将其转换为 double。如果尝试成功，则此方法返回得到的值。否则返回 def。

指定者：

类 Preferences 中的 getDouble

参数：

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

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

返回：

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

抛出：

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

NullPointerException - 如果 key 为 null。

另请参见：

Preferences.putDouble(String,double), Preferences.get(String,String)

putByteArray

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

根据 Preferences.putByteArray(String,byte[]) 中的规范实现 putByteArray 方法。

指定者：

类 Preferences 中的 putByteArray

参数：

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

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

抛出：

NullPointerException - 如果 key 或 value 为 null。

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

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

另请参见：

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

getByteArray

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

根据 Preferences.getByteArray(String,byte[]) 中的规范实现 getByteArray 方法。

指定者：

类 Preferences 中的 getByteArray

参数：

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

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

返回：

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

抛出：

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

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

另请参见：

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

keys

public String[] keys()
              throws BackingStoreException

根据 Preferences.keys() 中的规范实现 keys 方法。

此实现获取首选项节点的锁，检查该节点是否未被移除并调用 keysSpi()。

指定者：

类 Preferences 中的 keys

返回：

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

抛出：

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

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

childrenNames

public String[] childrenNames()
                       throws BackingStoreException

根据 Preferences.childrenNames() 中的规范实现 children 方法。

此实现获取首选项节点的锁，检查该节点是否未被移除，构造已初始化为已缓存的子节点名称（此节点“子缓存”中的子节点）的 TreeSet，调用 childrenNamesSpi() 并将所有返回的子名称添加到该 set 中。使用 toArray 方法将树 set 的元素转储到 String 数组中，并返回此数组。

指定者：

类 Preferences 中的 childrenNames

返回：

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

抛出：

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

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

另请参见：

cachedChildren()

cachedChildren

protected final AbstractPreferences[] cachedChildren()

返回此节点的所有已知未移除子节点。

返回：

此节点的所有已知未移除子节点。

parent

public Preferences parent()

根据 Preferences.parent() 中的规范实现 parent 方法。

此实现获取首选项节点的锁，检查该节点是否未被移除，并返回传递给此节点构造方法的父值。

指定者：

类 Preferences 中的 parent

返回：

首选项节点的父节点。

抛出：

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

node

public Preferences node(String path)

根据 Preferences.node(String) 中的规范实现 node 方法。

此实现获取首选项节点的锁并检查该节点是否未被移除。如果 path 为 ""，则返回此节点；如果 path 为 "/"，则返回此节点的根。如果 path 中的第一个字符不是 '/'，则此实现将 path 分解为标记，并从此节点到指定节点递归式遍历此路径，在遍历的每一个步骤都要“使用”path 中的名称和斜杠。在每一个步骤，都要锁定当前节点并为指定节点检查该节点的子缓存。如果未找到，则该名称已经过检查，以确保其长度不超过 MAX_NAME_LENGTH。然后，调用 childSpi(String) 方法并将结果存储在此节点的子缓存中。如果新创建的 Preferences 对象的 newNode 字段为 true，并且存在任一节点更改侦听器，则将由事件指派线程所处理的通知事件加入队列。

没有其他的标记时，此方法将返回在子缓存中找到的最后一个值或 childSpi 返回的值。如果在遍历过程中，连续出现两个 "/" 标记或者最后一个标记是 "/"（而不是名称），则抛出适当的 IllegalArgumentException。

如果 path 的第一个字符是 '/'（指示绝对路径名），则在将 path 分解为标记前，删除此首选项节点的锁，此方法从根（不是从此节点）开始递归式遍历此路径。该递归在其他方面与对相对路径名的描述相同。根据 locking invariant，从根节点开始遍历前删除此节点上的锁，这对于避免可能发生的死锁是至关重要的。

指定者：

类 Preferences 中的 node

参数：

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

返回：

指定的首选项节点。

抛出：

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

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

另请参见：

Preferences.flush()

nodeExists

public boolean nodeExists(String path)
                   throws BackingStoreException

根据 Preferences.nodeExists(String) 中的规范实现 nodeExists 方法。

此实现非常类似于 node(String)，不同之处是使用了 getChild(String) 而没有使用 childSpi(String)。

指定者：

类 Preferences 中的 nodeExists

参数：

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

返回：

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

抛出：

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

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

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

removeNode

public void removeNode()
                throws BackingStoreException

根据 Preferences.removeNode() 中的规范实现 removeNode() 方法。

此实现检查此节点是否为根；如果是，则抛出适当的异常。然后，它锁定此节点的父节点，并调用递归帮助器方法来遍历以此节点为根的子树。递归方法锁定其所调用的节点，检查它是否未被删除，然后确保已缓存其所有子节点：调用 childrenNamesSpi() 方法并检查每个返回的子节点名称是否已包含在子缓存中。如果没有缓存子节点，则会调用 childSpi(String) 方法为其创建一个 Preferences 实例并将此实例置于子缓存中。然后，帮助器方法在其子缓存所包含的每个节点上递归式自我调用。下一步，它调用 removeNodeSpi()，将其自身标记为已移除，并从其父节点的子缓存中自我移除。最后，如果存在任何节点更改侦听器，则其会将由事件指派线程所处理的通知事件加入队列。

注意，始终使用所有祖先来调用帮助器方法，直到锁定“未被移除的最近祖先”为止。

指定者：

类 Preferences 中的 removeNode

抛出：

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

UnsupportedOperationException - 如果在根节点上调用此方法。

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

另请参见：

Preferences.flush()

name

public String name()

根据 Preferences.name() 中的规范实现 name 方法。

此实现仅返回传递给此节点构造方法的名称。

指定者：

类 Preferences 中的 name

返回：

此首选项节点的名称（相对于其父节点）。

absolutePath

public String absolutePath()

根据 Preferences.absolutePath() 中的规范实现 absolutePath 方法。

此实现仅返回构造此节点时计算出的绝对路径名（基于传递给此节点构造方法的名称和传递给此节点祖先构造方法的名称）。

指定者：

类 Preferences 中的 absolutePath

返回：

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

isUserNode

public boolean isUserNode()

根据 Preferences.isUserNode() 中的规范实现 isUserNode 方法。

此实现将此节点的根节点（在 private 字段中存储）与 Preferences.userRoot() 返回的值相比较。如果两个对象引用相同，则此方法返回 true。

指定者：

类 Preferences 中的 isUserNode

返回：

如果此首选项节点位于用户首选项树中，则返回 true；如果其位于系统首选项树中，则返回 false。

addPreferenceChangeListener

public void addPreferenceChangeListener(PreferenceChangeListener pcl)

从类 Preferences 复制的描述

注册指定侦听器以接收此首选项节点的首选项更改事件。将首选项添加到此节点、从此节点移除首选项或者更改与首选项关联的值时都将生成首选项更改事件。（Preferences.removeNode() 方法不 生成首选项更改事件，该方法只生成节点更改事件。首选项更改事件是 由 clear 方法生成的。）

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

指定者：

类 Preferences 中的 addPreferenceChangeListener

参数：

pcl - 要添加的首选项更改侦听器。

另请参见：

Preferences.removePreferenceChangeListener(PreferenceChangeListener), Preferences.addNodeChangeListener(NodeChangeListener)

removePreferenceChangeListener

public void removePreferenceChangeListener(PreferenceChangeListener pcl)

从类 Preferences 复制的描述

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

指定者：

类 Preferences 中的 removePreferenceChangeListener

参数：

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

另请参见：

Preferences.addPreferenceChangeListener(PreferenceChangeListener)

addNodeChangeListener

public void addNodeChangeListener(NodeChangeListener ncl)

从类 Preferences 复制的描述

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

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

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

指定者：

类 Preferences 中的 addNodeChangeListener

参数：

ncl - 要添加的 NodeChangeListener。

另请参见：

Preferences.removeNodeChangeListener(NodeChangeListener), Preferences.addPreferenceChangeListener(PreferenceChangeListener)

removeNodeChangeListener

public void removeNodeChangeListener(NodeChangeListener ncl)

从类 Preferences 复制的描述

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

指定者：

类 Preferences 中的 removeNodeChangeListener

参数：

ncl - 要移除的 NodeChangeListener。

另请参见：

Preferences.addNodeChangeListener(NodeChangeListener)

putSpi

protected abstract void putSpi(String key,
                               String value)

将给定的键-值关联置于此首选项节点中。保证 key 和 value 均为非 null，并且具有合法的长度。此外，还要保证此节点未被移除。（实现者不必检查这些事情。）

利用此节点上保持的锁定调用此方法。

getSpi

protected abstract String getSpi(String key)

返回与此首选项节点上的指定键相关联的值；如果不存在此键的关联值或此时无法确定该关联值，则返回 null。保证 key 为非 null。此外，还要保证此节点未被移除。（实现者不必检查这两件事。）

一般而言，此方法在任何情形下也不应抛出异常。但是，如果它确实抛出了异常，则该异常将被解释为 null，并按 null 返回值对待。

利用此节点上保持的锁定调用此方法。

返回：

与此首选项节点上的指定键相关联的值；如果不存在此键的关联值或此时无法确定该关联值，则返回 null。

removeSpi

protected abstract void removeSpi(String key)

移除此首选项节点上指定键的关联值（如果有）。保证 key 为非 null。此外，还要保证此节点未被移除。（实现者不必检查这两件事。）

利用此节点上保持的锁定调用此方法。

removeNodeSpi

protected abstract void removeNodeSpi()
                               throws BackingStoreException

移除此首选项节点，该首选项节点及其所包含的所有首选项都将失效。进行此调用时，指定子节点不具有任何子节点（即 Preferences.removeNode() 方法以自下向上的方式重复调用此方法，在移除节点本身之前首先移除该节点的所有子节点）。

使用此节点及其父节点上保持的锁调用此方法（对 Preferences.removeNode() 的一次调用即可移除所有祖先）。

在此节点（或祖先）上调用 flush 方法之前对节点的移除不必是持久的。

如果此节点抛出 BackingStoreException，则该异常将会传播到封闭的 removeNode() 调用之外。

抛出：

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

keysSpi

protected abstract String[] keysSpi()
                             throws BackingStoreException

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

利用此节点上保持的锁调用此方法。

如果此节点抛出 BackingStoreException，则该异常将会传播到封闭的 keys() 调用之外。

返回：

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

抛出：

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

childrenNamesSpi

protected abstract String[] childrenNamesSpi()
                                      throws BackingStoreException

返回此首选项节点的子节点名称。（如果此节点不具有任何子节点，则返回数组的大小将为 0。）此方法不必返回任何已缓存节点的名称，但是这样做也没有什么坏处。

利用此节点上保持的锁调用此方法。

如果此节点抛出 BackingStoreException，则该异常将会传播到封闭的 childrenNames() 调用之外。

返回：

包含此首选项节点的子节点名称的数组。

抛出：

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

getChild

protected AbstractPreferences getChild(String nodeName)
                                throws BackingStoreException

如果指定的子节点存在，则返回该子节点；如果它不存在，则返回 null。保证 nodeName 为非 null、非空、不包含斜杠字符 ('/')，并且长度不超过 Preferences.MAX_NAME_LENGTH 个字符。此外，还要保证此节点未被移除。（如果选择重写此方法，则实现者不必检查这些事情。）

最后，保证最后一次将指定节点移除后此方法的以前调用或 childSpi(java.lang.String) 未曾返回它。换句话说，缓存的值始终在首选项中使用，以调用此方法。（如果选择重写此方法，则实现者不必维护它自己以前返回的子节点缓存。）

此实现获取首选项节点的锁，调用 childrenNames() 以获取此节点的子节点的名称数组，并在该数组上迭代，将每个子节点的名称与指定节点名称进行比较。如果子节点名称正确，则调用 childSpi(String) 方法并返回得到的节点。如果迭代完成时没有找到指定的名称，则返回 null。

参数：

nodeName - 要搜索的子节点的名称。

返回：

如果指定的子节点存在，则返回该子节点；如果它不存在，则返回 null。

抛出：

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

childSpi

protected abstract AbstractPreferences childSpi(String name)

返回此首选项节点的指定子节点；如果该子节点尚未存在，则创建它。保证 name 为非 null、非空、不包含斜杠字符 ('/')，并且长度不超过 Preferences.MAX_NAME_LENGTH 个字符。此外，还要保证此节点未被移除。（实现者不必检查这些事情。）

最后，保证最后一次将指定节点移除后此方法的以前调用或 getChild(String) 未曾返回它。换句话说，缓存的值始终在首选项中使用，以调用此方法。子类不必维护它们自己以前返回的子节点缓存。

实现者必须确保返回的节点没有被移除。如果以前移除了此节点的名称相同的子节点，则实现者必须返回一个新构建的 AbstractPreferences 节点；一旦移除，AbstractPreferences 节点便无法“再生”。

如果此方法导致创建了节点，则在此节点或其祖先之一（或子节点）上调用 flush 方法之前，不保证该节点是持久的。

利用此节点上保持的锁调用此方法。

参数：

name - 要返回的子节点的名称（相对于此首选项节点）。

返回：

指定的子节点。

toString

public String toString()

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

指定者：

类 Preferences 中的 toString

返回：

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

sync

public void sync()
          throws BackingStoreException

根据 Preferences.sync() 中的规范实现 sync 方法。

此实现调用锁定此节点的递归帮助器方法，针对该方法调用 syncSpi() ，解除此节点的锁，并在每个“缓存子节点”上递归式调用这一方法。缓存子节点是此节点的子节点，已在此 VM 中创建并且后来没有被移除。实际上，此方法对以此节点为根的“缓存子树”进行深度优先遍历，针对该 subTree 中的每个节点调用 syncSpi()，这时只有该节点是锁定的。注意，是自上向下调用 syncSpi() 的。

指定者：

类 Preferences 中的 sync

抛出：

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

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

另请参见：

flush()

syncSpi

protected abstract void syncSpi()
                         throws BackingStoreException

此方法是在此节点被锁定的情况下调用的。根据协定，此方法用于同步存储在此节点上的所有缓存首选项与存储在内部存储中的所有缓存首选项。（内部存储中不存在此节点是完全可能的，或者因为另一个 VM 删除了它或者因为还没有创建它。）注意，此方法不 应同步此节点的所有子节点中的首选项。如果内部存储自然地同步了整个子树，则鼓励实现者重写 sync()，而不是仅仅重写此方法。

如果此节点抛出 BackingStoreException，则该异常将会传播到封闭的 sync() 调用之外。

抛出：

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

flush

public void flush()
           throws BackingStoreException

根据 Preferences.flush() 中的规范实现 flush 方法。

此实现调用锁定此节点的递归帮助器方法，针对该方法调用 flushSpi()，解除此节点的锁，并在每个“缓存子节点”上递归式调用这一方法。缓存子节点是此节点的子节点，已在此 VM 中创建并且后来没有被移除。实际上，此方法对以此节点为根的“缓存子树”进行深度优先遍历，针对该 subTree 中的每个节点调用 flushSpi()，这时只有该节点是锁定的。注意，是自上向下调用 flushSpi() 的。

如果在已经使用 removeNode() 方法移除的节点上调用此方法，则会在此节点（而非其他节点）上调用 flushSpi()。

指定者：

类 Preferences 中的 flush

抛出：

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

另请参见：

flush()

flushSpi

protected abstract void flushSpi()
                          throws BackingStoreException

此方法是在此节点被锁定的情况下调用的。根据协定，此方法用于强制执行从此首选项节点到内部存储内容的缓存更改，以保证其持久性。（内部存储中不存在此节点是完全可能的，或者因为另一个 VM 删除了它或者因为还没有创建它。）注意，此方法不 应刷新此节点的所有子节点中的首选项。如果内部存储自然地刷新了整个子树，则鼓励实现者重写 flush()，而不是仅仅重写此方法。

如果此节点抛出 BackingStoreException，则该异常将会传播到封闭的 flush() 调用之外。

抛出：

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

isRemoved

protected boolean isRemoved()

当且仅当已经使用 removeNode() 方法移除此节点（或其祖先）时才返回 true。此方法在返回用于跟踪此状态的 private 字段内容前锁定此节点。

返回：

当且仅当已经使用 removeNode() 方法移除了此节点（或其祖先）时才返回 true。

exportNode

public void exportNode(OutputStream os)
                throws IOException,
                       BackingStoreException

根据 Preferences.exportNode(OutputStream) 中的规范实现 exportNode 方法。

指定者：

类 Preferences 中的 exportNode

参数：

os - 根据其内容发出 XML 文档的输出流。

抛出：

IOException - 如果写入指定的输出流导致一个 IOException。

BackingStoreException - 如果无法从内部存储读取首选项数据。

另请参见：

Preferences.importPreferences(InputStream)

exportSubtree

public void exportSubtree(OutputStream os)
                   throws IOException,
                          BackingStoreException

根据 Preferences.exportSubtree(OutputStream) 中的规范实现 exportSubtree 方法。

指定者：

类 Preferences 中的 exportSubtree

参数：

os - 根据其内容发出 XML 文档的输出流。

抛出：

IOException - 如果写入指定的输出流导致一个 IOException。

BackingStoreException - 如果无法从内部存储读取首选项数据。

另请参见：

Preferences.importPreferences(InputStream), Preferences.exportNode(OutputStream)

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