preferences.java

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

/*
 * @(#)Preferences.java 1.7 01/07/18
 * $Header: /cvshome/repository/org/osgi/service/prefs/Preferences.java,v 1.17 2002/10/08 06:43:04 pkriens Exp $
 *
 * Open Services Gateway Initiative (OSGi) Confidential.
 *
 * (C) Copyright 1996-2001 Sun Microsystems, Inc.
 *
 * This source code is licensed to OSGi as MEMBER LICENSED MATERIALS
 * under the terms of Section 3.2 of the OSGi MEMBER AGREEMENT.
 *
 */

package org.osgi.service.prefs;

import java.util.*;
import java.io.*;

/**
 * A node in a hierarchical collection of preference data.
 *
 * <p>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.
 *
 * <p>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.
 *
 * <p>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 <i>node name</i> (which is not necessarily unique),
 * a unique <i>absolute path name</i>, and a path name <i>relative</i> to each
 * ancestor including itself.
 *
 * <p>The root node has a node name of the empty <tt>String</tt> 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 ('/').
 *
 * <p>The root node has an absolute path name of <tt>"/"</tt>.  Children of
 * the root node have absolute path names of <tt>"/" + </tt><i>&lt;node
 * name&gt;</i>.  All other nodes have absolute path names of <i>&lt;parent's
 * absolute path name&gt;</i><tt> + "/" + </tt><i>&lt;node name&gt;</i>.
 * Note that all absolute path names begin with the slash character.
 *
 * <p>A node <i>n</i>'s path name relative to its ancestor <i>a</i>
 * is simply the string that must be appended to <i>a</i>'s absolute path name
 * in order to form <i>n</i>'s absolute path name, with the initial slash
 * character (if present) removed.  Note that:
 * <ul>
 * <li>No relative path names begin with the slash character.
 * <li>Every node's path name relative to itself is the empty string.
 * <li>Every node's path name relative to its parent is its node name (except
 * for the root node, which does not have a parent).
 * <li>Every node's path name relative to the root is its absolute path name
 * with the initial slash character removed.
 * </ul>
 *
 * <p>Note finally that:
 * <ul>
 * <li>No path name contains multiple consecutive slash characters.
 * <li>No path name with the exception of the root's absolute path name
 * end in the slash character.
 * <li>Any string that conforms to these two rules is a valid path name.
 * </ul>
 *
 * <p>Each <tt>Preference</tt> 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 <tt>String</tt>, <tt>long</tt>, <tt>int</tt>, <tt>boolean</tt>,
 * <tt>byte[]</tt>, <tt>float</tt>, or <tt>double</tt> but
 * they can always be accessed as if they were <tt>String</tt> objects.
 *
 * <p>All node name and property name comparisons are case-sensitive.
 *
 * <p>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 <tt>flush</tt> method
 * may be used to synchronously force updates to the backing store.
 *
 * <p>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.
 *
 * <p>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 <i>by multiple JVMs</i> 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.
 *
 *
 * @version $Revision: 1.17 $
 * @author Open Services Gateway Initiative
*/

public interface Preferences {

    /**
     * Associates the specified value with the specified key in this
     * node.
     *
     * @param key key with which the specified value is to be associated.
     * @param value value to be associated with the specified key.
     * @throws NullPointerException if <tt>key</tt> or <tt>value</tt> is <tt>null</tt>.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     */
    public abstract void put(String key, String value);

    /**
     * Returns the value associated with the specified <tt>key</tt> in this
     * node. Returns the specified default if there is no value associated
     * with the <tt>key</tt>, or the backing store is inaccessible.
     *
     * @param key key whose associated value is to be returned.
     * @param def the value to be returned in the event that this
     *        node has no value associated with <tt>key</tt>
     *        or the backing store is inaccessible.
     * @return the value associated with <tt>key</tt>, or <tt>def</tt>
     *         if no value is associated with <tt>key</tt>.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.  (A
     *         <tt>null</tt> default <i>is</i> permitted.)
     */
    public abstract String get(String key, String def);

    /**
     * Removes the value associated with the specified <tt>key</tt> in this
     * node, if any.
     *
     * @param key key whose mapping is to be removed from this node.
     * @see #get(String,String)
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     */
    public abstract void remove(String key);

    /**
     * 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.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     * @see #remove(String)
     */
    public abstract void clear() throws BackingStoreException;

    /**
     * Associates a <tt>String</tt> object representing the specified <tt>int</tt> value with the
     * specified <tt>key</tt> in this node.  The associated string is the
     * one that would be returned if the <tt>int</tt> value were passed to
     * <tt>Integer.toString(int)</tt>.  This method is intended for use in
     * conjunction with {@link #getInt}method.
     *
     * <p>Implementor's note: it is <i>not</i> necessary that the property
     * value be represented by a <tt>String</tt> 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
     * <tt>Preferences</tt> API, which allows the value to be read as an <tt>int</tt>
     * (with <tt>getInt</tt> or a <tt>String</tt> (with <tt>get</tt>) type.
     *
     * @param key key with which the string form of value is to be associated.
     * @param value <tt>value</tt> whose string form is to be associated with <tt>key</tt>.
     * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     * @see #getInt(String,int)
     */
    public abstract void putInt(String key, int value);

    /**
     * Returns the <tt>int</tt> value represented by the <tt>String</tt> object associated with the
     * specified <tt>key</tt> in this node. The <tt>String</tt> object is converted to
     * an <tt>int</tt> as by <tt>Integer.parseInt(String)</tt>.  Returns the
     * specified default if there is no value associated with the <tt>key</tt>,
     * the backing store is inaccessible, or if
     * <tt>Integer.parseInt(String)</tt> would throw a
     * <tt>NumberFormatException</tt> if the associated
     * <tt>value</tt> were passed.  This
     * method is intended for use in conjunction with the {@link #putInt}method.
     *
     * @param key key whose associated value is to be returned as an <tt>int</tt>.
     * @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 an <tt>int</tt>
     *        or the backing store is inaccessible.
     * @return the <tt>int</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
     *         an <tt>int</tt> type.
     * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
     * @throws IllegalStateException if this node (or an ancestor) has been
     *         removed with the {@link #removeNode()}method.
     * @see #putInt(String,int)
     * @see #get(String,String)
     */
    public abstract int getInt(String key, int def);

    /**
     * Associates a <tt>String</tt> object representing the specified <tt>long</tt> value with the
     * specified <tt>key</tt> in this node.  The associated <tt>String</tt> object is the
     * one that would be returned if the <tt>long</tt> value were passed to
     * <tt>Long.toString(long)</tt>.  This method is intended for use in
     * conjunction with the {@link #getLong}method.
     *
     * <p>Implementor's note: it is <i>not</i> necessary that the
     * <tt>value</tt> be represented by a <tt>String</tt> type in the backing store.  If