©
本文檔使用 php中文網手册 發布
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
java.lang.Object java.util.prefs.Preferences
public abstract class Preferences
首选项数据的层次结构 collection 中的节点。此类允许应用程序存储和获取用户和系统首选项以及配置数据。此数据持久存储在依赖于实现的内部存储中。典型实现包括纯文本文件、特定于操作系统的注册表、目录服务器和 SQL 数据库。此类的用户无需关注内部存储的细节。
有两个独立的首选项节点树,一个用于用户首选项,一个用于系统首选项。每个用户都有一个单独的用户首选项树,而在给定系统中,所有用户都共享同一系统首选项树。对“用户”和“系统”的精确描述因实现而异。用户首选项树中存储的典型信息可能包括特定应用程序的字体选择、颜色选择和首选窗口的位置及大小。系统首选项树中存储的典型信息可能包括应用程序的安装配置数据。
使用类似的方式将首选项树中的节点命名为层次结构文件系统中的目录。首选项树的每个节点都具有一个节点名(不必是唯一的)、一个唯一的绝对路径名 和一个相对于 每个祖先(包括它自己)的路径名。
根节点的节点名为空字符串 ("")。每个其他节点的节点名可以在创建时任意指定。此名称的唯一限制是,它不能是空字符串,也不能包含斜杠字符 ('/')。
根节点的绝对路径名为 "/"。根节点的子节点的绝对路径名是 "/" + <节点名>。所有其他节点的绝对路径名是<父节点的绝对路径名> + "/" + <节点名>。注意,所有绝对路径名的第一个字符都是斜杠。
节点 n 相对于其祖先 a 的路径名只是为了形成 n 的绝对路径名,而必须添加到 a 的绝对路径名的字符串,同时移除开头的斜杠字符(如果存在)。注意:
最后注意:
修改首选项数据的所有方法都允许进行异步操作;它们可能立即返回,但是更改最终将传播到持久内部存储中,其延迟取决于实现。可以使用 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);该系统 URI 仅作为一个唯一标识 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 实现的位置如下:
如果定义了系统属性 java.util.prefs.PreferencesFactory,则该属性名就会用作实现 PreferencesFactory 接口的类的完全限定名。加载并实例化该类;如果此进程失败,则抛出未指定的错误。
如果在对系统类加载器
可见的 jar 文件中安装了 PreferencesFactory 实现类文件,并且该 jar 文件在资源目录 META-INF/services 中包含名为 java.util.prefs.PreferencesFactory 的提供者配置文件,则采用在该文件中指定的第一个类名称。如果提供了一个以上这样的 jar 文件,则使用找到的第一个文件。加载并实例化该类;如果此进程失败,则抛出未指定的错误。
最后,如果既没有提供上述系统属性也没有提供扩展 jar 文件,则加载和实例化底层平台的系统级默认 PreferencesFactory 实现。
字段摘要 | |
---|---|
static int |
MAX_KEY_LENGTH
允许作为键的字符串最大长度(80 个字符)。 |
static int |
MAX_NAME_LENGTH
节点名的最大长度(80 个字符)。 |
static int |
MAX_VALUE_LENGTH
允许作为值的字符串最大长度(8192 个字符)。 |
构造方法摘要 | |
---|---|
protected |
Preferences()
单独的构造方法。 |
方法摘要 | |
---|---|
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)
返回与此首选项节点中指定的键相关联的、由字符串表示的 boolean 值。 |
abstract byte[] |
getByteArray(String key,
byte[] def)
返回与此首选项节点中指定键相关联的、由字符串表示的字节数组。 |
abstract double |
getDouble(String key,
double def)
返回与此首选项节点中指定的键相关联的、由字符串表示的 double 值。 |
abstract float |
getFloat(String key,
float def)
返回与此首选项节点中指定的键相关联的、由字符串表示的 float 值。 |
abstract int |
getInt(String key,
int def)
返回与此首选项节点中与指定键相关联的、由字符串表示的 int 值。 |
abstract long |
getLong(String key,
long def)
返回与此首选项节点中指定的键相关联的、由字符串表示的 long 值。 |
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)
将表示指定 boolean 值的字符串与此首选项节点中的指定键相关联。 |
abstract void |
putByteArray(String key,
byte[] value)
将表示指定字节数组的字符串与此首选项节点中的指定键相关联。 |
abstract void |
putDouble(String key,
double value)
将表示指定 double 值的字符串与此首选项节点中的指定键相关联。 |
abstract void |
putFloat(String key,
float value)
将表示指定 float 值的字符串与此首选项节点中的指定键相关联。 |
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)
从系统首选项树(根据约定,它与指定类的包相关联)返回首选项节点。 |
static Preferences |
systemRoot()
返回系统的根首选项节点。 |
abstract String |
toString()
返回此首选项节点的字符串表示形式,与通过表达式:(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 计算的结果一样。 |
static Preferences |
userNodeForPackage(Class<?> c)
从调用用户首选项树(根据约定,它与指定类的包相关联)返回首选项节点。 |
static Preferences |
userRoot()
返回调用用户的根首选项节点。 |
从类 java.lang.Object 继承的方法 |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
字段详细信息 |
---|
public static final int MAX_KEY_LENGTH
public static final int MAX_VALUE_LENGTH
public static final int MAX_NAME_LENGTH
构造方法详细信息 |
---|
protected Preferences()
方法详细信息 |
---|
public static Preferences userNodeForPackage(Class<?> c)
此约定不适用于未命名的包,未命名包的关联首选项节点是 <unnamed>。此节点只是为了方便程序的早期开发(而非长期使用)而存在的,它不属于任何包,只用于“一次性”程序。在此节点中不应该存储有价值的数据,因为使用它的所有程序都可以共享它。
希望访问与其包有关的首选项类 Foo 可以获得以下首选项节点:
static Preferences prefs = Preferences.userNodeForPackage(Foo.class);此语句消除了使用字符串描述首选项节点的需求,从而降低了发生运行时故障的可能性。(如果类名称拼写错误,则通常会导致编译时错误。)
调用此方法将导致返回节点及其祖先的创建(如果它们不存在)。如果在此调用之前返回的节点不存在,那么在对返回节点(或者其某个祖先或子节点)调用 flush 方法之前,不能保证由此调用所创建的节点及其所有祖先是永久性的。
c
- 用户首选项节点需要其包的类。
NullPointerException
- 如果 c 为 null。
SecurityException
- 如果安全管理器存在并且拒绝 RuntimePermission("preferences")。RuntimePermission
public static Preferences systemNodeForPackage(Class<?> c)
此约定不适用于未命名的包,未命名包的关联首选项节点是 <unnamed>。此节点只是为了方便程序的早期开发(而非长期使用)而存在的,它不属于任何包,只用于“一次性”程序。在此节点中不应该存储有价值的数据,因为使用它的所有程序都可以共享它。
希望访问与其包有关的首选项类 Foo 可以获得以下首选项节点:
static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);此语句消除了使用字符串描述首选项节点的需求,从而降低了发生运行时故障的可能性。(如果类名称拼写错误,则通常会导致编译时错误。)
调用此方法将导致返回节点及其祖先的创建(如果它们不存在)。如果在此调用之前返回的节点不存在,那么在对返回节点(或者其某个祖先或子节点)调用 flush 方法之前,不能保证由此调用所创建的节点及其所有祖先是永久性的。
c
- 系统首选项节点需要其包的类。
NullPointerException
- 如果 c 为 null。
SecurityException
- 如果安全管理器存在并且拒绝 RuntimePermission("preferences")。RuntimePermission
public static Preferences userRoot()
SecurityException
- 如果安全管理器存在并且拒绝 RuntimePermission("preferences")。RuntimePermission
public static Preferences systemRoot()
SecurityException
- 如果安全管理器存在并且拒绝 RuntimePermission("preferences")。RuntimePermission
public abstract void put(String key, String value)
key
- 指定的 value 将要关联的键。value
- 指定的 key 将要关联的值。
NullPointerException
- 如果 key 或 value 为 null。
IllegalArgumentException
- 如果 key.length() 超过 MAX_KEY_LENGTH 或者 value.length 超过 MAX_VALUE_LENGTH。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。public abstract String get(String key, String def)
有些实现可能将默认值存储在其内部存储中。如果不存在与指定键相关联的值,而只有存储的默认值,则系统优先返回存储的默认值(而不是指定的默认值)。
key
- 要返回其相关值的键。def
- 此首选项节点不具有与 key 相关联的值时所要返回的值。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。
NullPointerException
- 如果 key 为 null。(值 null 用于 def 是 允许的。)public abstract void remove(String key)
如果此实现支持存储的默认值,并且指定的首选项存在这样的默认值,则此调用将“公开”存储的默认值,这表示对 get 的后续调用将返回它。
key
- 从首选项节点中移除其映射关系的键。
NullPointerException
- 如果 key 为 null。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。public abstract void clear() throws BackingStoreException
如果此实现支持存储的默认值,并且首选项层次结构中的这一节点包含这样的默认值,则此调用将“公开”存储的默认值,这表示对 get 的后续调用将返回它。
BackingStoreException
- 如果由于内部存储的故障或未能通信而无法完成此操作。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。removeNode()
public abstract void putInt(String key, int value)
Integer.toString(int)
时将返回的字符串。此方法与 getInt(java.lang.String, int)
一起使用。
key
- 要与字符串形式的 value 相关联的键。value
- 要与 key 相关联的字符串形式的值。
NullPointerException
- 如果 key 为 null。
IllegalArgumentException
- 如果 key.length() 超过 MAX_KEY_LENGTH。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。getInt(String,int)
public abstract int getInt(String key, int def)
Integer.parseInt(String)
转换为整数。如果不存在与该键相关联的值,内部存储不可用,或者传递关联值时 Integer.parseInt(String) 抛出 NumberFormatException
,则返回指定的默认值。此方法与 putInt(java.lang.String, int)
一起使用。
如果该实现支持存储的默认值,并且这样的默认值存在且可访问,而且可以使用 Integer.parseInt 将其转换为 int,则优先返回此 int(而不是指定默认值)。
key
- 要作为 int 返回其关联值的键。def
- 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为 int 或者内部存储不可访问时要返回的值。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。
NullPointerException
- 如果 key 为 null。putInt(String,int)
,
get(String,String)
public abstract void putLong(String key, long value)
Long.toString(long)
时将返回的字符串。此方法与 getLong(java.lang.String, long)
一起使用。
key
- 要与字符串形式的 value 相关联的键。value
- 要与 key 相关联的字符串形式的值。
NullPointerException
- 如果 key 为 null。
IllegalArgumentException
- 如果 key.length() 超过 MAX_KEY_LENGTH。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。getLong(String,long)
public abstract long getLong(String key, long def)
Long.parseLong(String)
转换为 long。如果不存在与该键相关联的值,内部存储不可用,或者传递关联值时 Long.parseLong(String) 抛出 NumberFormatException
,则返回指定的默认值。此方法与 putLong(java.lang.String, long)
一起使用。
如果该实现支持存储的默认值,这样的默认值存在且可访问,并且可以使用 Long.parseLong 转换为 long,则优先返回此 long(而不是指定默认值)。
key
- 要作为 long 返回其关联值的键。def
- 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为 long 或者内部存储不可访问时要返回的值。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。
NullPointerException
- 如果 key 为 null。putLong(String,long)
,
get(String,String)
public abstract void putBoolean(String key, boolean value)
getBoolean(java.lang.String, boolean)
一起使用。
key
- 要与字符串形式的 value 相关联的键。value
- 要与 key 相关联的字符串形式的值。
NullPointerException
- 如果 key 为 null。
IllegalArgumentException
- 如果 key.length() 超过 MAX_KEY_LENGTH。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。getBoolean(String,boolean)
,
get(String,String)
public abstract boolean getBoolean(String key, boolean def)
putBoolean(java.lang.String, boolean)
一起使用。
如果不存在与该键相关联的值或者内部存储不可访问或者关联值是 "true" 或 "false"(不区分大小写)之外的其他值,则返回指定默认值。
如果该实现支持存储的默认值,这样的默认值存在且可访问,则优先使用存储的默认值(而不是指定默认值);但如果存储的默认值是 "true" 或 "false"(不区分大小写)之外的其他值,在这种情况下,则使用指定默认值。
key
- 要作为 boolean 返回其关联值的键。def
- 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为 boolean 或者内部存储不可访问时要返回的值。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。
NullPointerException
- 如果 key 为 null。get(String,String)
,
putBoolean(String,boolean)
public abstract void putFloat(String key, float value)
Float.toString(float)
时将返回的字符串。此方法与 getFloat(java.lang.String, float)
一起使用。
key
- 要与字符串形式的 value 相关联的键。value
- 要与 key 相关联的字符串形式的值。
NullPointerException
- 如果 key 为 null。
IllegalArgumentException
- 如果 key.length() 超过 MAX_KEY_LENGTH。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。getFloat(String,float)
public abstract float getFloat(String key, float def)
Float.parseFloat(String)
转换为整数。如果不存在与该键相关联的值,内部存储不可用,或者传递关联值时 Float.parseFloat(String) 抛出 NumberFormatException
,则返回指定的默认值。此方法与 putFloat(java.lang.String, float)
一起使用。
如果该实现支持存储的默认值,这样的默认值存在且可访问,并且可以使用 Float.parseFloat 转换为 float,则优先返回此 float(而不是指定默认值)。
key
- 要作为 float 返回其关联值的键。def
- 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为 float 或者内部存储不可访问时要返回的值。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。
NullPointerException
- 如果 key 为 null。putFloat(String,float)
,
get(String,String)
public abstract void putDouble(String key, double value)
Double.toString(double)
时将返回的字符串。此方法与 getDouble(java.lang.String, double)
一起使用。
key
- 要与字符串形式的 value 相关联的键。value
- 要与 key 相关联的字符串形式的值。
NullPointerException
- 如果 key 为 null。
IllegalArgumentException
- 如果 key.length() 超过 MAX_KEY_LENGTH。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。getDouble(String,double)
public abstract double getDouble(String key, double def)
Double.parseDouble(String)
转换为整数。如果不存在与该键相关联的值,内部存储不可用,或者传递关联值时 Double.parseDouble(String) 抛出 NumberFormatException
,则返回指定的默认值。此方法与 putDouble(java.lang.String, double)
一起使用。
如果该实现支持存储的默认值,这样的默认值存在且可访问,并且可以使用 Double.parseDouble 转换为 double,则优先返回此 double(而不是指定默认值)。
key
- 要作为 double 返回其关联值的键。def
- 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为 double 或者内部存储不可访问时要返回的值。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。
NullPointerException
- 如果 key 为 null。putDouble(String,double)
,
get(String,String)
public abstract void putByteArray(String key, byte[] value)
getByteArray(java.lang.String, byte[])
一起使用。
key
- 要与字符串形式的 value 相关联的键。value
- 要与 key 相关联的字符串形式的值。
NullPointerException
- 如果 key 或 value 为 null。
IllegalArgumentException
- 如果 key.length() 超过 MAX_KEY_LENGTH 或者 value.length 超过 MAX_VALUE_LENGTH*3/4。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。getByteArray(String,byte[])
,
get(String,String)
public abstract byte[] getByteArray(String key, byte[] def)
putByteArray(java.lang.String, byte[])
一起使用。
如果没有与该键相关联的值或者内部存储不可访问或者关联值不是有效的 Base64 编码字节数组(根据上面的定义),则返回指定默认值。
如果该实现支持存储的默认值,这样的默认值存在且可访问,则优先使用存储的默认值(而不是指定默认值);但如果存储的默认值不是有效的 Base64 编码的字节数组(根据上面的定义),在这种情况下,则使用指定默认值。
key
- 要作为字节数组返回其关联值的键。def
- 此首选项节点不具有与 key 相关联的值或者无法将该关联值解释为字节数组或者内部存储不可访问时要返回的值。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。
NullPointerException
- 如果 key 为 null。(值 null 用于 def 是 允许的。)get(String,String)
,
putByteArray(String,byte[])
public abstract String[] keys() throws BackingStoreException
如果该实现支持存储的默认值,此节点中存在这样的默认值并且没有被显式首选项重写,则在数组中除了返回所有显式首选项外,还返回默认值。
BackingStoreException
- 如果由于内部存储的故障或未能通信而无法完成此操作。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。public abstract String[] childrenNames() throws BackingStoreException
BackingStoreException
- 如果由于内部存储的故障或未能通信而无法完成此操作。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。public abstract Preferences parent()
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。public abstract Preferences node(String pathName)
如果在此调用之前返回的节点不存在,那么在对返回节点(或者其某个祖先或子节点)调用 flush 方法之前,不能保证由此调用所创建的节点及其所有祖先是永久性的。
pathName
- 要返回的首选项节点的路径名。
IllegalArgumentException
- 如果路径名无效(即它包含多个连续的斜杠字符,或者以斜杠字符结束并且大于一个 long 字符)。
NullPointerException
- 如果路径名为 null。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。flush()
public abstract boolean nodeExists(String pathName) throws BackingStoreException
如果已经使用 removeNode()
方法移除了此节点(及其祖先),则调用此方法也是 合法的,只是需要使用路径名 "";该调用返回 false。因此,可以使用语句 p.nodeExists("") 测试 p 是否已被移除。
pathName
- 要检查其是否存在的节点路径名。
BackingStoreException
- 如果由于内部存储的故障或未能通信而无法完成此操作。
IllegalArgumentException
- 如果路径名无效(即它包含多个连续的斜杠字符,或者以斜杠字符结束并且大于一个 long 字符)。
NullPointerException
- 如果路径名为 null。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先),并且 pathName 不是空字符串 ("")。public abstract void removeNode() throws BackingStoreException
name()
、absolutePath()
、isUserNode()
、flush()
或 nodeExists("")
之外的任何方法都将失败并抛出 IllegalStateException。(节点被移除后,在该节点上仍然可以调用在 Object
上定义的方法,并且不抛出 IllegalStateException。)
在此节点(或其祖先)上调用 flush 方法之前移除操作不保证是持久的。
如果此实现支持存储的默认值,则移除节点将公开此节点的或此节点下的所有存储的默认值。因此,对此节点的路径名后续调用 nodeExists 将返回 true,而对此路径名后续调用 node 则返回表示首选项和/或子首选项的非空 collection 的(不同)Preferences 实例。
BackingStoreException
- 如果由于内部存储的故障或未能通信而无法完成此操作。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。
UnsupportedOperationException
- 如果在根节点上调用此方法。flush()
public abstract String name()
public abstract String absolutePath()
public abstract boolean isUserNode()
public abstract String toString()
Object
中的 toString
public abstract void flush() throws BackingStoreException
实现可以在任何时间随意将更改刷新到持久存储中。它们无需等待此方法的调用。
对新创建的节点进行刷新后,它就变得持久了,同时其所有尚未变得持久的祖先(和子节点)也将变得持久。但是注意,不 保证其祖先中的所有首选项值的更改能变得持久。
如果在已经使用 removeNode()
方法移除的节点上调用此方法,则会在此节点(而非其他节点)上调用 flushSpi()。
BackingStoreException
- 如果由于内部存储的故障或未能通信而无法完成此操作。sync()
public abstract void sync() throws BackingStoreException
BackingStoreException
- 如果由于内部存储的故障或未能通信而无法完成此操作。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。flush()
public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)
removeNode()
方法不 生成首选项更改事件,该方法只生成节点更改事件。首选项更改事件是 由 clear 方法生成的。)
尽管有些实现可以为在 JVM 外进行的更改生成事件,但只有在已注册侦听器所在的 JVM 中所作的更改才能得到保证。事件可能是更改变得持久之前生成的。在此节点的子节点中修改首选项时不生成事件;需要此类事件的调用者必须在每个子节点中注册。
pcl
- 要添加的首选项更改侦听器。
NullPointerException
- 如果 pcl 为 null。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。removePreferenceChangeListener(PreferenceChangeListener)
,
addNodeChangeListener(NodeChangeListener)
public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)
pcl
- 要移除的首选项更改侦听器。
IllegalArgumentException
- 如果 pcl 不是此节点上的已注册首选项更改侦听器。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。addPreferenceChangeListener(PreferenceChangeListener)
public abstract void addNodeChangeListener(NodeChangeListener ncl)
removeNode()
调用即可产生多个节点更改事件,每个都对应于以已移除节点为根的子树中的一个节点。)
尽管有些实现可以为在 JVM 外进行的更改生成事件,但只有在注册侦听器所在的 JVM 中所作的更改才能得到保证。事件可能是更改变得持久之前生成的。添加或移除此节点的间接子节点时不生成事件;需要此类事件的调用者必须在每个子节点中注册。
节点的创建难以得到保证。因为节点是基于访问隐式创建的,实现无法确定访问前内部存储中是否存在子节点(例如,内部存储不可访问或已缓存信息过期)。在这些情形下,实现既不要求生成节点更改事件也不禁止这样做。
ncl
- 要添加的 NodeChangeListener。
NullPointerException
- 如果 ncl 为 null。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。removeNodeChangeListener(NodeChangeListener)
,
addPreferenceChangeListener(PreferenceChangeListener)
public abstract void removeNodeChangeListener(NodeChangeListener ncl)
ncl
- 要移除的 NodeChangeListener。
IllegalArgumentException
- 如果 ncl 不是此节点上的已注册 NodeChangeListener。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。addNodeChangeListener(NodeChangeListener)
public abstract void exportNode(OutputStream os) throws IOException, BackingStoreException
该 XML 文档具有以下 DOCTYPE 声明:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">使用 UTF-8 字符编码。
此方法对一般规则而言是个例外,在此类中并发执行多个方法将产生等效于某些顺序执行的结果。如果由于调用此方法而同时修改了此节点的多个首选项,则导出的首选项由该节点所包含的首选项的“模糊快照”组成;有些并发修改可能在导出数据中得到了反映,而有些则不然。
os
- 根据其内容发出 XML 文档的输出流。
IOException
- 如果写入指定的输出流导致 IOException。
BackingStoreException
- 如果无法从内部存储读取首选项数据。
IllegalStateException
- 如果已经使用 removeNode()
方法移除了此节点(或其祖先)。importPreferences(InputStream)
public abstract void exportSubtree(OutputStream os) throws IOException, BackingStoreException
该 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)
public static void importPreferences(InputStream is) throws IOException, InvalidPreferencesFormatException
该 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
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。