Module java.prefs
Package java.util.prefs

Class 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并不意味着所有先前的操作都已成功永久化。

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

大多数SPI方法要求实现在首选项节点中读取或写入信息。实现者应该注意到另一个VM可能已经从后端存储中并发删除了这个节点。如果节点已被删除，实现的责任是重新创建该节点。

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

自 JDK 版本:
1.4
参见:

  • Field Details

    • newNode

      protected boolean newNode
      如果此节点在创建此对象之前不存在于后备存储中，则此字段应为true。该字段初始化为false，但可以由子类构造函数设置为true（之后不应修改）。此字段指示在创建完成时是否应触发节点更改事件。

    • lock

      protected final Object lock
      用于锁定此节点的监视器对象。为了避免死锁，永远不会由持有该节点后代锁的线程锁定节点本身。

  • Constructor Details

    • AbstractPreferences

      protected AbstractPreferences(AbstractPreferences parent, String name)
      使用指定的父级和相对于其父级的指定名称创建偏好节点。
      参数：
      parent - 此偏好节点的父级，如果这是根节点，则为null。
      name - 此偏好节点的名称，相对于其父级，如果这是根节点，则为""。
      抛出：
      IllegalArgumentException - 如果name包含斜杠（'/'），或者parent为null且名称不是""。

  • Method Details

    • 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方法。

      此实现获取此偏好节点的锁，检查节点是否已被移除，调用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方法。

      此实现使用Integer.toString(int)将value转换为字符串，并在结果上调用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方法。

      此实现使用Long.toString(long)将value转换为字符串，并在结果上调用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方法。

      此实现使用String.valueOf(boolean)将value转换为字符串，并在结果上调用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 - 要返回其关联值作为布尔值的键。
      def - 如果此首选项节点没有与key关联的值，或者关联值无法解释为布尔值，则返回的值。
      返回:
      此首选项节点中与key关联的字符串表示的布尔值，如果关联值不存在或无法解释为布尔值，则返回def。
      抛出:
      IllegalStateException - 如果使用removeNode()方法删除了此节点（或祖先）。
      NullPointerException - 如果key为null。
      IllegalArgumentException - 如果键包含空控制字符，代码点U+0000。
      参见:

    • putFloat

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

      此实现使用Float.toString(float)将value转换为字符串，并在结果上调用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方法。

      此实现使用Double.toString(double)将value转换为字符串，并在结果上调用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 - 如果键的长度超过MAX_KEY_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分解为标记，并从此节点递归遍历到命名节点，“消耗”每一步遍历中的名称和斜杠。在每一步中，当前节点被锁定，并检查节点的子节点缓存是否包含命名节点。如果未找到，则检查名称以确保其长度不超过MAX_NAME_LENGTH。然后调用childSpi(String)方法，并将结果存储在此节点的子节点缓存中。如果新创建的Preferences对象的newNode字段为true并且存在任何节点更改侦听器，则会为事件分派线程排队一个通知事件以供处理。

      当没有更多标记时，此方法返回子节点缓存中找到的或childSpi返回的最后一个值。在遍历过程中，如果连续出现两个"/"标记，或最终标记为"/"（而不是名称），则会抛出适当的IllegalArgumentException。

      如果path的第一个字符是'/'（表示绝对路径名），则在将path分解为标记之前，将放弃此偏好节点的锁，并且此方法将从根（而不是从此节点）开始递归遍历路径。遍历与相对路径名描述的遍历相同。在从根节点开始遍历之前放弃此节点上的锁对于避免死锁的可能性至关重要，根据锁定不变性。

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

    • removeNode

      public void removeNode() throws BackingStoreException
      实现了Preferences.removeNode()规范中的removeNode()方法。

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

      请注意，辅助方法始终与所有祖先一直到“最近未删除的祖先”一起调用。

      指定者:
      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
      注册指定的侦听器以接收此首选项节点的首选项更改事件。当向此节点添加首选项、从此节点中删除首选项或更改与首选项关联的值时，将生成首选项更改事件。（首选项更改事件不是由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方法（或祖先的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删除，要么因为它尚未被创建。）请注意，此方法不应同步此节点的任何子节点中的首选项。如果后备存储自然地一次同步整个子树，建议实现者重写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删除，要么因为它尚未被创建。）请注意，此方法不应刷新此节点的任何子节点中的首选项。如果后备存储自然地一次刷新整个子树，建议实现者重写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 - 如果无法从后备存储中读取首选项数据。
      参见: