preferences.java

OSGI这是一个中间件,与UPNP齐名,是用于移植到嵌入式平台之上

    /**
     * Returns the <tt>byte[]</tt> value represented by the <tt>String</tt> object associated with
     * the specified <tt>key</tt> in this node.  Valid <tt>String</tt> objects are
     * <i>Base64</i> encoded binary data, as defined in 
	 * <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>, Section 6.8,
     * with one minor change: the string must consist solely of characters
     * from the <i>Base64 Alphabet</i>; no newline characters or
     * extraneous characters are permitted.  This method is intended for use
     * in conjunction with the {@link #putByteArray} method.
     *
     * <p>Returns the specified default if there is no value
     * associated with the <tt>key</tt>, the backing store is inaccessible, or if the
     * associated value is not a valid Base64 encoded byte array
     * (as defined above).
     *
     * @param key <tt>key</tt> whose associated value is to be returned as a <tt>byte[]</tt> object.
     * @param def the value to be returned in the event that this
     *        node has no value associated with <tt>key</tt>
     *        or the associated value cannot be interpreted as a <tt>byte[]</tt> type,
     *        or the backing store is inaccessible.
     * @return the <tt>byte[]</tt> value represented by the <tt>String</tt> object associated with
     *         <tt>key</tt> in this node, or <tt>def</tt> if the
     *         associated value does not exist or cannot be interpreted as
     *         a <tt>byte[]</tt>.
     * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>. (A 
     *         <tt>null</tt> value for <tt>def</tt> <i>is</i> permitted.)
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     * @see #get(String,String)
     * @see #putByteArray(String,byte[])
     */
    public abstract byte[] getByteArray(String key, byte[] def);

    /**
     * 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 <tt>null</tt>!)
     *
     * @return 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.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     */
    public abstract String[] keys() 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 <tt>null</tt>!)
     *
     * @return 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.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     */
    public abstract String[] childrenNames() throws BackingStoreException;

    /**
     * Returns the parent of this node, or <tt>null</tt> if this is
     * the root.
     *
     * @return the parent of this node.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     */
    public abstract Preferences parent();

    /**
     * Returns a named <tt>Preferences</tt> 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 <tt>'/'</tt>) are interpreted
     * relative to the root of this node.  Relative pathnames
     * (which begin with any character other than <tt>'/'</tt>) are
     * interpreted relative to this node itself.  The empty string
     * (<tt>""</tt>) is a valid relative pathname, referring to this
     * node itself.
     *
     * <p>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 <tt>flush</tt> method is called on
     * the returned node (or one of its descendants).
     *
     * @param pathName the path name of the <tt>Preferences</tt> object to return.
     * @return the specified <tt>Preferences</tt> object.
     * @throws IllegalArgumentException if the path name is invalid.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     * @throws NullPointerException if path name is <tt>null</tt>.
     * @see #flush()
     */
    public abstract Preferences node(String pathName);

    /**
     * Returns true if the named node exists.  Accepts a relative
     * or absolute pathname.  Absolute pathnames (which begin with
     * <tt>'/'</tt>) are interpreted relative to the root of this
     * node.  Relative pathnames (which begin with any character other than
     * <tt>'/'</tt>) are interpreted relative to this node itself.
     * The pathname <tt>""</tt> is valid, and refers to this node
     * itself.
     *
     * <p>If this node (or an ancestor) has already been removed with the
     * {@link #removeNode()}method, it <i>is</i> legal to invoke this method,
     * but only with the pathname <tt>""</tt>; the invocation will return
     * <tt>false</tt>.  Thus, the idiom <tt>p.nodeExists("")</tt> may be
     * used to test whether <tt>p</tt> has been removed.
     *
     * @param pathName the path name of the node whose existence
     *        is to be checked.
     * @return 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.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method and
     *         <tt>pathname</tt> is not the empty string (<tt>""</tt>).
     * @throws 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).
     */
    public abstract boolean nodeExists(String pathName)
        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 <tt>name()</tt>,
     * <tt>absolutePath()</tt> or
     * <tt>nodeExists("")</tt> on the corresponding <tt>Preferences</tt>
     * instance will fail with an <tt>IllegalStateException</tt>.  (The
     * methods defined on <tt>Object</tt> can still be invoked on a node after
     * it has been removed; they will not throw
     * <tt>IllegalStateException</tt>.)
     *
     * <p>The removal is not guaranteed to be persistent until the
     * <tt>flush</tt> method is called on the parent of this node.
     * (It is illegal to remove the root node.)
     *
     * @throws IllegalStateException if this node (or an ancestor) has already
     *         been removed with the {@link #removeNode()}method.
     * @throws RuntimeException if this is a root node.
     * @throws BackingStoreException if this operation cannot be
     *         completed due to a failure in the backing store, or 
     *         inability to communicate with it.
     * @see #flush()
     */
    public abstract void removeNode()
    throws BackingStoreException;

    /**
     * Returns this node's name, relative to its parent.
     *
     * @return this node's name, relative to its parent.
     */
    public abstract String name();

    /**
     * Returns this node's absolute path name.  Note that:
     * <ul>
     *     <li>Root node - The path name of the root node is <tt>"/"</tt>.
     *     <li>Slash at end - Path names other than that of the root node may not end in
     *     slash (<tt>'/'</tt>).
     *     <li>Unusual names - <tt>"."</tt> and <tt>".."</tt> have <i>no</i> special significance
     *     in path names.
     *     <li>Illegal names - The only illegal path names are those that contain multiple
     *     consecutive slashes, or that end in slash and are not the root.
     * </ul>
     *
     * @return this node's absolute path name.
     */
    public abstract String absolutePath();

    /**
     * Forces any changes in the contents of this node and its
     * descendants to the persistent store.
     *
     * <p>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.
     *
     * <p>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.
     *
     * <p>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 <i>not</i> 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.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     * @see    #sync()
     */
    public abstract void flush() 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 <tt>sync</tt> invocation.  As a
     * side-effect, forces any changes in the contents of this node
     * and its descendants to the persistent store, as if the <tt>flush</tt>
     * 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.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     * @see    #flush()
     */
    public abstract void sync() throws BackingStoreException;

}