Preferences
Date: 2016-06-25

org.osgi.service.prefs

## Interface Preferences

-     public interface Preferences

  A node in a hierarchical collection of preference data.

  This interface allows applications to store and retrieve user and system preference data. This data is stored persistently in an implementation-dependent backing store. Typical implementations include flat files, OS-specific registries, directory servers and SQL databases.

  For each bundle, there is a separate tree of nodes for each user, and one for system preferences. The precise description of "user" and "system" will vary from one bundle to another. Typical information stored in the user preference tree might include font choice, and color choice for a bundle which interacts with the user via a servlet. Typical information stored in the system preference tree might include installation data, or things like high score information for a game program.

  Nodes in a preference tree are named in a similar fashion to directories in a hierarchical file system. Every node in a preference tree has a node name (which is not necessarily unique), a unique absolute path name , and a path name relative to each ancestor including itself.

  The root node has a node name of the empty `String` object (""). Every other node has an arbitrary node name, specified at the time it is created. The only restrictions on this name are that it cannot be the empty string, and it cannot contain the slash character ('/').

  The root node has an absolute path name of `"/"`. Children of the root node have absolute path names of `"/" +` <node name> . All other nodes have absolute path names of <parent's absolute path name> `+ "/" +` <node name> . Note that all absolute path names begin with the slash character.

  A node n 's path name relative to its ancestor a is simply the string that must be appended to a 's absolute path name in order to form n 's absolute path name, with the initial slash character (if present) removed. Note that:

  - No relative path names begin with the slash character.
  - Every node's path name relative to itself is the empty string.
  - Every node's path name relative to its parent is its node name (except for the root node, which does not have a parent).
  - Every node's path name relative to the root is its absolute path name with the initial slash character removed.

  Note finally that:

  - No path name contains multiple consecutive slash characters.
  - No path name with the exception of the root's absolute path name end in the slash character.
  - Any string that conforms to these two rules is a valid path name.

  Each `Preference` node has zero or more properties associated with it, where a property consists of a name and a value. The bundle writer is free to choose any appropriate names for properties. Their values can be of type `String`,`long`,`int`,`boolean`, `byte[]`, `float`, or `double` but they can always be accessed as if they were `String` objects.

  All node name and property name comparisons are case-sensitive.

  All of the methods that modify preference data are permitted to operate asynchronously; they may return immediately, and changes will eventually propagate to the persistent backing store, with an implementation-dependent delay. The `flush` method may be used to synchronously force updates to the backing store.

  Implementations must automatically attempt to flush to the backing store any pending updates for a bundle's preferences when the bundle is stopped or otherwise ungets the Preferences Service.

  The methods in this class may be invoked concurrently by multiple threads in a single Java Virtual Machine (JVM) without the need for external synchronization, and the results will be equivalent to some serial execution. If this class is used concurrently by multiple JVMs that store their preference data in the same backing store, the data store will not be corrupted, but no other guarantees are made concerning the consistency of the preference data.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `absolutePath()` Returns this node's absolute path name.
    `java.lang.String[]` | `childrenNames()` Returns the names of the children of this node.
    `void` | `clear()` Removes all of the properties (key-value associations) in this node.
    `void` | `flush()` Forces any changes in the contents of this node and its descendants to the persistent store.
    `java.lang.String` | `get(java.lang.String key, java.lang.String def)` Returns the value associated with the specified `key` in this node.
    `boolean` | `getBoolean(java.lang.String key, boolean def)` Returns the `boolean` value represented by the `String` object associated with the specified `key` in this node.
    `byte[]` | `getByteArray(java.lang.String key, byte[] def)` Returns the `byte[]` value represented by the `String` object associated with the specified `key` in this node.
    `double` | `getDouble(java.lang.String key, double def)` Returns the `double` value represented by the `String` object associated with the specified `key` in this node.
    `float` | `getFloat(java.lang.String key, float def)` Returns the float `value` represented by the `String` object associated with the specified `key` in this node.
    `int` | `getInt(java.lang.String key, int def)` Returns the `int` value represented by the `String` object associated with the specified `key` in this node.
    `long` | `getLong(java.lang.String key, long def)` Returns the `long` value represented by the `String` object associated with the specified `key` in this node.
    `java.lang.String[]` | `keys()` Returns all of the keys that have an associated value in this node.
    `java.lang.String` | `name()` Returns this node's name, relative to its parent.
    `Preferences` | `node(java.lang.String pathName)` Returns a named `Preferences` object (node), creating it and any of its ancestors if they do not already exist.
    `boolean` | `nodeExists(java.lang.String pathName)` Returns true if the named node exists.
    `Preferences` | `parent()` Returns the parent of this node, or `null` if this is the root.
    `void` | `put(java.lang.String key, java.lang.String value)` Associates the specified value with the specified key in this node.
    `void` | `putBoolean(java.lang.String key, boolean value)` Associates a `String` object representing the specified `boolean` value with the specified key in this node.
    `void` | `putByteArray(java.lang.String key, byte[] value)` Associates a `String` object representing the specified `byte[]` with the specified `key` in this node.
    `void` | `putDouble(java.lang.String key, double value)` Associates a `String` object representing the specified `double` value with the specified `key` in this node.
    `void` | `putFloat(java.lang.String key, float value)` Associates a `String` object representing the specified `float` value with the specified `key` in this node.
    `void` | `putInt(java.lang.String key, int value)` Associates a `String` object representing the specified `int` value with the specified `key` in this node.
    `void` | `putLong(java.lang.String key, long value)` Associates a `String` object representing the specified `long` value with the specified `key` in this node.
    `void` | `remove(java.lang.String key)` Removes the value associated with the specified `key` in this node, if any.
    `void` | `removeNode()` Removes this node and all of its descendants, invalidating any properties contained in the removed nodes.
    `void` | `sync()` 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.

- - ### Method Detail

    - #### put

          void put(java.lang.String key,
                 java.lang.String value)

      Associates the specified value with the specified key in this node.
      Parameters:
        `key` - key with which the specified value is to be associated.
        `value` - value to be associated with the specified key.
      Throws:
        `java.lang.NullPointerException` - if `key` or `value` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.

    - #### get

          java.lang.String get(java.lang.String key,
                             java.lang.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.
      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`.
      Throws:
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
        `java.lang.NullPointerException` - if `key` is `null`. (A `null` default is permitted.)

    - #### remove

          void remove(java.lang.String key)

      Removes the value associated with the specified `key` in this node, if any.
      Parameters:
        `key` - key whose mapping is to be removed from this node.
      Throws:
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `get(String,String)`

    - #### clear

          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.
      Throws:
        `BackingStoreException` - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `remove(String)`

    - #### putInt

          void putInt(java.lang.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 `getInt(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.

      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`.
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `getInt(String,int)`

    - #### getInt

          int getInt(java.lang.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 `putInt(String, int)` method.
      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.
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `putInt(String,int)`, `get(String,String)`

    - #### putLong

          void putLong(java.lang.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 `getLong(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.

      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`.
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `getLong(String,long)`

    - #### getLong

          long getLong(java.lang.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 `putLong(String, long)` method.
      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.
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `putLong(String,long)`, `get(String,String)`

    - #### putBoolean

          void putBoolean(java.lang.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 `getBoolean(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.

      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` .
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `getBoolean(String,boolean)`, `get(String,String)`

    - #### getBoolean

          boolean getBoolean(java.lang.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 `putBoolean(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.

      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`.
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `get(String,String)`, `putBoolean(String,boolean)`

    - #### putFloat

          void putFloat(java.lang.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 `getFloat(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.

      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` .
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `getFloat(String,float)`

    - #### getFloat

          float getFloat(java.lang.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 `putFloat(String, float)` method.
      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.
      Throws:
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
        `java.lang.NullPointerException` - if `key` is `null`.
      See Also:
        `putFloat(String,float)`, `get(String,String)`

    - #### putDouble

          void putDouble(java.lang.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 `getDouble(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.

      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` .
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `getDouble(String,double)`

    - #### getDouble

          double getDouble(java.lang.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 `putDouble(java.lang.String, double)` method.
      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.
      Throws:
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
        `java.lang.NullPointerException` - if `key` is `null`.
      See Also:
        `putDouble(String,double)`, `get(String,String)`

    - #### putByteArray

          void putByteArray(java.lang.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 `getByteArray(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` ).

      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`.
      Throws:
        `java.lang.NullPointerException` - if `key` or `value` is `null`.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `getByteArray(String,byte[])`, `get(String,String)`

    - #### getByteArray

          byte[] getByteArray(java.lang.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 `putByteArray(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).

      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[]`.
      Throws:
        `java.lang.NullPointerException` - if `key` is `null`. (A `null` value for `def` is permitted.)
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `get(String,String)`, `putByteArray(String,byte[])`

    - #### keys

          java.lang.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`!)
      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.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.

    - #### childrenNames

          java.lang.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`!)
      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.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.

    - #### parent

          Preferences parent()

      Returns the parent of this node, or `null` if this is the root.
      Returns:
        the parent of this node.
      Throws:
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.

    - #### node

          Preferences node(java.lang.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).

      Parameters:
        `pathName` - the path name of the `Preferences` object to return.
      Returns:
        the specified `Preferences` object.
      Throws:
        `java.lang.IllegalArgumentException` - if the path name is invalid.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
        `java.lang.NullPointerException` - if path name is `null`.
      See Also:
        `flush()`

    - #### nodeExists

          boolean nodeExists(java.lang.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 `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.

      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.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method and `pathname` is not the empty string (`""`).
        `java.lang.IllegalArgumentException` - if the path name is invalid (i.e., it contains multiple consecutive slash characters, or ends with a slash character and is more than one character long).

    - #### removeNode

          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.

      Throws:
        `java.lang.IllegalStateException` - if this node (or an ancestor) has already been removed with the `removeNode()` method.
        `BackingStoreException` - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
      See Also:
        `flush()`

    - #### name

          java.lang.String name()

      Returns this node's name, relative to its parent.
      Returns:
        this node's name, relative to its parent.

    - #### absolutePath

          java.lang.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.
      Returns:
        this node's absolute path name.

    - #### flush

          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.

      Throws:
        `BackingStoreException` - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `sync()`

    - #### sync

          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.
      Throws:
        `BackingStoreException` - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
        `java.lang.IllegalStateException` - if this node (or an ancestor) has been removed with the `removeNode()` method.
      See Also:
        `flush()`