public abstract class AbstractPreferences
extends Preferences
java.lang.Object | ||
↳ | java.util.prefs.Preferences | |
↳ | java.util.prefs.AbstractPreferences |
这个类提供了 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 ,因为他们通常可以遵守他们的合同,即使后备商店不可用。 这是事实,因为他们没有返回任何信息,并且在后续调用flush()
或sync()
之前,它们的效果不需要变为永久的。 一般来说,这些SPI方法不应该抛出异常。 在一些实现中,可能存在这些调用甚至不能排队所请求的操作以供后续处理的情况。 即使在这种情况下,通常最好忽略调用和返回,而不是抛出异常。 但是,在这种情况下,所有后续调用flush()和sync都应该返回false ,因为返回true意味着所有先前的操作已成功永久化。
有一种情况下, putSpi, removeSpi and childSpi 应该抛出一个异常:如果调用者在底层操作系统上缺乏执行请求操作的足够特权。 例如,如果非特权用户尝试修改系统首选项,则会出现在大多数系统上。 (所需特权因实现而异,在某些实现中,他们有权修改文件系统中某个目录的内容;而另一些则有权修改注册表中某些密钥的内容。)在这些情况下,让程序继续执行通常是不可取的,就好像这些操作在以后会永久执行一样。 尽管在这些情况下实现并不需要抛出异常,但是我们鼓励他们这样做。 一个SecurityException
将是适当的。
大多数SPI方法都要求实现在首选项节点上读取或写入信息。 实现者应该注意另一个虚拟机可能已经从后备存储中同时删除了这个节点。 如果节点已被删除,重新创建节点是实施的责任。
实现注意事项:在Sun的默认Preferences实现中,用户的身份从底层操作系统继承而来,并且在虚拟机的生命周期内不会更改。 应当认识到,服务器端Preferences层的实现可能有来自请求的用户的身份变化请求,通过使用静态的隐式传递给Preferences种方法ThreadLocal
实例。 强烈建议此类实现的作者在访问首选项时确定用户(例如通过get(String, String)
或put(String, String)
方法),而不是将用户与每个Preferences实例永久关联。 后者的行为与正常Preferences使用冲突,并会导致很大的混乱。
也可以看看:
Inherited constants |
---|
From class java.util.prefs.Preferences
|
Fields |
|
---|---|
protected final Object |
lock 其监视器用于锁定此节点的对象。 |
protected boolean |
newNode 如果此节点在创建此对象之前不存在于后备存储中,则此字段应为 true 。 |
Protected constructors |
|
---|---|
AbstractPreferences(AbstractPreferences parent, String name) 使用指定的父项和指定的名称相对于其父项创建首选项节点。 |
Public methods |
|
---|---|
String |
absolutePath() 实现 absolutePath方法按照在本说明书中 |
void |
addNodeChangeListener(NodeChangeListener ncl) 注册指定的侦听器以接收此节点的 节点更改事件 。 |
void |
addPreferenceChangeListener(PreferenceChangeListener pcl) 注册指定的侦听器以接收此首选项节点的 首选项更改事件 。 |
String[] |
childrenNames() 实现 children方法按照在本说明书中 |
void |
clear() 实现 clear方法按照在本说明书中 |
void |
exportNode(OutputStream os) 实现 exportNode方法按照在本说明书中 |
void |
exportSubtree(OutputStream os) 实现 exportSubtree方法按照在本说明书中 |
void |
flush() 实现 flush方法按照在本说明书中 |
String |
get(String key, String def) 实现 get方法按照在本说明书中 |
boolean |
getBoolean(String key, boolean def) 实现 getBoolean方法按照在本说明书中 |
byte[] |
getByteArray(String key, byte[] def) 实现 getByteArray方法按照在本说明书中 |
double |
getDouble(String key, double def) 实现 getDouble方法按照在本说明书中 |
float |
getFloat(String key, float def) 实现 getFloat方法按照在本说明书中 |
int |
getInt(String key, int def) 实现 getInt方法按照在本说明书中 |
long |
getLong(String key, long def) 实现 getLong方法按照在本说明书中 |
boolean |
isUserNode() 实现 isUserNode方法按照在本说明书中 |
String[] |
keys() 实现 keys方法按照在本说明书中 |
String |
name() 实现 name方法按照在本说明书中 |
Preferences |
node(String path) 实现 node方法按照在本说明书中 |
boolean |
nodeExists(String path) 实现 nodeExists方法按照在本说明书中 |
Preferences |
parent() 实现 parent方法按照在本说明书中 |
void |
put(String key, String value) 实现 put方法按照在本说明书中 |
void |
putBoolean(String key, boolean value) 实现 putBoolean方法按照在本说明书中 |
void |
putByteArray(String key, byte[] value) 实现 putByteArray方法按照在本说明书中 |
void |
putDouble(String key, double value) 实现 putDouble方法按照在本说明书中 |
void |
putFloat(String key, float value) 实现 putFloat方法按照在本说明书中 |
void |
putInt(String key, int value) 实现 putInt方法按照在本说明书中 |
void |
putLong(String key, long value) 实现 putLong方法按照在本说明书中 |
void |
remove(String key) 实现 remove(String)方法按照在本说明书中 |
void |
removeNode() 实现 removeNode()方法按照在本说明书中 |
void |
removeNodeChangeListener(NodeChangeListener ncl) 删除指定的 NodeChangeListener ,因此它不再收到更改事件。 |
void |
removePreferenceChangeListener(PreferenceChangeListener pcl) 删除指定的首选项更改侦听器,使其不再接收首选项更改事件。 |
void |
sync() 实现 sync方法按照在本说明书中 |
String |
toString() 返回此首选项节点的绝对路径名称。 |
Protected methods |
|
---|---|
final AbstractPreferences[] |
cachedChildren() 返回此节点的所有已知未清除的子节点。 |
abstract AbstractPreferences |
childSpi(String name) 返回此首选项节点的命名子节点,如果它尚不存在,则创建它。 |
abstract String[] |
childrenNamesSpi() 返回此首选项节点的子项名称。 |
abstract void |
flushSpi() 此方法在此节点被锁定时调用。 |
AbstractPreferences |
getChild(String nodeName) 返回指定的子项(如果存在);如果不存在,则返回 null 。 |
abstract String |
getSpi(String key) 返回与此首选项节点上的指定键相关联的值 ;如果此键不存在关联,则 返回null ,否则此关联无法确定。 |
boolean |
isRemoved() 返回 true如果此节点(或其祖先)已经被除去的 |
abstract String[] |
keysSpi() 返回此首选项节点中具有关联值的所有键。 |
abstract void |
putSpi(String key, String value) 将给定的键值关联放入此首选项节点中。 |
abstract void |
removeNodeSpi() 删除此首选项节点,使其无效并包含它的任何首选项。 |
abstract void |
removeSpi(String key) 删除此首选项节点上指定键的关联(如果有)。 |
abstract void |
syncSpi() 此方法在此节点被锁定时调用。 |
Inherited methods |
|
---|---|
From class java.util.prefs.Preferences
|
|
From class java.lang.Object
|
Object lock
其监视器用于锁定此节点的对象。 此对象优先于节点本身使用,以减少由于锁定的节点而导致有意或无意拒绝服务的可能性。 为避免死锁,一个节点永远不会被一个在该节点的后代拥有一个锁的线程锁定。
boolean newNode
如果此节点在创建此对象之前不存在于后备存储中,则此字段应为true 。 该字段初始化为false,但可以通过子类构造函数将其设置为true(并且此后不应修改)。 该字段指示创建完成时是否应激发节点更改事件。
AbstractPreferences (AbstractPreferences parent, String name)
使用指定的父项和指定的名称相对于其父项创建首选项节点。
Parameters | |
---|---|
parent |
AbstractPreferences : the parent of this preference node, or null if this is the root. |
name |
String : the name of this preference node, relative to its parent, or "" if this is the root. |
Throws | |
---|---|
IllegalArgumentException |
if name contains a slash ('/'), or parent is null and name isn't "". |
String absolutePath ()
实现 absolutePath方法按照在本说明书中 absolutePath()
。
该实现仅返回在构造此节点时计算的绝对路径名(基于传递给此节点的构造函数的名称以及传递给此节点的祖先构造函数的名称)。
Returns | |
---|---|
String |
this preference node's absolute path name. |
void addNodeChangeListener (NodeChangeListener ncl)
注册指定的侦听器以接收此节点的节点更改事件 。 将子节点添加到此节点或从中删除时,会生成节点更改事件。 (单个removeNode()
调用会导致多个节点更改事件 ,其中一个用于以已除去节点为根的子树中的每个节点。)
事件只能保证在与注册监听器相同的JVM中进行的更改,尽管某些实现可能会生成事件以便在此JVM之外进行更改。 事件可能会在更改变为永久之前生成。 当添加或删除此节点的间接后代时,不会生成事件; 希望发生此类事件的来电者必须向每个后代登记。
几乎没有关于节点创建的保证。 由于节点是在访问时隐式创建的,因此实现可能无法确定子节点在访问之前是否存在于后备存储中(例如,因为后备存储无法访问或缓存的信息已过期)。 在这些情况下,实现既不需要生成节点更改事件也不被禁止。
Parameters | |
---|---|
ncl |
NodeChangeListener : The NodeChangeListener to add. |
void addPreferenceChangeListener (PreferenceChangeListener pcl)
注册指定的侦听器以接收此首选项节点的首选项更改事件 。 当首选项添加到此节点,从此节点中删除或与首选项关联的值发生更改时,会生成首选项更改事件。 (偏好改变事件不会由所产生的removeNode()
方法,该方法生成事件 。优选变化事件是由clear方法生成的节点的变化 。)
事件只能保证在与注册监听器相同的JVM中进行的更改,尽管某些实现可能会生成事件以便在此JVM之外进行更改。 事件可能在变更持续之前生成。 在此节点的后代中修改首选项时不会生成事件; 希望发生此类事件的来电者必须向每个后代登记。
Parameters | |
---|---|
pcl |
PreferenceChangeListener : The preference change listener to add. |
String[] childrenNames ()
实现 children方法按照在本说明书中 childrenNames()
。
此实现获取此首选项节点的锁,检查该节点已不被删除,构造一个初始化为已缓存的孩子(在此节点的“子缓存”的孩子)的名称的TreeSet,调用childrenNamesSpi()
,并将所有返回的子集名称。 使用toArray方法将树集的元素转储到String数组中,并返回该数组。
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. |
也可以看看:
void clear ()
实现 clear方法按照在本说明书中 clear()
。
这个实现获得了这个首选节点的锁,调用 keys()
来获得一个键数组,并遍历每个键调用 remove(String)
的数组。
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. |
void exportNode (OutputStream os)
实现 exportNode方法按照在本说明书中 exportNode(OutputStream)
。
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. |
void exportSubtree (OutputStream os)
实现 exportSubtree方法按照在本说明书中 exportSubtree(OutputStream)
。
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. |
void flush ()
实现 flush方法按照在本说明书中 flush()
。
这个实现调用一个递归辅助方法来锁定这个节点,在其上调用flushSpi(),解锁这个节点,并递归地在每个“缓存的孩子”上调用这个方法。 高速缓存的子项是此虚拟机中创建的此节点的子项,随后不会被删除。 实际上,此方法首先对以此节点为根的“缓存子树”进行深度优先遍历,并在子树中的每个节点上调用flushSpi(),同时仅锁定该节点。 请注意,flushSpi()是自顶向下调用的。
如果在使用 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. |
也可以看看:
String get (String key, String def)
实现 get方法按照在本说明书中 get(String, String)
。
此实现首先检查是否key是null扔NullPointerException,如果是这种情况。 然后它获得这个首选节点的锁,检查节点没有被移除,调用getSpi(String)
,并返回结果,除非getSpi调用返回null或引发异常,在这种情况下,此调用返回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. |
Throws | |
---|---|
IllegalStateException |
if this node (or an ancestor) has been removed with the removeNode() method. |
NullPointerException |
if key is null. (A null default is permitted.) |
boolean getBoolean (String key, boolean def)
实现 getBoolean方法按照在本说明书中 getBoolean(String, boolean)
。
该实现调用get(key, null)
。 如果返回值非空,则使用equalsIgnoreCase(String)
将其与"true"进行equalsIgnoreCase(String)
。 如果比较返回true ,则此调用返回true 。 否则,将原始返回值与"false"进行比较,再次使用equalsIgnoreCase(String)
。 如果比较返回true ,则此调用返回false 。 否则,该调用返回def 。
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. |
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. |
byte[] getByteArray (String key, byte[] def)
实现 getByteArray方法按照在本说明书中 getByteArray(String, byte[])
。
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. |
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.) |
double getDouble (String key, double def)
实现 getDouble方法按照在本说明书中 getDouble(String, double)
。
该实现调用get(key, null)
。 如果返回值非空,则实现尝试将其转换为101728179137877 , parseDouble(String)
其转换为parseDouble(String)
。 如果尝试成功,则返回值由此方法返回。 否则,返回def 。
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. |
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. |
float getFloat (String key, float def)
实现 getFloat方法按照在本说明书中 getFloat(String, float)
。
该实现调用get(key, null)
。 如果返回值非空,则实现尝试将其转换为float , parseFloat(String)
其转换为parseFloat(String)
。 如果尝试成功,则返回值由此方法返回。 否则,返回def 。
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. |
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. |
int getInt (String key, int def)
实现 getInt方法按照在本说明书中 getInt(String, int)
。
该实现调用get(key, null)
。 如果返回值非空,则实现将尝试将其转换为int和parseInt(String)
。 如果尝试成功,则返回值由此方法返回。 否则,返回def 。
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. |
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. |
long getLong (String key, long def)
实现 getLong方法按照在本说明书中 getLong(String, long)
。
该实现调用get(key, null)
。 如果返回值非空,则实现尝试将其转换为long , parseLong(String)
其转换为parseLong(String)
。 如果尝试成功,则返回值由此方法返回。 否则,返回def 。
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. |
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. |
boolean isUserNode ()
实现 isUserNode方法按照在本说明书中 isUserNode()
。
此实现将此节点的根节点(存储在专用字段中)与由userRoot()
返回的值进行userRoot()
。 如果两个对象引用是相同的,则此方法返回true。
Returns | |
---|---|
boolean |
true if this preference node is in the user preference tree, false if it's in the system preference tree. |
String[] keys ()
实现 keys方法按照在本说明书中 keys()
。
此实现获取此首选项节点的锁定,检查该节点是否未被删除并调用 keysSpi()
。
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. |
String name ()
实现 name方法按照在本说明书中 name()
。
该实现仅返回传递给此节点构造函数的名称。
Returns | |
---|---|
String |
this preference node's name, relative to its parent. |
Preferences node (String path)
实现 node方法按照在本说明书中 node(String)
。
此实现获取此首选节点的锁并检查该节点是否未被删除。 如果path是"" ,则返回此节点; 如果path是"/" ,则返回此节点的根。 如果path中的第一个字符不是'/' ,则实现将path分解为令牌,并递归遍历从此节点到命名节点的路径,在遍历的每一步中“消耗”来自path的名称和斜杠。 在每个步骤中,当前节点被锁定,并检查节点的子缓存中的指定节点。 如果未找到,则检查名称以确保其长度不超过MAX_NAME_LENGTH 。 然后调用childSpi(String)
方法,并将结果存储在此节点的子缓存中。 如果新创建的Preferences对象的newNode
字段为true,并且存在任何节点更改侦听器,则通知事件将被排队以供事件分派线程处理。
当没有更多的标记时,通过此方法返回在子缓存中找到的或由childSpi返回的最后一个值。 如果在遍历期间,两个"/"令牌连续出现,或者最后的令牌是"/" (而不是名称),则会引发相应的IllegalArgumentException 。
如果path的第一个字符是'/' (表示绝对路径名),则在将path分解为令牌之前先删除此首选节点的锁,并且此方法递归遍历从根开始的路径(而不是从此节点开始)。 否则,遍历与相对路径名描述的相同。 根据locking invariant
,在根节点开始遍历之前丢弃此节点上的锁对于避免死锁的可能性locking invariant
。
Parameters | |
---|---|
path |
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). |
IllegalStateException |
if this node (or an ancestor) has been removed with the removeNode() method. |
boolean nodeExists (String path)
实现 nodeExists方法按照在本说明书中 nodeExists(String)
。
该实现与 node(String)
非常相似,不同之 getChild(String)
在于使用 childSpi(String)
而不是 childSpi(String)
。
Parameters | |
---|---|
path |
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). |
IllegalStateException |
if this node (or an ancestor) has been removed with the removeNode() method and pathname is not the empty string (""). |
Preferences parent ()
实现 parent方法按照在本说明书中 parent()
。
此实现获取此首选项节点的锁定,检查该节点是否未被删除并返回传递给此节点构造函数的父值。
Returns | |
---|---|
Preferences |
the parent of this preference node. |
Throws | |
---|---|
IllegalStateException |
if this node (or an ancestor) has been removed with the removeNode() method. |
void put (String key, String value)
实现 put方法按照在本说明书中 put(String, String)
。
此实现将检查键和值是否合法,获取此首选项节点的锁定,检查节点是否未被删除,调用 putSpi(String, String)
,如果有任何首选项更改侦听器,则将事件分派线程处理的通知事件排入队列。
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. |
void putBoolean (String key, boolean value)
实现 putBoolean方法按照在本说明书中 putBoolean(String, boolean)
。
该实现将 value转换为包含 valueOf(boolean)
的字符串, valueOf(boolean)
结果调用 put(String, String)
。
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. |
void putByteArray (String key, byte[] value)
实现 putByteArray方法按照在本说明书中 putByteArray(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. |
void putDouble (String key, double value)
实现 putDouble方法按照在本说明书中 putDouble(String, double)
。
该实现将 value转换为 toString(double)的字符串, toString(double)
结果调用 put(String, String)
。
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. |
void putFloat (String key, float value)
实现 putFloat方法按照在本说明书中 putFloat(String, float)
。
该实现将 value转换为包含 toString(float)
的字符串, toString(float)
结果调用 put(String, String)
。
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. |
void putInt (String key, int value)
实现 putInt方法按照在本说明书中 putInt(String, int)
。
该实现将 value转换为一个包含 toString(int)
的字符串, toString(int)
结果调用 put(String, String)
。
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. |
void putLong (String key, long value)
实现 putLong方法按照在本说明书中 putLong(String, long)
。
该实现将 value转换为 toString(long)的字符串, toString(long)
结果调用 put(String, String)
。
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. |
void remove (String key)
实现 remove(String)方法按照在本说明书中 remove(String)
。
此实现获取此首选项节点的锁定,检查该节点是否未被删除,调用 removeSpi(String)
并且是否有任何首选项更改侦听器将事件分派线程处理的通知事件排入队列。
Parameters | |
---|---|
key |
String : key whose mapping is to be removed from the preference node. |
Throws | |
---|---|
IllegalStateException |
if this node (or an ancestor) has been removed with the removeNode() method. |
void removeNode ()
实现 removeNode()方法按照在本说明书中 removeNode()
。
该实现检查以查看该节点是根节点; 如果是这样,它会抛出一个适当的异常。 然后,它锁定该节点的父节点,并调用遍历以此节点为根的子树的递归辅助方法。 递归方法锁定被调用的节点,检查它是否已被删除,然后确保其所有子childrenNamesSpi()
都被缓存:调用childrenNamesSpi()
方法,并检查每个返回的子childrenNamesSpi()
名称是否包含在子childrenNamesSpi()
中,缓存。 如果孩子尚未被缓存,则会调用childSpi(String)
方法为其创建一个Preferences实例,并将此实例放入子缓存中。 然后,辅助方法在包含在其子缓存中的每个节点上递归地调用它自己。 接下来,它调用removeNodeSpi()
,将自己标记为已删除,并将其本身从其父级的子级高速缓存中移除。 最后,如果有任何节点更改侦听器,它会排队通知事件以供事件分派线程处理。
请注意,辅助方法始终在所有祖先锁定为“最近的未删除祖先”的情况下调用。
Throws | |
---|---|
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. |
BackingStoreException |
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it. |
void removeNodeChangeListener (NodeChangeListener ncl)
删除指定的 NodeChangeListener ,因此它不再收到更改事件。
Parameters | |
---|---|
ncl |
NodeChangeListener : The NodeChangeListener to remove. |
void removePreferenceChangeListener (PreferenceChangeListener pcl)
删除指定的首选项更改侦听器,使其不再接收首选项更改事件。
Parameters | |
---|---|
pcl |
PreferenceChangeListener : The preference change listener to remove. |
void sync ()
实现 sync方法按照在本说明书中 sync()
。
这个实现调用一个递归辅助方法来锁定这个节点,在其上调用syncSpi(),解锁这个节点,并递归地在每个“缓存的孩子”上调用这个方法。 高速缓存的子项是此虚拟机中创建的此节点的子项,随后不会被删除。 实际上,此方法首先对以此节点为根的“缓存子树”进行深度优先遍历,并在子树中的每个节点上调用syncSpi(),而只锁定该节点。 请注意,syncSpi()是自顶向下调用的。
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. |
也可以看看:
String toString ()
返回此首选项节点的绝对路径名称。
Returns | |
---|---|
String |
a string representation of the object. |
AbstractPreferences[] cachedChildren ()
返回此节点的所有已知未清除的子节点。
Returns | |
---|---|
AbstractPreferences[] |
all known unremoved children of this node. |
AbstractPreferences childSpi (String name)
返回此首选项节点的命名子节点,如果它尚不存在,则创建它。 确保name非空,非空,不包含斜杠字符('/'),并且不超过MAX_NAME_LENGTH
字符。 另外,保证这个节点还没有被移除。 (实现者不需要检查任何这些东西。)
最后,保证指定节点在上次调用此方法或getChild(String)
后最后一次调用时未被返回。 换句话说,缓存的值将始终用于优先于调用此方法。 子类不需要维护它们自己的先前返回的子项的缓存。
实施者必须确保返回的节点没有被移除。 如果之前删除了此节点的相似名称的子节点,那么实施者必须返回一个新构建的节点AbstractPreferences ; 一旦移除, AbstractPreferences节点不能“复苏”。
如果此方法导致创建节点,则在该节点或其祖先(或后代)之一调用 flush方法之前,该节点不能保证持久性。
该方法通过保持该节点上的锁来调用。
Parameters | |
---|---|
name |
String : The name of the child node to return, relative to this preference node. |
Returns | |
---|---|
AbstractPreferences |
The named child node. |
String[] childrenNamesSpi ()
返回此首选项节点的子项名称。 (如果此节点没有子节点,则返回的数组的大小为零)。此方法不需要返回已缓存的任何节点的名称,但可以毫无损坏地返回。
该方法通过保持该节点上的锁来调用。
如果此节点抛出 BackingStoreException ,则该异常将传出超出封闭的 childrenNames()
调用。
Returns | |
---|---|
String[] |
an array containing 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. |
void flushSpi ()
此方法在此节点被锁定时调用。 此方法的契约是强制将此首选项节点的内容中的任何缓存更改强制到后备存储,以确保其持久性。 (这是完全可能的是,该节点上不后备存储器中存在,或者是因为它已被另一个VM删除,或因为它尚未被创建)。注意,在此任何子节点此方法不应冲洗喜好节点。 如果后备存储自然地一次刷新整个子树,则鼓励实施者重写flush(),而不是仅仅重写此方法。
如果此节点引发 BackingStoreException ,则该异常将传出超出封闭的 flush()
调用。
Throws | |
---|---|
BackingStoreException |
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it. |
AbstractPreferences getChild (String nodeName)
返回指定的子项(如果存在);如果不存在,则返回null 。 保证nodeName非空,非空,不包含斜杠字符('/'),并且不超过MAX_NAME_LENGTH
字符。 另外,保证这个节点还没有被移除。 (如果执行者选择重写此方法,则不需要检查这些事情。)
最后,保证命名节点在上次调用此方法或childSpi(String)
后最后一次调用时未被返回。 换句话说,缓存的值将始终用于优先于调用此方法。 (如果实现者选择覆盖此方法,则无需维护自己的先前返回的子项的缓存。)
此实现获取此首选节点的锁,调用childrenNames()
以获取此节点的子节点的名称数组,并遍历数组,将每个子节点的名称与指定的节点名称进行比较。 如果子节点具有正确的名称,则会调用childSpi(String)
方法,并返回结果节点。 如果迭代完成而没有找到指定名称,则返回null 。
Parameters | |
---|---|
nodeName |
String : name of the child to be searched for. |
Returns | |
---|---|
AbstractPreferences |
the named child if it exists, or null if it does not. |
Throws | |
---|---|
BackingStoreException |
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it. |
String getSpi (String key)
返回与此首选项节点上指定键相关联的值,如果此键不存在关联,则返回null ,否则此关联无法确定。 保证key非空。 另外,保证这个节点还没有被移除。 (实现者不需要检查这些事情。)
一般来说,这种方法在任何情况下都不应该抛出异常。 但是,如果它确实抛出了异常,则该异常将被拦截并视为返回值null 。
该方法通过保持该节点上的锁来调用。
Parameters | |
---|---|
key |
String
|
Returns | |
---|---|
String |
the value associated with the specified key at this preference node, or null if there is no association for this key, or the association cannot be determined at this time. |
boolean isRemoved ()
返回true如果此节点(或其祖先)已经被除去的removeNode()
方法。 此方法在返回用于跟踪此状态的专用字段的内容之前锁定此节点。
Returns | |
---|---|
boolean |
true iff this node (or an ancestor) has been removed with the removeNode() method. |
String[] keysSpi ()
返回此首选项节点中具有关联值的所有键。 (如果此节点没有首选项,则返回的数组大小为零)。保证此节点未被删除。
该方法通过保持该节点上的锁来调用。
如果此节点引发 BackingStoreException ,则该异常将传出超出封闭的 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. |
void putSpi (String key, String value)
将给定的键值关联放入此首选项节点中。 保证key和value非空和法定长度。 另外,保证这个节点还没有被移除。 (实现者不需要检查任何这些东西。)
该方法通过保持该节点上的锁来调用。
Parameters | |
---|---|
key |
String
|
value |
String
|
void removeNodeSpi ()
删除此首选项节点,使其无效并包含它的任何首选项。 removeNode()
此调用时,命名的子项将没有后代(即, removeNode()
方法以自下而上的方式重复调用此方法,在删除节点本身之前删除每个节点的后代)。
此方法通过在此节点及其父节点(以及由于一次调用 removeNode()
而被删除的所有祖先)上的锁来调用。
除非在此节点(或祖先)上调用 flush方法, 否则删除节点不需要持久化。
如果此节点引发 BackingStoreException ,则该异常将传播到封闭的 removeNode()
调用之外。
Throws | |
---|---|
BackingStoreException |
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it. |
void removeSpi (String key)
删除此首选项节点上指定键的关联(如果有)。 保证key非空。 另外,保证这个节点还没有被移除。 (实现者不需要检查这些事情。)
该方法通过保持该节点上的锁来调用。
Parameters | |
---|---|
key |
String
|
void syncSpi ()
此方法在此节点被锁定时调用。 该方法的契约是将存储在此节点的所有缓存首选项与存储在后备存储中的任何缓存首选项同步。 (这是完全可能的,这点上不支持存储存在,可能是因为它已被其他虚拟机删除,或者因为它尚未创建)。注意,在这个任意子节点,此方法不应同步偏好节点。 如果后备存储自然地同步整个子树,鼓励实现者重写sync(),而不是仅仅覆盖此方法。
如果此节点引发 BackingStoreException ,则该异常将传播到封闭的 sync()
调用之外。
Throws | |
---|---|
BackingStoreException |
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it. |