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

---

字段摘要
protected  Object	lock           使用其监视器锁定此节点的对象。
protected  boolean	newNode           如果在创建此对象前内部存储中不存在此节点，则该字段为 true。

 

从类 java.util.prefs.Preferences 继承的字段
MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

 

构造方法摘要
protected	AbstractPreferences(AbstractPreferences parent, String name)           用指定的父节点和与其父节点相关的指定名称创建首选项节点。

 

方法摘要
String	absolutePath()           根据 Preferences.absolutePath() 中的规范实现 absolutePath 方法。
void	addNodeChangeListener(NodeChangeListener ncl)           注册指定侦听器以接收此节点的节点更改事件。
void	addPreferenceChangeListener(PreferenceChangeListener pcl)           注册指定侦听器以接收此首选项节点的首选项更改事件。
protected  AbstractPreferences[]	cachedChildren()           返回此节点的所有已知未移除子节点。
String[]	childrenNames()           根据 Preferences.childrenNames() 中的规范实现 children 方法。
protected abstract  String[]	childrenNamesSpi()           返回此首选项节点的子节点名称。
protected abstract  AbstractPreferences	childSpi(String name)           返回此首选项节点的指定子节点；如果该子节点尚未存在，则创建它。
void	clear()           根据 Preferences.clear() 中的规范实现 clear 方法。
void	exportNode(OutputStream os)           根据 Preferences.exportNode(OutputStream) 中的规范实现 exportNode 方法。
void	exportSubtree(OutputStream os)           根据 Preferences.exportSubtree(OutputStream) 中的规范实现 exportSubtree 方法。
void	flush()           根据 Preferences.flush() 中的规范实现 flush 方法。
protected abstract  void	flushSpi()           此方法是在此节点被锁定的情况下调用的。
String	get(String key, String def)           根据 Preferences.get(String,String) 中的规范实现 get 方法。
boolean	getBoolean(String key, boolean def)           根据 Preferences.getBoolean(String,boolean) 中的规范实现 getBoolean 方法。
byte[]	getByteArray(String key, byte[] def)           根据 Preferences.getByteArray(String,byte[]) 中的规范实现 getByteArray 方法。
protected  AbstractPreferences	getChild(String nodeName)           如果指定的子节点存在，则返回该子节点；如果它不存在，则返回 null。
double	getDouble(String key, double def)           根据 Preferences.getDouble(String,double) 中的规范实现 getDouble 方法。
float	getFloat(String key, float def)           根据 Preferences.getFloat(String,float) 中的规范实现 getFloat 方法。
int	getInt(String key, int def)           根据 Preferences.getInt(String,int) 中的规范实现 getInt 方法。
long	getLong(String key, long def)           根据 Preferences.getLong(String,long) 中的规范实现 getLong 方法。
protected abstract  String	getSpi(String key)           返回与此首选项节点上的指定键相关联的值；如果不存在此键的关联值或此时无法确定该关联值，则返回 null。
protected  boolean	isRemoved()           当且仅当已经使用 removeNode() 方法移除此节点（或其祖先）时才返回 true。
boolean	isUserNode()           根据 Preferences.isUserNode() 中的规范实现 isUserNode 方法。
String[]	keys()           根据 Preferences.keys() 中的规范实现 keys 方法。
protected abstract  String[]	keysSpi()           返回在此首选项节点中具有关联值的所有键。
String	name()           根据 Preferences.name() 中的规范实现 name 方法。
Preferences	node(String path)           根据 Preferences.node(String) 中的规范实现 node 方法。
boolean	nodeExists(String path)           根据 Preferences.nodeExists(String) 中的规范实现 nodeExists 方法。
Preferences	parent()           根据 Preferences.parent() 中的规范实现 parent 方法。
void	put(String key, String value)           根据 Preferences.put(String,String) 中的规范实现 put 方法。
void	putBoolean(String key, boolean value)           根据 Preferences.putBoolean(String,boolean) 中的规范实现 putBoolean 方法。
void	putByteArray(String key, byte[] value)           根据 Preferences.putByteArray(String,byte[]) 中的规范实现 putByteArray 方法。
void	putDouble(String key, double value)           根据 Preferences.putDouble(String,double) 中的规范实现 putDouble 方法。
void	putFloat(String key, float value)           根据 Preferences.putFloat(String,float) 中的规范实现 putFloat 方法。
void	putInt(String key, int value)           根据 Preferences.putInt(String,int) 中的规范实现 putInt 方法。
void	putLong(String key, long value)           根据 Preferences.putLong(String,long) 中的规范实现 putLong 方法。
protected abstract  void	putSpi(String key, String value)           将给定的键-值关联置于此首选项节点中。
void	remove(String key)           根据 Preferences.remove(String) 中的规范实现 remove(String) 方法。
void	removeNode()           根据 Preferences.removeNode() 中的规范实现 removeNode() 方法。
void	removeNodeChangeListener(NodeChangeListener ncl)           移除指定 NodeChangeListener，使其不再接收更改事件。
protected abstract  void	removeNodeSpi()           移除此首选项节点，该首选项节点及其所包含的所有首选项都将失效。
void	removePreferenceChangeListener(PreferenceChangeListener pcl)           移除指定首选项更改侦听器，使其不再接收首选项更改事件。
protected abstract  void	removeSpi(String key)           移除此首选项节点上指定键的关联值（如果有）。
void	sync()           根据 Preferences.sync() 中的规范实现 sync 方法。
protected abstract  void	syncSpi()           此方法是在此节点被锁定的情况下调用的。
String	toString()           返回此首选项节点的绝对路径名称。

 

从类 java.util.prefs.Preferences 继承的方法
importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

 

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

 

字段详细信息

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)