Package java.util.prefs

Class AbstractPreferences

java.lang.Object
java.util.prefs.Preferences
java.util.prefs.AbstractPreferences
public abstract class AbstractPreferences
extends Preferences
This abstract class is a partial implementation of the abstract class Preferences, which can be used to simplify Preferences provider's implementation. This class defines nine abstract SPI methods, which must be implemented by a preference provider.
Since:
1.4
See Also:
Preferences

  • Field Summary

    Fields
    Modifier and Type Field Description
    protected Object lock
    The object used to lock this node.
    protected boolean newNode
    This field is true if this node is created while it doesn't exist in the backing store.

    Fields inherited from class java.util.prefs.Preferences

    MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

  • Constructor Summary

    Constructors
    Modifier Constructor Description
    protected AbstractPreferences​(AbstractPreferences parent, String name)
    Constructs a new AbstractPreferences instance using the given parent node and node name.

  • Method Summary

    Modifier and Type Method Description
    String absolutePath()
    Gets the absolute path string of this preference node.
    void addNodeChangeListener​(NodeChangeListener ncl)
    Registers a NodeChangeListener instance for this node, which will handle NodeChangeEvents.
    void addPreferenceChangeListener​(PreferenceChangeListener pcl)
    Registers a PreferenceChangeListener instance for this node, which will handle PreferenceChangeEvents.
    protected AbstractPreferences[] cachedChildren()
    Returns an array of all cached child nodes.
    String[] childrenNames()
    Returns the names of all children of this node or an empty array if this node has no children.
    protected abstract String[] childrenNamesSpi()
    Returns the names of all of the child nodes of this node or an empty array if this node has no children.
    protected abstract AbstractPreferences childSpi​(String name)
    Returns the child preference node with the given name, creating it if it does not exist.
    void clear()
    Removes all preferences of this node.
    void exportNode​(OutputStream ostream)
    Exports all of the preferences of this node to a XML document using the given output stream.
    void exportSubtree​(OutputStream ostream)
    Exports all of the preferences of this node and all its descendants to a XML document using the given output stream.
    void flush()
    Forces all pending updates to this node and its descendants to be persisted in the backing store.
    protected abstract void flushSpi()
    Flushes changes of this node to the backing store.
    String get​(String key, String deflt)
    Gets the String value mapped to the given key or its default value if no value is mapped or no backing store is available.
    boolean getBoolean​(String key, boolean deflt)
    Gets the boolean value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is invalid.
    byte[] getByteArray​(String key, byte[] deflt)
    Gets the byte array value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
    protected AbstractPreferences getChild​(String name)
    Returns the child node with the specified name or null if it doesn't exist.
    double getDouble​(String key, double deflt)
    Gets the double value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
    float getFloat​(String key, float deflt)
    Gets the float value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
    int getInt​(String key, int deflt)
    Gets the int value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
    long getLong​(String key, long deflt)
    Gets the long value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
    protected abstract String getSpi​(String key)
    Gets the preference value mapped to the given key.
    protected boolean isRemoved()
    Returns whether this node has been removed by invoking the method removeNode().
    boolean isUserNode()
    Returns whether this is a user preference node.
    String[] keys()
    Returns all preference keys stored in this node or an empty array if no key was found.
    protected abstract String[] keysSpi()
    Returns an array of all preference keys of this node or an empty array if no preferences have been found.
    String name()
    Returns the name of this node.
    Preferences node​(String name)
    Returns the preference node with the given path name.
    boolean nodeExists​(String name)
    Returns whether the preference node with the given path name exists.
    Preferences parent()
    Returns the parent preference node of this node or null if this node is the root node.
    void put​(String key, String value)
    Adds a new preference to this node using the given key and value or updates the value if a preference with the given key already exists.
    void putBoolean​(String key, boolean value)
    Adds a new preference with a boolean value to this node using the given key and value or updates the value if a preference with the given key already exists.
    void putByteArray​(String key, byte[] value)
    Adds a new preference to this node using the given key and the string form of the given value or updates the value if a preference with the given key already exists.
    void putDouble​(String key, double value)
    Adds a new preference to this node using the given key and double value or updates the value if a preference with the given key already exists.
    void putFloat​(String key, float value)
    Adds a new preference to this node using the given key and float value or updates the value if a preference with the given key already exists.
    void putInt​(String key, int value)
    Adds a new preference to this node using the given key and int value or updates the value if a preference with the given key already exists.
    void putLong​(String key, long value)
    Adds a new preference to this node using the given key and long value or updates the value if a preference with the given key already exists.
    protected abstract void putSpi​(String name, String value)
    Puts the given key-value pair into this node.
    void remove​(String key)
    Removes the preference mapped to the given key from this node.
    void removeNode()
    Removes this preference node with all its descendants.
    void removeNodeChangeListener​(NodeChangeListener ncl)
    Removes the given NodeChangeListener instance from this node.
    protected abstract void removeNodeSpi()
    Removes this node from the preference hierarchy tree.
    void removePreferenceChangeListener​(PreferenceChangeListener pcl)
    Removes the given PreferenceChangeListener instance from this node.
    protected abstract void removeSpi​(String key)
    Removes the preference with the specified key.
    void sync()
    Synchronizes the data of this preference node and its descendants with the back-end preference store.
    protected abstract void syncSpi()
    Synchronizes this node with the backing store.
    String toString()
    Returns a string representation of this node.

    Methods inherited from class java.util.prefs.Preferences

    importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • lock

      protected final Object lock
      The object used to lock this node.

    • newNode

      protected boolean newNode
      This field is true if this node is created while it doesn't exist in the backing store. This field's default value is false, and it is checked when the node creation is completed, and if it is true, the node change event will be fired for this node's parent.

  • Constructor Details

    • AbstractPreferences

      protected AbstractPreferences​(AbstractPreferences parent, String name)
      Constructs a new AbstractPreferences instance using the given parent node and node name.
      Parameters:
      parent - the parent node of the new node or null to indicate that the new node is a root node.
      name - the name of the new node or an empty string to indicate that this node is called "root".
      Throws:
      IllegalArgumentException - if the name contains a slash character or is empty if parent is not null.

  • Method Details

    • cachedChildren

      protected final AbstractPreferences[] cachedChildren()
      Returns an array of all cached child nodes.
      Returns:
      the array of cached child nodes.

    • getChild

      protected AbstractPreferences getChild​(String name) throws BackingStoreException
      Returns the child node with the specified name or null if it doesn't exist. Implementers can assume that the name supplied to this method will be a valid node name string (conforming to the node naming format) and will not correspond to a node that has been cached or removed.
      Parameters:
      name - the name of the desired child node.
      Returns:
      the child node with the given name or null if it doesn't exist.
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • isRemoved

      protected boolean isRemoved()
      Returns whether this node has been removed by invoking the method removeNode().
      Returns:
      true, if this node has been removed, false otherwise.

    • flushSpi

      protected abstract void flushSpi() throws BackingStoreException
      Flushes changes of this node to the backing store. This method should only flush this node and should not include the descendant nodes. Any implementation that wants to provide functionality to flush all nodes at once should override the method flush().
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • childrenNamesSpi

      protected abstract String[] childrenNamesSpi() throws BackingStoreException
      Returns the names of all of the child nodes of this node or an empty array if this node has no children. The names of cached children are not required to be returned.
      Returns:
      the names of this node's children.
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • childSpi

      protected abstract AbstractPreferences childSpi​(String name)
      Returns the child preference node with the given name, creating it if it does not exist. The caller of this method should ensure that the given name is valid and that this node has not been removed or cached. If the named node has just been removed, the implementation of this method must create a new one instead of reactivating the removed one.

      The new creation is not required to be persisted immediately until the flush method will be invoked.

      Parameters:
      name - the name of the child preference to be returned.
      Returns:
      the child preference node.

    • putSpi

      protected abstract void putSpi​(String name, String value)
      Puts the given key-value pair into this node. Caller of this method should ensure that both of the given values are valid and that this node has not been removed.
      Parameters:
      name - the given preference key.
      value - the given preference value.

    • getSpi

      protected abstract String getSpi​(String key)
      Gets the preference value mapped to the given key. The caller of this method should ensure that the given key is valid and that this node has not been removed. This method should not throw any exceptions but if it does, the caller will ignore the exception, regarding it as a null return value.
      Parameters:
      key - the given key to be searched for.
      Returns:
      the preference value mapped to the given key.

    • keysSpi

      protected abstract String[] keysSpi() throws BackingStoreException
      Returns an array of all preference keys of this node or an empty array if no preferences have been found. The caller of this method should ensure that this node has not been removed.
      Returns:
      the array of all preference keys.
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • removeNodeSpi

      protected abstract void removeNodeSpi() throws BackingStoreException
      Removes this node from the preference hierarchy tree. The caller of this method should ensure that this node has no child nodes, which means the method Preferences.removeNode() should invoke this method multiple-times in bottom-up pattern. The removal is not required to be persisted until after it is flushed.
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • removeSpi

      protected abstract void removeSpi​(String key)
      Removes the preference with the specified key. The caller of this method should ensure that the given key is valid and that this node has not been removed.
      Parameters:
      key - the key of the preference that is to be removed.

    • syncSpi

      protected abstract void syncSpi() throws BackingStoreException
      Synchronizes this node with the backing store. This method should only synchronize this node and should not include the descendant nodes. An implementation that wants to provide functionality to synchronize all nodes at once should override the method sync().
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • absolutePath

      public String absolutePath()
      Description copied from class: Preferences
      Gets the absolute path string of this preference node.
      Specified by:
      absolutePath in class Preferences
      Returns:
      the preference node's absolute path string.

    • childrenNames

      public String[] childrenNames() throws BackingStoreException
      Description copied from class: Preferences
      Returns the names of all children of this node or an empty array if this node has no children.
      Specified by:
      childrenNames in class Preferences
      Returns:
      the names of all children of this node.
      Throws:
      BackingStoreException - if backing store is unavailable or causes an operation failure.

    • clear

      public void clear() throws BackingStoreException
      Description copied from class: Preferences
      Removes all preferences of this node.
      Specified by:
      clear in class Preferences
      Throws:
      BackingStoreException - if backing store is unavailable or causes an operation failure.

    • exportNode

      public void exportNode​(OutputStream ostream) throws IOException, BackingStoreException
      Description copied from class: Preferences
      Exports all of the preferences of this node to a XML document using the given output stream.

      This XML document uses the UTF-8 encoding and is written according to the DTD in its DOCTYPE declaration, which is the following: 

       <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
      Please note that (unlike the methods of this class that don't concern serialization), this call is not thread-safe.

      Specified by:
      exportNode in class Preferences
      Parameters:
      ostream - the output stream to write the XML-formatted data to.
      Throws:
      IOException - if an error occurs while exporting.
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • exportSubtree

      public void exportSubtree​(OutputStream ostream) throws IOException, BackingStoreException
      Description copied from class: Preferences
      Exports all of the preferences of this node and all its descendants to a XML document using the given output stream.

      This XML document uses the UTF-8 encoding and is written according to the DTD in its DOCTYPE declaration, which is the following: 

       <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
      Please note that (unlike the methods of this class that don't concern serialization), this call is not thread-safe.

      Specified by:
      exportSubtree in class Preferences
      Parameters:
      ostream - the output stream to write the XML-formatted data to.
      Throws:
      IOException - if an error occurs while exporting.
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • flush

      public void flush() throws BackingStoreException
      Description copied from class: Preferences
      Forces all pending updates to this node and its descendants to be persisted in the backing store.

      If this node has been removed, the invocation of this method only flushes this node, not its descendants.

      Specified by:
      flush in class Preferences
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • get

      public String get​(String key, String deflt)
      Description copied from class: Preferences
      Gets the String value mapped to the given key or its default value if no value is mapped or no backing store is available.

      Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

      Specified by:
      get in class Preferences
      Parameters:
      key - the preference key.
      deflt - the default value, which will be returned if no value is mapped to the given key or no backing store is available.
      Returns:
      the preference value mapped to the given key.

    • getBoolean

      public boolean getBoolean​(String key, boolean deflt)
      Description copied from class: Preferences
      Gets the boolean value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is invalid.

      The only valid values are the String "true", which represents true and "false", which represents false, ignoring case.

      Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

      Specified by:
      getBoolean in class Preferences
      Parameters:
      key - the preference key.
      deflt - the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid.
      Returns:
      the boolean value mapped to the given key.

    • getByteArray

      public byte[] getByteArray​(String key, byte[] deflt)
      Description copied from class: Preferences
      Gets the byte array value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.

      To be valid, the value string must be Base64-encoded binary data. The Base64 encoding is as defined in RFC 2045, section 6.8.

      Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

      Specified by:
      getByteArray in class Preferences
      Parameters:
      key - the preference key.
      deflt - the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid.
      Returns:
      the byte array value mapped to the given key.

    • getDouble

      public double getDouble​(String key, double deflt)
      Description copied from class: Preferences
      Gets the double value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.

      To be valid, the value string must be a string that can be converted to a double by Double.parseDouble(String).

      Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

      Specified by:
      getDouble in class Preferences
      Parameters:
      key - the preference key.
      deflt - the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid.
      Returns:
      the double value mapped to the given key.

    • getFloat

      public float getFloat​(String key, float deflt)
      Description copied from class: Preferences
      Gets the float value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.

      To be valid, the value string must be a string that can be converted to a float by Float.parseFloat(String).

      Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

      Specified by:
      getFloat in class Preferences
      Parameters:
      key - the preference key.
      deflt - the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid.
      Returns:
      the float value mapped to the given key.

    • getInt

      public int getInt​(String key, int deflt)
      Description copied from class: Preferences
      Gets the int value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.

      To be valid, the value string must be a string that can be converted to an int by Integer.parseInt(String).

      Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

      Specified by:
      getInt in class Preferences
      Parameters:
      key - the preference key.
      deflt - the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid.
      Returns:
      the integer value mapped to the given key.

    • getLong

      public long getLong​(String key, long deflt)
      Description copied from class: Preferences
      Gets the long value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.

      To be valid, the value string must be a string that can be converted to a long by Long.parseLong(String).

      Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

      Specified by:
      getLong in class Preferences
      Parameters:
      key - the preference key.
      deflt - the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid.
      Returns:
      the long value mapped to the given key.

    • isUserNode

      public boolean isUserNode()
      Description copied from class: Preferences
      Returns whether this is a user preference node.
      Specified by:
      isUserNode in class Preferences
      Returns:
      true, if this is a user preference node, false if this is a system preference node.

    • keys

      public String[] keys() throws BackingStoreException
      Description copied from class: Preferences
      Returns all preference keys stored in this node or an empty array if no key was found.
      Specified by:
      keys in class Preferences
      Returns:
      the list of all preference keys of this node.
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • name

      public String name()
      Description copied from class: Preferences
      Returns the name of this node.
      Specified by:
      name in class Preferences
      Returns:
      the name of this node.

    • node

      public Preferences node​(String name)
      Description copied from class: Preferences
      Returns the preference node with the given path name. The path name can be relative or absolute. The requested node and its ancestors will be created if they do not exist.

      The path is treated as relative to this node if it doesn't start with a slash, otherwise it will be treated as an absolute path.

      Specified by:
      node in class Preferences
      Parameters:
      name - the path name of the requested preference node.
      Returns:
      the requested preference node.

    • nodeExists

      public boolean nodeExists​(String name) throws BackingStoreException
      Description copied from class: Preferences
      Returns whether the preference node with the given path name exists. The path is treated as relative to this node if it doesn't start with a slash, otherwise it is treated as an absolute path.

      Please note that if this node has been removed, an invocation of this node will throw an IllegalStateException unless the given path is an empty string, which will return false.

      Specified by:
      nodeExists in class Preferences
      Parameters:
      name - the path name of the preference node to query.
      Returns:
      true, if the queried preference node exists, false otherwise.
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • parent

      public Preferences parent()
      Description copied from class: Preferences
      Returns the parent preference node of this node or null if this node is the root node.
      Specified by:
      parent in class Preferences
      Returns:
      the parent preference node of this node.

    • put

      public void put​(String key, String value)
      Description copied from class: Preferences
      Adds a new preference to this node using the given key and value or updates the value if a preference with the given key already exists.
      Specified by:
      put in class Preferences
      Parameters:
      key - the preference key to be added or updated.
      value - the preference value for the given key.

    • putBoolean

      public void putBoolean​(String key, boolean value)
      Description copied from class: Preferences
      Adds a new preference with a boolean value to this node using the given key and value or updates the value if a preference with the given key already exists.
      Specified by:
      putBoolean in class Preferences
      Parameters:
      key - the preference key to be added or updated.
      value - the preference boolean value for the given key.

    • putByteArray

      public void putByteArray​(String key, byte[] value)
      Description copied from class: Preferences
      Adds a new preference to this node using the given key and the string form of the given value or updates the value if a preference with the given key already exists.

      The string form of the value is the Base64-encoded binary data of the given byte array. The Base64 encoding is as defined in RFC 2045, section 6.8.

      Specified by:
      putByteArray in class Preferences
      Parameters:
      key - the preference key to be added or updated.
      value - the preference value for the given key.

    • putDouble

      public void putDouble​(String key, double value)
      Description copied from class: Preferences
      Adds a new preference to this node using the given key and double value or updates the value if a preference with the given key already exists.

      The value is stored in its string form, which is the result of invoking Double.toString(double).

      Specified by:
      putDouble in class Preferences
      Parameters:
      key - the preference key to be added or updated.
      value - the preference value for the given key.

    • putFloat

      public void putFloat​(String key, float value)
      Description copied from class: Preferences
      Adds a new preference to this node using the given key and float value or updates the value if a preference with the given key already exists.

      The value is stored in its string form, which is the result of invoking Float.toString(float).

      Specified by:
      putFloat in class Preferences
      Parameters:
      key - the preference key to be added or updated.
      value - the preference value for the given key.

    • putInt

      public void putInt​(String key, int value)
      Description copied from class: Preferences
      Adds a new preference to this node using the given key and int value or updates the value if a preference with the given key already exists.

      The value is stored in its string form, which is the result of invoking Integer.toString(int).

      Specified by:
      putInt in class Preferences
      Parameters:
      key - the preference key to be added or updated.
      value - the preference value for the given key.

    • putLong

      public void putLong​(String key, long value)
      Description copied from class: Preferences
      Adds a new preference to this node using the given key and long value or updates the value if a preference with the given key already exists.

      The value is stored in its string form, which is the result of invoking Long.toString(long).

      Specified by:
      putLong in class Preferences
      Parameters:
      key - the preference key to be added or updated.
      value - the preference value for the given key.

    • remove

      public void remove​(String key)
      Description copied from class: Preferences
      Removes the preference mapped to the given key from this node.
      Specified by:
      remove in class Preferences
      Parameters:
      key - the key of the preference to be removed.

    • removeNode

      public void removeNode() throws BackingStoreException
      Description copied from class: Preferences
      Removes this preference node with all its descendants. The removal won't necessarily be persisted until the method flush() is invoked.
      Specified by:
      removeNode in class Preferences
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • addNodeChangeListener

      public void addNodeChangeListener​(NodeChangeListener ncl)
      Description copied from class: Preferences
      Registers a NodeChangeListener instance for this node, which will handle NodeChangeEvents. NodeChangeEvents will be fired when a child node has been added to or removed from this node.
      Specified by:
      addNodeChangeListener in class Preferences
      Parameters:
      ncl - the listener to be registered.

    • addPreferenceChangeListener

      public void addPreferenceChangeListener​(PreferenceChangeListener pcl)
      Description copied from class: Preferences
      Registers a PreferenceChangeListener instance for this node, which will handle PreferenceChangeEvents. PreferenceChangeEvents will be fired when a preference has been added to, removed from, or updated for this node.
      Specified by:
      addPreferenceChangeListener in class Preferences
      Parameters:
      pcl - the listener to be registered.

    • removeNodeChangeListener

      public void removeNodeChangeListener​(NodeChangeListener ncl)
      Description copied from class: Preferences
      Removes the given NodeChangeListener instance from this node.
      Specified by:
      removeNodeChangeListener in class Preferences
      Parameters:
      ncl - the listener to be removed.

    • removePreferenceChangeListener

      public void removePreferenceChangeListener​(PreferenceChangeListener pcl)
      Description copied from class: Preferences
      Removes the given PreferenceChangeListener instance from this node.
      Specified by:
      removePreferenceChangeListener in class Preferences
      Parameters:
      pcl - the listener to be removed.

    • sync

      public void sync() throws BackingStoreException
      Description copied from class: Preferences
      Synchronizes the data of this preference node and its descendants with the back-end preference store. Any changes found in the back-end data should be reflected in this node and its descendants, and at the same time any local changes to this node and descendants should be persisted.
      Specified by:
      sync in class Preferences
      Throws:
      BackingStoreException - if the backing store is unavailable or causes an operation failure.

    • toString

      public String toString()
      Description copied from class: Preferences
      Returns a string representation of this node. The format is "User/System Preference Node: " followed by this node's absolute path.
      Specified by:
      toString in class Preferences
      Returns:
      the string representation of this node.