Java java.util.prefs 类 AbstractPreferences（JDK5）

所有类

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)