模块 java.prefs
包 java.util.prefs

类 AbstractPreferences

java.lang.Object
java.util.prefs.Preferences
java.util.prefs.AbstractPreferences
public abstract class AbstractPreferences extends Preferences
此类提供了 Preferences 类的骨架实现，大大简化了实现它的任务。

This class is for Preferences implementers only. Normal users of the Preferences facility should have no need to consult this documentation. The Preferences documentation should suffice.

实施者必须覆盖九个抽象服务提供商接口 (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 ，要求实现在无法执行操作时抛出这个checked exception。异常向外传播，导致相应的 API 方法失败。

其余 SPI 方法 putSpi(String,String) 、removeSpi(String) 和 childSpi(String) 具有更复杂的异常行为。他们没有被指定抛出 BackingStoreException ，因为即使后备存储不可用，他们通常也可以遵守他们的合同。这是真的，因为它们不返回任何信息，并且在随后调用 Preferences.flush() 或 Preferences.sync() 之前，它们的效果不需要成为永久性的。一般来说，这些 SPI 方法不应该抛出异常。在某些实现中，可能存在这些调用甚至无法将请求的操作排队以供以后处理的情况。即使在这些情况下，通常最好忽略调用并返回，而不是抛出异常。然而，在这些情况下，随后调用 flush() 或 sync 并不意味着所有先前的操作都已成功永久化。

在一种情况下putSpi, removeSpi and childSpi应该抛出异常：如果调用者在底层操作系统上缺乏足够的权限来执行请求的操作。例如，如果非特权用户试图修改系统首选项，大多数系统都会发生这种情况。 （所需的权限因实现而异。在某些实现中，它们有权修改文件系统中某些目录的内容；在其他实现中，它们有权修改注册表中某些键的内容。）在任何情况下在这些情况下，通常不希望让程序继续执行，就好像这些操作将在以后成为永久性操作一样。虽然在这些情况下不需要实现抛出异常，但我们鼓励它们这样做。 SecurityException 是合适的。

大多数 SPI 方法需要实现在首选项节点读取或写入信息。实现者应该注意另一个 VM 可能同时从后备存储中删除该节点的事实。如果节点已被删除，则执行者有责任重新创建该节点。

实施说明：在 Sun 的默认 Preferences 实施中，用户的身份是从底层操作系统继承的，并且在虚拟机的生命周期内不会改变。认识到服务端 Preferences 实现可能会根据请求更改用户身份，通过使用静态 ThreadLocal 实例隐式传递给 Preferences 方法。此类实现的作者是强烈地鼓励在访问首选项时确定用户（例如通过 get(String,String) 或 put(String,String) 方法），而不是将用户与每个 Preferences 实例永久关联。后一种行为与正常的 Preferences 用法相冲突，并会导致极大的混乱。

自从：
1.4
参见：

  • 字段详细信息

    • 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) ，如果有任何首选项更改监听器，则将通知事件加入队列以供事件调度线程处理。

      指定者：
      put 在类 Preferences 中
      参数：
      key - 与指定值关联的键。
      value - 与指定键关联的值。
      抛出：
      NullPointerException - 如果键或值是 null 。
      IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH 或者如果 value.length 超过 MAX_VALUE_LENGTH。
      IllegalArgumentException - 如果键或值包含空控制字符，代码点 U+0000。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。

    • get

      public String  get(String  key, String  def)
      根据 Preferences.get(String,String) 中的规范实施 get 方法。

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

      指定者：
      get 在类 Preferences 中
      参数：
      key - 要返回其关联值的键。
      def - 如果此首选项节点没有与 key 关联的值，则返回该值。
      返回：
      与 key 关联的值，如果没有值与 key 关联，则为 def 。
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      NullPointerException - 如果键是 null 。 （一个null默认是允许。）
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。

    • remove

      public void remove(String  key)
      根据 Preferences.remove(String) 中的规范实施 remove(String) 方法。

      此实现获取此首选项节点的锁，检查该节点是否未被删除，调用removeSpi(String) ，如果有任何首选项更改监听器，则将通知事件加入队列以供事件调度线程处理。

      指定者：
      remove 在类 Preferences 中
      参数：
      key - 要从首选项节点中删除其映射的键。
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      NullPointerException - 如果 key 是 null。

    • clear

      public void clear() throws BackingStoreException
      根据 Preferences.clear() 中的规范实施 clear 方法。

      此实现获取此首选项节点的锁，调用 keys() 以获取键数组，并在每个键上调用 remove(String) 遍历数组。

      指定者：
      clear 在类 Preferences 中
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • putInt

      public void putInt(String  key, int value)
      根据 Preferences.putInt(String,int) 中的规范实施 putInt 方法。

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

      指定者：
      putInt 在类 Preferences 中
      参数：
      key - 与字符串形式的值关联的键。
      value - 其字符串形式要与键相关联的值。
      抛出：
      NullPointerException - 如果键是 null 。
      IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • getInt

      public int getInt(String  key, int def)
      根据 Preferences.getInt(String,int) 中的规范实施 getInt 方法。

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

      指定者：
      getInt 在类 Preferences 中
      参数：
      key - 其关联值将作为 int 返回的键。
      def - 如果此首选项节点没有与 key 关联的值或关联值不能解释为 int，则返回该值。
      返回：
      此首选项节点中与 key 关联的字符串表示的 int 值，如果关联值不存在或无法解释为 int，则为 def。
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      NullPointerException - 如果 key 是 null。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      参见：

    • putLong

      public void putLong(String  key, long value)
      根据 Preferences.putLong(String,long) 中的规范实施 putLong 方法。

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

      指定者：
      putLong 在类 Preferences 中
      参数：
      key - 与字符串形式的值关联的键。
      value - 其字符串形式要与键相关联的值。
      抛出：
      NullPointerException - 如果键是 null 。
      IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • getLong

      public long getLong(String  key, long def)
      根据 Preferences.getLong(String,long) 中的规范实施 getLong 方法。

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

      指定者：
      getLong 在类 Preferences 中
      参数：
      key - 其关联值将作为 long 返回的键。
      def - 如果此首选项节点没有与 key 关联的值或关联值不能解释为 long，则返回该值。
      返回：
      此首选项节点中与 key 关联的字符串表示的 long 值，如果关联值不存在或不能解释为 long，则为 def。
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      NullPointerException - 如果 key 是 null。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      参见：

    • putBoolean

      public void putBoolean(String  key, boolean value)
      根据 Preferences.putBoolean(String,boolean) 中的规范实施 putBoolean 方法。

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

      指定者：
      putBoolean 在类 Preferences 中
      参数：
      key - 与字符串形式的值关联的键。
      value - 其字符串形式要与键相关联的值。
      抛出：
      NullPointerException - 如果键是 null 。
      IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • getBoolean

      public boolean getBoolean(String  key, boolean def)
      根据 Preferences.getBoolean(String,boolean) 中的规范实施 getBoolean 方法。

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

      指定者：
      getBoolean 在类 Preferences 中
      参数：
      key - 其关联值将作为boolean返回的键。
      def - 如果此首选项节点没有与 key 关联的值或关联值不能解释为boolean，则返回该值。
      返回：
      此首选项节点中与 key 关联的字符串表示的boolean，如果关联值不存在或无法解释为boolean，则为 def。
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      NullPointerException - 如果 key 是 null。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      参见：

    • putFloat

      public void putFloat(String  key, float value)
      根据 Preferences.putFloat(String,float) 中的规范实施 putFloat 方法。

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

      指定者：
      putFloat 在类 Preferences 中
      参数：
      key - 与字符串形式的值关联的键。
      value - 其字符串形式要与键相关联的值。
      抛出：
      NullPointerException - 如果键是 null 。
      IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • getFloat

      public float getFloat(String  key, float def)
      根据 Preferences.getFloat(String,float) 中的规范实施 getFloat 方法。

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

      指定者：
      getFloat 在类 Preferences 中
      参数：
      key - 其关联值将作为浮点数返回的键。
      def - 如果此首选项节点没有与 key 关联的值或关联值不能解释为浮点数，则返回该值。
      返回：
      此首选项节点中与 key 关联的字符串表示的浮点值，如果关联值不存在或无法解释为浮点数，则为 def。
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      NullPointerException - 如果 key 是 null。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      参见：

    • putDouble

      public void putDouble(String  key, double value)
      根据 Preferences.putDouble(String,double) 中的规范实施 putDouble 方法。

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

      指定者：
      putDouble 在类 Preferences 中
      参数：
      key - 与字符串形式的值关联的键。
      value - 其字符串形式要与键相关联的值。
      抛出：
      NullPointerException - 如果键是 null 。
      IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • getDouble

      public double getDouble(String  key, double def)
      根据 Preferences.getDouble(String,double) 中的规范实施 getDouble 方法。

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

      指定者：
      getDouble 在类 Preferences 中
      参数：
      key - 其关联值将作为双精度值返回的键。
      def - 如果此首选项节点没有与 key 关联的值或关联值不能解释为双精度值，则返回该值。
      返回：
      此首选项节点中与 key 关联的字符串表示的双精度值，如果关联值不存在或不能解释为双精度值，则为 def。
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      NullPointerException - 如果 key 是 null。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      参见：

    • putByteArray

      public void putByteArray(String  key, byte[] value)
      根据 Preferences.putByteArray(String,byte[]) 中的规范实施 putByteArray 方法。
      指定者：
      putByteArray 在类 Preferences 中
      参数：
      key - 与字符串形式的值关联的键。
      value - 其字符串形式要与键相关联的值。
      抛出：
      NullPointerException - 如果键或值是 null 。
      IllegalArgumentException - 如果 key.length() 超过 MAX_KEY_LENGTH 或者如果 value.length 超过 MAX_VALUE_LENGTH*3/4。
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • getByteArray

      public byte[] getByteArray(String  key, byte[] def)
      根据 Preferences.getByteArray(String,byte[]) 中的规范实施 getByteArray 方法。
      指定者：
      getByteArray 在类 Preferences 中
      参数：
      key - 其关联值将作为字节数组返回的键。
      def - 如果此首选项节点没有与 key 关联的值或关联值不能解释为字节数组，则返回该值。
      返回：
      由与此首选项节点中的 key 关联的字符串表示的字节数组值，如果关联值不存在或无法解释为字节数组，则为 def。
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      NullPointerException - 如果 key 是 null。 （def 的 null 值是允许。）
      IllegalArgumentException - 如果键包含空控制字符，代码点 U+0000。
      参见：

    • keys

      public String [] keys() throws BackingStoreException
      根据 Preferences.keys() 中的规范实施 keys 方法。

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

      指定者：
      keys 在类 Preferences 中
      返回：
      在此首选项节点中具有关联值的键数组。
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。

    • childrenNames

      public String [] childrenNames() throws BackingStoreException
      根据 Preferences.childrenNames() 中的规范实施 children 方法。

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

      指定者：
      childrenNames 在类 Preferences 中
      返回：
      此首选项节点的子节点的名称。
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • cachedChildren

      protected final AbstractPreferences [] cachedChildren()
      返回此节点的所有已知未删除的子节点。
      返回：
      该节点的所有已知未删除的子节点。

    • parent

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

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

      指定者：
      parent 在类 Preferences 中
      返回：
      此首选项节点的父节点。
      抛出：
      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 ，在根节点处开始遍历之前删除此节点上的锁对于避免死锁的可能性至关重要。

      指定者：
      node 在类 Preferences 中
      参数：
      path - 要返回的首选项节点的路径名。
      返回：
      指定的首选项节点。
      抛出：
      IllegalArgumentException - 如果路径名无效（即它包含多个连续的斜杠字符，或以斜杠字符结尾且长度超过一个字符）。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • nodeExists

      public boolean nodeExists(String  path) throws BackingStoreException
      根据 Preferences.nodeExists(String) 中的规范实施 nodeExists 方法。

      此实现与 node(String) 非常相似，除了使用 getChild(String) 而不是 childSpi(String) 。

      指定者：
      nodeExists 在类 Preferences 中
      参数：
      path - 要检查其存在的节点的路径名。
      返回：
      如果指定的节点存在，则为真。
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。
      IllegalArgumentException - 如果路径名无效（即它包含多个连续的斜杠字符，或以斜杠字符结尾且长度超过一个字符）。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除且 pathname 不是空字符串 ("" )。

    • removeNode

      public void removeNode() throws BackingStoreException
      根据 Preferences.removeNode() 中的规范实施 removeNode() 方法。

      此实现检查此节点是否为根节点；如果是这样，它会抛出一个适当的异常。然后，它锁定该节点的父节点，并调用遍历以该节点为根的子树的递归辅助方法。递归方法锁定调用它的节点，检查它是否已经被删除，然后确保它的所有子节点都被缓存：调用 childrenNamesSpi() 方法并检查每个返回的子名称是否包含在子节点中缓存。如果一个孩子还没有被缓存，childSpi(String) 方法被调用来为它创建一个Preferences实例，这个实例被放入孩子缓存中。然后辅助方法在其子缓存中包含的每个节点上递归调用自身。接下来，它调用 removeNodeSpi() ，将自己标记为已删除，并将自己从其父级的子缓存中删除。最后，如果有任何节点更改监听器，它会将通知事件排入队列以供事件分派线程处理。

      注意 helper 方法总是在所有祖先被调用时被锁定，直到“最近的未移除的祖先”被锁定。

      指定者：
      removeNode 在类 Preferences 中
      抛出：
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      UnsupportedOperationException - 如果在根节点上调用此方法。
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。
      参见：

    • name

      public String  name()
      根据 Preferences.name() 中的规范实施 name 方法。

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

      指定者：
      name 在类 Preferences 中
      返回：
      此首选项节点的名称，相对于其父节点。

    • absolutePath

      public String  absolutePath()
      根据 Preferences.absolutePath() 中的规范实施 absolutePath 方法。

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

      指定者：
      absolutePath 在类 Preferences 中
      返回：
      此首选项节点的绝对路径名。

    • isUserNode

      public boolean isUserNode()
      根据 Preferences.isUserNode() 中的规范实施 isUserNode 方法。

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

      指定者：
      isUserNode 在类 Preferences 中
      返回：
      true 如果此首选项节点在用户首选项树中，false 如果它在系统首选项树中。

    • addPreferenceChangeListener

      public void addPreferenceChangeListener(PreferenceChangeListener  pcl)
      从类复制的描述：Preferences
      注册指定的监听接收偏好改变事件对于这个偏好节点。当偏好被添加到该节点、从该节点移除，或者当与偏好关联的值被更改时，会生成偏好更改事件。 （偏好变化事件是not由 Preferences.removeNode() 方法生成，它生成一个节点变化事件.偏好更改事件是由 clear 方法生成。）

      只有在与注册的监听相同的 JVM 内所做的更改才能保证事件，尽管某些实现可能会为在该 JVM 之外所做的更改生成事件。事件可能会在更改持久化之前生成。在此节点的后代中修改首选项时不会生成事件；想要此类事件的调用者必须向每个后代注册。

      指定者：
      addPreferenceChangeListener 在类 Preferences 中
      参数：
      pcl - 要添加的首选项更改监听器。
      参见：

    • removePreferenceChangeListener

      public void removePreferenceChangeListener(PreferenceChangeListener  pcl)
      从类复制的描述：Preferences
      删除指定的首选项更改监听，因此它不再接收首选项更改事件。
      指定者：
      removePreferenceChangeListener 在类 Preferences 中
      参数：
      pcl - 要删除的首选项更改监听器。
      参见：

    • addNodeChangeListener

      public void addNodeChangeListener(NodeChangeListener  ncl)
      从类复制的描述：Preferences
      注册指定的监听接收节点变化事件对于这个节点。当向该节点添加或删除子节点时，会生成节点更改事件。 （单个 Preferences.removeNode() 调用会导致多个节点变化事件，一个代表以删除的节点为根的子树中的每个节点。）

      只有在与注册的监听相同的 JVM 内所做的更改才能保证事件，尽管某些实现可能会为在该 JVM 之外所做的更改生成事件。在更改成为永久性更改之前可能会生成事件。添加或删除此节点的间接后代时不会生成事件；想要此类事件的调用者必须向每个后代注册。

      关于节点创建几乎没有保证。因为节点是在访问时隐式创建的，所以实现在访问之前确定子节点是否存在于后备存储中可能是不可行的（例如，因为后备存储不可访问或缓存信息已过时）。在这些情况下，既不需要实现也不禁止生成节点更改事件。

      指定者：
      addNodeChangeListener 在类 Preferences 中
      参数：
      ncl - 要添加的 NodeChangeListener。
      参见：

    • removeNodeChangeListener

      public void removeNodeChangeListener(NodeChangeListener  ncl)
      从类复制的描述：Preferences
      删除指定的 NodeChangeListener ，因此它不再接收更改事件。
      指定者：
      removeNodeChangeListener 在类 Preferences 中
      参数：
      ncl - 要删除的 NodeChangeListener。
      参见：

    • putSpi

      protected abstract void putSpi(String  key, String  value)
      将给定的键值关联放入此偏好节点。保证 key 和 value 非空且具有合法长度。此外，还保证该节点未被删除。 （实施者不需要检查任何这些东西。）

      在持有此节点上的锁的情况下调用此方法。

      参数：
      key - 钥匙
      value - 值

    • getSpi

      protected abstract String  getSpi(String  key)
      返回与该首选项节点上的指定键关联的值，如果没有关联该键，则返回null，或者此时无法确定关联。保证 key 是非空的。此外，还保证该节点未被删除。 （实施者不需要检查这些事情中的任何一个。）

      一般来说，这个方法在任何情况下都不应该抛出异常。但是，如果它确实抛出异常，则该异常将被拦截并视为null 返回值。

      在持有此节点上的锁的情况下调用此方法。

      参数：
      key - 钥匙
      返回：
      与此首选项节点上的指定键相关联的值，或 null 如果此键没有关联，或者此时无法确定关联。

    • removeSpi

      protected abstract void removeSpi(String  key)
      删除此首选项节点上指定键的关联（如果有）。保证 key 是非空的。此外，还保证该节点未被删除。 （实施者不需要检查这些事情中的任何一个。）

      在持有此节点上的锁的情况下调用此方法。

      参数：
      key - 钥匙

    • removeNodeSpi

      protected abstract void removeNodeSpi() throws BackingStoreException
      删除此首选项节点，使其及其包含的任何首选项失效。在进行此调用时，命名的孩子将没有后代（即，Preferences.removeNode() 方法以自下而上的方式重复调用此方法，在删除节点本身之前删除节点的每个后代）。

      使用此节点及其父级（以及由于对 Preferences.removeNode() 的单次调用而被删除的所有祖先）持有的锁来调用此方法。

      在 flush 方法在此节点（或祖先）上调用之前，节点的删除不需要成为持久的。

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

      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。

    • keysSpi

      protected abstract String [] keysSpi() throws BackingStoreException
      返回在此首选项节点中具有关联值的所有键。 （如果此节点没有偏好，则返回的数组大小为零。）保证此节点未被删除。

      在持有此节点上的锁的情况下调用此方法。

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

      返回：
      在此首选项节点中具有关联值的键数组。
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。

    • childrenNamesSpi

      protected abstract String [] childrenNamesSpi() throws BackingStoreException
      返回此首选项节点的子节点的名称。 （如果此节点没有子节点，则返回的数组大小为零。）此方法不需要返回任何已缓存的节点的名称，但这样做可能不会造成任何损害。

      在持有此节点上的锁的情况下调用此方法。

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

      返回：
      包含此首选项节点的子节点名称的数组。
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。

    • getChild

      protected AbstractPreferences  getChild(String  nodeName) throws BackingStoreException
      如果命名的孩子存在则返回，如果不存在则返回null。保证 nodeName 非空，非空，不包含斜杠字符（'/'），并且不超过 Preferences.MAX_NAME_LENGTH 个字符。此外，还保证该节点未被删除。 （如果实现者选择覆盖此方法，则无需检查这些内容中的任何一项。）

      最后，保证命名节点在上次被删除后没有被此方法的先前调用返回或childSpi(java.lang.String) 。换句话说，将始终优先使用缓存值而不是调用此方法。 （如果实现者选择覆盖此方法，则无需维护他自己的先前返回的子级的缓存。）

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

      参数：
      nodeName - 要搜索的孩子的姓名。
      返回：
      命名的子级（如果存在）或 null（如果不存在）。
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。

    • childSpi

      protected abstract AbstractPreferences  childSpi(String  name)
      返回此首选项节点的命名子节点，如果它尚不存在则创建它。保证 name 非空，非空，不包含斜杠字符（'/'），并且不超过 Preferences.MAX_NAME_LENGTH 个字符。此外，还保证该节点未被删除。 （实施者不需要检查任何这些东西。）

      最后，保证命名节点在上次删除后没有被该方法的先前调用返回或getChild(String) 。换句话说，将始终优先使用缓存值而不是调用此方法。子类不需要维护自己的先前返回的孩子的缓存。

      实施者必须确保返回的节点没有被删除。如果先前删除了该节点的同名子节点，则实现者必须返回一个新构造的 AbstractPreferences 节点；一旦移除，AbstractPreferences 节点就无法“复苏”。

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

      在持有此节点上的锁的情况下调用此方法。

      参数：
      name - 要返回的子节点的名称，相对于此首选项节点。
      返回：
      命名的子节点。

    • toString

      public String  toString()
      返回此首选项节点的绝对路径名。
      指定者：
      toString 在类 Preferences 中
      返回：
      对象的字符串表示形式。

    • sync

      public void sync() throws BackingStoreException
      根据 Preferences.sync() 中的规范实施 sync 方法。

      这个实现调用一个递归的辅助方法来锁定这个节点，在它上面调用 syncSpi()，解锁这个节点，然后在每个“缓存的子节点”上递归地调用这个方法。缓存的子节点是已在此 VM 中创建且随后未被删除的此节点的子节点。实际上，此方法对以该节点为根的“缓存子树”进行深度优先遍历，在子树中的每个节点上调用 syncSpi()，而只有该节点被锁定。请注意，syncSpi() 是自上而下调用的。

      指定者：
      sync 在类 Preferences 中
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。
      IllegalStateException - 如果此节点（或祖先节点）已使用 removeNode() 方法移除。
      参见：

    • syncSpi

      protected abstract void syncSpi() throws BackingStoreException
      在锁定此节点的情况下调用此方法。此方法的契约是将存储在此节点的任何缓存首选项与存储在后备存储中的任何首选项同步。 （这个节点很可能不存在于后备存储中，要么是因为它已经被另一个VM删除，要么是因为它还没有被创建。）注意这个方法应该not同步此节点的任何子节点中的首选项。如果后备存储自然地一次同步整个子树，则鼓励实现者重写 sync()，而不是仅仅重写此方法。

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

      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。

    • flush

      public void flush() throws BackingStoreException
      根据 Preferences.flush() 中的规范实施 flush 方法。

      这个实现调用一个递归的辅助方法来锁定这个节点，在它上面调用 flushSpi()，解锁这个节点，并在每个“缓存的子级”上递归地调用这个方法。缓存的子节点是已在此 VM 中创建且随后未被删除的此节点的子节点。实际上，此方法对以该节点为根的“缓存子树”进行深度优先遍历，在子树中的每个节点上调用 flushSpi()，而只有该节点被锁定。请注意，flushSpi() 是自上而下调用的。

      如果在已使用 removeNode() 方法移除的节点上调用此方法，则会在该节点上调用 flushSpi()，但不会在其他节点上调用。

      指定者：
      flush 在类 Preferences 中
      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。
      参见：

    • flushSpi

      protected abstract void flushSpi() throws BackingStoreException
      在锁定此节点的情况下调用此方法。此方法的契约是将此首选项节点内容中的任何缓存更改强制到后备存储，以保证它们的持久性。 （这个节点很可能不存在于后备存储中，要么是因为它已经被另一个VM删除，要么是因为它还没有被创建。）注意这个方法应该not刷新此节点的任何子节点中的首选项。如果后备存储自然地一次刷新整个子树，则鼓励实现者重写 flush()，而不是仅仅重写此方法。

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

      抛出：
      BackingStoreException - 如果由于后备存储故障或无法与其通信而无法完成此操作。

    • isRemoved

      protected boolean isRemoved()
      返回 true 当且仅当此节点（或祖先）已使用 removeNode() 方法删除。此方法在返回用于跟踪此状态的私有字段的内容之前锁定此节点。
      返回：
      true 当且仅当此节点（或祖先）已使用 removeNode() 方法删除。

    • exportNode

      public void exportNode(OutputStream  os) throws IOException , BackingStoreException
      根据 Preferences.exportNode(OutputStream) 中的规范实施 exportNode 方法。
      指定者：
      exportNode 在类 Preferences 中
      参数：
      os - 在其上发出 XML 文档的输出流。
      抛出：
      IOException - 如果写入指定的输出流导致 IOException 。
      BackingStoreException - 如果无法从后备存储中读取偏好数据。
      参见：

    • exportSubtree

      public void exportSubtree(OutputStream  os) throws IOException , BackingStoreException
      根据 Preferences.exportSubtree(OutputStream) 中的规范实施 exportSubtree 方法。
      指定者：
      exportSubtree 在类 Preferences 中
      参数：
      os - 在其上发出 XML 文档的输出流。
      抛出：
      IOException - 如果写入指定的输出流导致 IOException 。
      BackingStoreException - 如果无法从后备存储中读取偏好数据。
      参见：