Package rs.baselib.prefs

Class AbstractPreferences

java.lang.Object
rs.baselib.prefs.AbstractPreferences
All Implemented Interfaces:
IPreferences
Direct Known Subclasses:
Preferences
public abstract class AbstractPreferences extends Object implements IPreferences
Abstract implementation of a preference node. All modifications are performed synchronously.
Author:
ralph

  • Constructor Details

    • AbstractPreferences

      public AbstractPreferences()
      Constructor. Creates a root node.

    • AbstractPreferences

      public AbstractPreferences(AbstractPreferences parent, String name)
      Constructor.
      Parameters:
      parent - the parent of this node
      name - the name of this preferences

  • Method Details

    • createReadLock

      protected abstract Lock createReadLock()
      Creates the appropriate read lock object.
      Returns:
      the read lock object

    • createWriteLock

      protected abstract Lock createWriteLock()
      Creates the appropriate write lock object.
      Returns:
      the write lock object

    • getReadLock

      public Lock getReadLock()
      Returns the readLock.
      Returns:
      the readLock

    • readLock

      protected void readLock()
      Aquires a read lock.

    • readUnlock

      protected void readUnlock()
      Releases a read lock.

    • getWriteLock

      public Lock getWriteLock()
      Returns the writeLock.
      Returns:
      the writeLock

    • writeLock

      protected void writeLock()
      Aquires a write lock.

    • writeUnlock

      protected void writeUnlock()
      Releases a write lock.

    • createNode

      protected abstract AbstractPreferences createNode(AbstractPreferences parent, String name)
      Subclasses must implement this to return a new child node.
      Parameters:
      parent - the parent to be used
      name - the name to be used
      Returns:
      the new node

    • addNode

      protected void addNode(AbstractPreferences child)
      Adds the given node. The scheduling policy will define whether this task is executed immediately or performed by a background task (which requires a flush() call to access the node later).
      Parameters:
      child - child to be added

    • removeNode

      protected void removeNode(AbstractPreferences child)
      Removes the given node. The scheduling policy will define whether this task is executed immediately or performed by a background task (which requires a flush() to see the result).
      Parameters:
      child - child to be removed

    • put

      public void put(String key, String value)
      Associates the specified value with the specified key in this node.
      Specified by:
      put in interface IPreferences
      Parameters:
      key - key with which the specified value is to be associated.
      value - value to be associated with the specified key.

    • get

      public String get(String key, String def)
      Returns the value associated with the specified key in this node. Returns the specified default if there is no value associated with the key, or the backing store is inaccessible.
      Specified by:
      get in interface IPreferences
      Parameters:
      key - key whose associated value is to be returned.
      def - the value to be returned in the event that this node has no value associated with key or the backing store is inaccessible.
      Returns:
      the value associated with key, or def if no value is associated with key.

    • remove

      public void remove(String key)
      Removes the value associated with the specified key in this node, if any.
      Specified by:
      remove in interface IPreferences
      Parameters:
      key - key whose mapping is to be removed from this node.
      See Also:

    • clear

      public void clear() throws BackingStoreException
      Removes all of the properties (key-value associations) in this node. This call has no effect on any descendants of this node.
      Specified by:
      clear in interface IPreferences
      Throws:
      BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
      See Also:

    • putInt

      public void putInt(String key, int value)
      Associates a String object representing the specified int value with the specified key in this node. The associated string is the one that would be returned if the int value were passed to Integer.toString(int). This method is intended for use in conjunction with IPreferences.getInt(java.lang.String, int) method.

      Implementor's note: it is not necessary that the property value be represented by a String object in the backing store. If the backing store supports integer values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as an int (with getInt or a String (with get) type.

      Specified by:
      putInt in interface IPreferences
      Parameters:
      key - key with which the string form of value is to be associated.
      value - value whose string form is to be associated with key.
      See Also:

    • getInt

      public int getInt(String key, int def)
      Returns the int value represented by the String object associated with the specified key in this node. The String object is converted to an int as by Integer.parseInt(String). Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Integer.parseInt(String) would throw a NumberFormatException if the associated value were passed. This method is intended for use in conjunction with the IPreferences.putInt(java.lang.String, int) method.
      Specified by:
      getInt in interface IPreferences
      Parameters:
      key - key whose associated value is to be returned as an int.
      def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as an int or the backing store is inaccessible.
      Returns:
      the int value represented by the String object associated with key in this node, or def if the associated value does not exist or cannot be interpreted as an int type.
      See Also:

    • putLong

      public void putLong(String key, long value)
      Associates a String object representing the specified long value with the specified key in this node. The associated String object is the one that would be returned if the long value were passed to Long.toString(long). This method is intended for use in conjunction with the IPreferences.getLong(java.lang.String, long) method.

      Implementor's note: it is not necessary that the value be represented by a String type in the backing store. If the backing store supports long values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as a long (with getLong or a String (with get) type.

      Specified by:
      putLong in interface IPreferences
      Parameters:
      key - key with which the string form of value is to be associated.
      value - value whose string form is to be associated with key.
      See Also:

    • getLong

      public long getLong(String key, long def)
      Returns the long value represented by the String object associated with the specified key in this node. The String object is converted to a long as by Long.parseLong(String). Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Long.parseLong(String) would throw a NumberFormatException if the associated value were passed. This method is intended for use in conjunction with the IPreferences.putLong(java.lang.String, long) method.
      Specified by:
      getLong in interface IPreferences
      Parameters:
      key - key whose associated value is to be returned as a long value.
      def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a long type or the backing store is inaccessible.
      Returns:
      the long value represented by the String object associated with key in this node, or def if the associated value does not exist or cannot be interpreted as a long type.
      See Also:

    • putBoolean

      public void putBoolean(String key, boolean value)
      Associates a String object representing the specified boolean value with the specified key in this node. The associated string is "true" if the value is true, and "false" if it is false. This method is intended for use in conjunction with the IPreferences.getBoolean(java.lang.String, boolean) method.

      Implementor's note: it is not necessary that the value be represented by a string in the backing store. If the backing store supports boolean values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as a boolean (with getBoolean) or a String (with get) type.

      Specified by:
      putBoolean in interface IPreferences
      Parameters:
      key - key with which the string form of value is to be associated.
      value - value whose string form is to be associated with key.
      See Also:

    • getBoolean

      public boolean getBoolean(String key, boolean def)
      Returns the boolean value represented by the String object associated with the specified key in this node. Valid strings are "true", which represents true, and "false", which represents false. Case is ignored, so, for example, "TRUE" and "False" are also valid. This method is intended for use in conjunction with the IPreferences.putBoolean(java.lang.String, boolean) method.

      Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is something other than "true" or "false", ignoring case.

      Specified by:
      getBoolean in interface IPreferences
      Parameters:
      key - key whose associated value is to be returned as a boolean.
      def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a boolean or the backing store is inaccessible.
      Returns:
      the boolean value represented by the String object associated with key in this node, or null if the associated value does not exist or cannot be interpreted as a boolean.
      See Also:

    • putFloat

      public void putFloat(String key, float value)
      Associates a String object representing the specified float value with the specified key in this node. The associated String object is the one that would be returned if the float value were passed to Float.toString(float). This method is intended for use in conjunction with the IPreferences.getFloat(java.lang.String, float) method.

      Implementor's note: it is not necessary that the value be represented by a string in the backing store. If the backing store supports float values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as a float (with getFloat) or a String (with get) type.

      Specified by:
      putFloat in interface IPreferences
      Parameters:
      key - key with which the string form of value is to be associated.
      value - value whose string form is to be associated with key.
      See Also:

    • getFloat

      public float getFloat(String key, float def)
      Returns the float value represented by the String object associated with the specified key in this node. The String object is converted to a float value as by Float.parseFloat(String). Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Float.parseFloat(String) would throw a NumberFormatException if the associated value were passed. This method is intended for use in conjunction with the IPreferences.putFloat(java.lang.String, float) method.
      Specified by:
      getFloat in interface IPreferences
      Parameters:
      key - key whose associated value is to be returned as a float value.
      def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a float type or the backing store is inaccessible.
      Returns:
      the float value represented by the string associated with key in this node, or def if the associated value does not exist or cannot be interpreted as a float type.
      See Also:

    • putDouble

      public void putDouble(String key, double value)
      Associates a String object representing the specified double value with the specified key in this node. The associated String object is the one that would be returned if the double value were passed to Double.toString(double). This method is intended for use in conjunction with the IPreferences.getDouble(java.lang.String, double) method

      Implementor's note: it is not necessary that the value be represented by a string in the backing store. If the backing store supports double values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as a double (with getDouble) or a String (with get) type.

      Specified by:
      putDouble in interface IPreferences
      Parameters:
      key - key with which the string form of value is to be associated.
      value - value whose string form is to be associated with key.
      See Also:

    • getDouble

      public double getDouble(String key, double def)
      Returns the double value represented by the String object associated with the specified key in this node. The String object is converted to a double value as by Double.parseDouble(String). Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Double.parseDouble(String) would throw a NumberFormatException if the associated value were passed. This method is intended for use in conjunction with the IPreferences.putDouble(java.lang.String, double) method.
      Specified by:
      getDouble in interface IPreferences
      Parameters:
      key - key whose associated value is to be returned as a double value.
      def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a double type or the backing store is inaccessible.
      Returns:
      the double value represented by the String object associated with key in this node, or def if the associated value does not exist or cannot be interpreted as a double type.
      See Also:

    • putByteArray

      public void putByteArray(String key, byte[] value)
      Associates a String object representing the specified byte[] with the specified key in this node. The associated String object the Base64 encoding of the byte[], as defined in RFC 2045 , Section 6.8, with one minor change: the string will consist solely of characters from the Base64 Alphabet ; it will not contain any newline characters. This method is intended for use in conjunction with the IPreferences.getByteArray(java.lang.String, byte[]) method.

      Implementor's note: it is not necessary that the value be represented by a String type in the backing store. If the backing store supports byte[] values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as an a byte[] object (with getByteArray) or a String object (with get).

      Specified by:
      putByteArray in interface IPreferences
      Parameters:
      key - key with which the string form of value is to be associated.
      value - value whose string form is to be associated with key.
      See Also:

    • getByteArray

      public byte[] getByteArray(String key, byte[] def)
      Returns the byte[] value represented by the String object associated with the specified key in this node. Valid String objects are Base64 encoded binary data, as defined in RFC 2045 , Section 6.8, with one minor change: the string must consist solely of characters from the Base64 Alphabet ; no newline characters or extraneous characters are permitted. This method is intended for use in conjunction with the IPreferences.putByteArray(java.lang.String, byte[]) method.

      Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is not a valid Base64 encoded byte array (as defined above).

      Specified by:
      getByteArray in interface IPreferences
      Parameters:
      key - key whose associated value is to be returned as a byte[] object.
      def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a byte[] type, or the backing store is inaccessible.
      Returns:
      the byte[] value represented by the String object associated with key in this node, or def if the associated value does not exist or cannot be interpreted as a byte[].
      See Also:

    • keys

      public String[] keys() throws BackingStoreException
      Returns all of the keys that have an associated value in this node. (The returned array will be of size zero if this node has no preferences and not null!)
      Specified by:
      keys in interface IPreferences
      Returns:
      an array of the keys that have an associated value in this node.
      Throws:
      BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

    • childrenNames

      public String[] childrenNames() throws BackingStoreException
      Returns the names of the children of this node. (The returned array will be of size zero if this node has no children and not null!)
      Specified by:
      childrenNames in interface IPreferences
      Returns:
      the names of the children of this node.
      Throws:
      BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

    • parent

      public IPreferences parent()
      Returns the parent of this node, or null if this is the root.
      Specified by:
      parent in interface IPreferences
      Returns:
      the parent of this node.

    • isRelative

      protected boolean isRelative(String pathName)
      Returns true when the given pathname is relative to this node. This means the path does not start with a slash ('/').
      Parameters:
      pathName - name to be checked
      Returns:
      true when path name is relative to this node

    • isAbsolute

      protected boolean isAbsolute(String pathName)
      Returns true when the given pathname is absolute to root node of this node. This means the path starts with a slash ('/').
      Parameters:
      pathName - name to be checked
      Returns:
      true when path name is absolute to root node of this node

    • isRootNode

      protected boolean isRootNode()
      Returns true when this is a root node.
      Returns:
      true when this is a root node

    • getRootNode

      protected AbstractPreferences getRootNode()
      Returns the root node of this node.
      Returns:
      root node

    • node

      public IPreferences node(String pathName)
      Returns a named Preferences object (node), creating it and any of its ancestors if they do not already exist. Accepts a relative or absolute pathname. Absolute pathnames (which begin with '/') are interpreted relative to the root of this node. Relative pathnames (which begin with any character other than '/') are interpreted relative to this node itself. The empty string ("") is a valid relative pathname, referring to this node itself.

      If the returned node did not exist prior to this call, this node and any ancestors that were created by this call are not guaranteed to become persistent until the flush method is called on the returned node (or one of its descendants).

      Specified by:
      node in interface IPreferences
      Parameters:
      pathName - the path name of the Preferences object to return.
      Returns:
      the specified Preferences object.
      See Also:

    • nodeExists

      public boolean nodeExists(String pathName) throws BackingStoreException
      Returns true if the named node exists. Accepts a relative or absolute pathname. Absolute pathnames (which begin with '/') are interpreted relative to the root of this node. Relative pathnames (which begin with any character other than '/') are interpreted relative to this node itself. The pathname "" is valid, and refers to this node itself.

      If this node (or an ancestor) has already been removed with the IPreferences.removeNode() method, it is legal to invoke this method, but only with the pathname ""; the invocation will return false. Thus, the idiom p.nodeExists("") may be used to test whether p has been removed.

      Specified by:
      nodeExists in interface IPreferences
      Parameters:
      pathName - the path name of the node whose existence is to be checked.
      Returns:
      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.

    • removeNode

      public void removeNode() throws BackingStoreException
      Removes this node and all of its descendants, invalidating any properties contained in the removed nodes. Once a node has been removed, attempting any method other than name(),absolutePath() or nodeExists("") on the corresponding Preferences instance will fail with an IllegalStateException. (The methods defined on Object can still be invoked on a node after it has been removed; they will not throw IllegalStateException.)

      The removal is not guaranteed to be persistent until the flush method is called on the parent of this node.

      Specified by:
      removeNode in interface IPreferences
      Throws:
      BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
      See Also:

    • name

      public String name()
      Returns this node's name, relative to its parent.
      Specified by:
      name in interface IPreferences
      Returns:
      this node's name, relative to its parent.

    • absolutePath

      public String absolutePath()
      Returns this node's absolute path name. Note that:
      • Root node - The path name of the root node is "/".
      • Slash at end - Path names other than that of the root node may not end in slash ('/').
      • Unusual names -"." and ".." have no special significance in path names.
      • Illegal names - The only illegal path names are those that contain multiple consecutive slashes, or that end in slash and are not the root.
      Specified by:
      absolutePath in interface IPreferences
      Returns:
      this node's absolute path name.

    • getPreferencesService

      protected abstract AbstractPreferencesService getPreferencesService()
      Returns the preferences service.
      Returns:
      the preferences service

    • flush

      public void flush() throws BackingStoreException
      Forces any changes in the contents of this node and its descendants to the persistent store.

      Once this method returns successfully, it is safe to assume that all changes made in the subtree rooted at this node prior to the method invocation have become permanent.

      Implementations are free to flush changes into the persistent store at any time. They do not need to wait for this method to be called.

      When a flush occurs on a newly created node, it is made persistent, as are any ancestors (and descendants) that have yet to be made persistent. Note however that any properties value changes in ancestors are not guaranteed to be made persistent.

      Specified by:
      flush in interface IPreferences
      Throws:
      BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
      See Also:

    • sync

      public void sync() throws BackingStoreException
      Ensures that future reads from this node and its descendants reflect any changes that were committed to the persistent store (from any VM) prior to the sync invocation. As a side-effect, forces any changes in the contents of this node and its descendants to the persistent store, as if the flush method had been invoked on this node.
      Specified by:
      sync in interface IPreferences
      Throws:
      BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
      See Also:

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener listener)

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener listener)

    • addPropertyChangeListener

      public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)

    • removePropertyChangeListener

      public void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)

    • firePropertyChange

      protected boolean firePropertyChange(String propertyName, Object oldValue, Object newValue)
      Fires an event if property changed.
      Parameters:
      propertyName - name of property
      oldValue - old value
      newValue - new value
      Returns:
      true when the event was fired (because values were not equal)

    • firePropertyChange

      protected boolean firePropertyChange(PropertyChangeEvent event)
      Fires a change event.
      Parameters:
      event - event to be fired
      Returns:
      true when the event was fired (because values were not equal)