felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From erodrig...@apache.org
Subject svn commit: r389891 [4/9] - in /incubator/felix/trunk/org.osgi.compendium: ./ src/ src/main/ src/main/java/ src/main/java/org/ src/main/java/org/osgi/ src/main/java/org/osgi/service/ src/main/java/org/osgi/service/cm/ src/main/java/org/osgi/service/com...
Date Wed, 29 Mar 2006 21:05:18 GMT
Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/Preferences.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/Preferences.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/Preferences.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/Preferences.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,702 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.prefs/src/org/osgi/service/prefs/Preferences.java,v 1.9 2006/03/14 01:21:15 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2001, 2005). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.prefs;
+
+/**
+ * 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 <code>String</code> 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 <code>"/"</code>. Children of the
+ * root node have absolute path names of <code>"/" + </code> <i>&lt;node name&gt;
+ * </i>. All other nodes have absolute path names of <i>&lt;parent's absolute
+ * path name&gt; </i> <code> + "/" + </code> <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 <code>Preference</code> 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 <code>String</code>,<code>long</code>,<code>int</code>,<code>boolean</code>,
+ * <code>byte[]</code>,<code>float</code>, or <code>double</code> but they can
+ * always be accessed as if they were <code>String</code> 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 <code>flush</code> 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.9 $
+ */
+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 <code>key</code> or <code>value</code> is
+	 *         <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 */
+	public void put(String key, String value);
+
+	/**
+	 * Returns the value associated with the specified <code>key</code> in this
+	 * node. Returns the specified default if there is no value associated with
+	 * the <code>key</code>, 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 <code>key</code> or the backing store is
+	 *        inaccessible.
+	 * @return the value associated with <code>key</code>, or <code>def</code> if
+	 *         no value is associated with <code>key</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>. (A
+	 *         <code>null</code> default <i>is </i> permitted.)
+	 */
+	public String get(String key, String def);
+
+	/**
+	 * Removes the value associated with the specified <code>key</code> 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 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 void clear() throws BackingStoreException;
+
+	/**
+	 * Associates a <code>String</code> object representing the specified
+	 * <code>int</code> value with the specified <code>key</code> in this node. The
+	 * associated string is the one that would be returned if the <code>int</code>
+	 * value were passed to <code>Integer.toString(int)</code>. 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 <code>String</code> 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
+	 * <code>Preferences</code> API, which allows the value to be read as an
+	 * <code>int</code> (with <code>getInt</code> or a <code>String</code> (with
+	 * <code>get</code>) type.
+	 * 
+	 * @param key key with which the string form of value is to be associated.
+	 * @param value <code>value</code> whose string form is to be associated with
+	 *        <code>key</code>.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @see #getInt(String,int)
+	 */
+	public void putInt(String key, int value);
+
+	/**
+	 * Returns the <code>int</code> value represented by the <code>String</code>
+	 * object associated with the specified <code>key</code> in this node. The
+	 * <code>String</code> object is converted to an <code>int</code> as by
+	 * <code>Integer.parseInt(String)</code>. Returns the specified default if
+	 * there is no value associated with the <code>key</code>, the backing store
+	 * is inaccessible, or if <code>Integer.parseInt(String)</code> would throw a
+	 * <code>NumberFormatException</code> if the associated <code>value</code> 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
+	 *        <code>int</code>.
+	 * @param def the value to be returned in the event that this node has no
+	 *        value associated with <code>key</code> or the associated value
+	 *        cannot be interpreted as an <code>int</code> or the backing store is
+	 *        inaccessible.
+	 * @return the <code>int</code> value represented by the <code>String</code>
+	 *         object associated with <code>key</code> in this node, or
+	 *         <code>def</code> if the associated value does not exist or cannot
+	 *         be interpreted as an <code>int</code> type.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @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 int getInt(String key, int def);
+
+	/**
+	 * Associates a <code>String</code> object representing the specified
+	 * <code>long</code> value with the specified <code>key</code> in this node. The
+	 * associated <code>String</code> object is the one that would be returned if
+	 * the <code>long</code> value were passed to <code>Long.toString(long)</code>.
+	 * 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 <code>value</code>
+	 * be represented by a <code>String</code> type in the backing store. If the
+	 * backing store supports <code>long</code> values, it is not unreasonable to
+	 * use them. This implementation detail is not visible through the <code>
+	 * Preferences</code> API, which allows the value to be read as a
+	 * <code>long</code> (with <code>getLong</code> or a <code>String</code> (with
+	 * <code>get</code>) type.
+	 * 
+	 * @param key <code>key</code> with which the string form of <code>value</code>
+	 *        is to be associated.
+	 * @param value <code>value</code> whose string form is to be associated with
+	 *        <code>key</code>.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @see #getLong(String,long)
+	 */
+	public void putLong(String key, long value);
+
+	/**
+	 * Returns the <code>long</code> value represented by the <code>String</code>
+	 * object associated with the specified <code>key</code> in this node. The
+	 * <code>String</code> object is converted to a <code>long</code> as by
+	 * <code>Long.parseLong(String)</code>. Returns the specified default if
+	 * there is no value associated with the <code>key</code>, the backing store
+	 * is inaccessible, or if <code>Long.parseLong(String)</code> would throw a
+	 * <code>NumberFormatException</code> if the associated <code>value</code> were
+	 * passed. This method is intended for use in conjunction with the
+	 * {@link #putLong}method.
+	 * 
+	 * @param key <code>key</code> whose associated value is to be returned as a
+	 *        <code>long</code> value.
+	 * @param def the value to be returned in the event that this node has no
+	 *        value associated with <code>key</code> or the associated value
+	 *        cannot be interpreted as a <code>long</code> type or the backing
+	 *        store is inaccessible.
+	 * @return the <code>long</code> value represented by the <code>String</code>
+	 *         object associated with <code>key</code> in this node, or
+	 *         <code>def</code> if the associated value does not exist or cannot
+	 *         be interpreted as a <code>long</code> type.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @see #putLong(String,long)
+	 * @see #get(String,String)
+	 */
+	public long getLong(String key, long def);
+
+	/**
+	 * Associates a <code>String</code> object representing the specified
+	 * <code>boolean</code> value with the specified key in this node. The
+	 * associated string is "true" if the value is <code>true</code>, and "false"
+	 * if it is <code>false</code>. This method is intended for use in
+	 * conjunction with the {@link #getBoolean}method.
+	 * 
+	 * <p>
+	 * Implementor's note: it is <i>not </i> necessary that the value be
+	 * represented by a string in the backing store. If the backing store
+	 * supports <code>boolean</code> values, it is not unreasonable to use them.
+	 * This implementation detail is not visible through the <code>Preferences
+	 * </code> API, which allows the value to be read as a <code>boolean</code>
+	 * (with <code>getBoolean</code>) or a <code>String</code> (with <code>get</code>)
+	 * type.
+	 * 
+	 * @param key <code>key</code> with which the string form of value is to be
+	 *        associated.
+	 * @param value value whose string form is to be associated with
+	 *        <code>key</code>.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @see #getBoolean(String,boolean)
+	 * @see #get(String,String)
+	 */
+	public void putBoolean(String key, boolean value);
+
+	/**
+	 * Returns the <code>boolean</code> value represented by the <code>String</code>
+	 * object associated with the specified <code>key</code> in this node. Valid
+	 * strings are "true", which represents <code>true</code>, and "false", which
+	 * represents <code>false</code>. Case is ignored, so, for example, "TRUE"
+	 * and "False" are also valid. This method is intended for use in
+	 * conjunction with the {@link #putBoolean}method.
+	 * 
+	 * <p>
+	 * Returns the specified default if there is no value associated with the
+	 * <code>key</code>, the backing store is inaccessible, or if the associated
+	 * value is something other than "true" or "false", ignoring case.
+	 * 
+	 * @param key <code>key</code> whose associated value is to be returned as a
+	 *        <code>boolean</code>.
+	 * @param def the value to be returned in the event that this node has no
+	 *        value associated with <code>key</code> or the associated value
+	 *        cannot be interpreted as a <code>boolean</code> or the backing store
+	 *        is inaccessible.
+	 * @return the <code>boolean</code> value represented by the <code>String</code>
+	 *         object associated with <code>key</code> in this node, or
+	 *         <code>null</code> if the associated value does not exist or cannot
+	 *         be interpreted as a <code>boolean</code>.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @see #get(String,String)
+	 * @see #putBoolean(String,boolean)
+	 */
+	public boolean getBoolean(String key, boolean def);
+
+	/**
+	 * Associates a <code>String</code> object representing the specified
+	 * <code>float</code> value with the specified <code>key</code> in this node.
+	 * The associated <code>String</code> object is the one that would be returned
+	 * if the <code>float</code> value were passed to
+	 * <code>Float.toString(float)</code>. This method is intended for use in
+	 * conjunction with the {@link #getFloat}method.
+	 * 
+	 * <p>
+	 * Implementor's note: it is <i>not </i> necessary that the value be
+	 * represented by a string in the backing store. If the backing store
+	 * supports <code>float</code> values, it is not unreasonable to use them.
+	 * This implementation detail is not visible through the <code>Preferences
+	 * </code> API, which allows the value to be read as a <code>float</code> (with
+	 * <code>getFloat</code>) or a <code>String</code> (with <code>get</code>) type.
+	 * 
+	 * @param key <code>key</code> with which the string form of value is to be
+	 *        associated.
+	 * @param value value whose string form is to be associated with
+	 *        <code>key</code>.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @see #getFloat(String,float)
+	 */
+	public void putFloat(String key, float value);
+
+	/**
+	 * Returns the float <code>value</code> represented by the <code>String</code>
+	 * object associated with the specified <code>key</code> in this node. The
+	 * <code>String</code> object is converted to a <code>float</code> value as by
+	 * <code>Float.parseFloat(String)</code>. Returns the specified default if
+	 * there is no value associated with the <code>key</code>, the backing store
+	 * is inaccessible, or if <code>Float.parseFloat(String)</code> would throw a
+	 * <code>NumberFormatException</code> if the associated value were passed.
+	 * This method is intended for use in conjunction with the {@link #putFloat}
+	 * method.
+	 * 
+	 * @param key <code>key</code> whose associated value is to be returned as a
+	 *        <code>float</code> value.
+	 * @param def the value to be returned in the event that this node has no
+	 *        value associated with <code>key</code> or the associated value
+	 *        cannot be interpreted as a <code>float</code> type or the backing
+	 *        store is inaccessible.
+	 * @return the <code>float</code> value represented by the string associated
+	 *         with <code>key</code> in this node, or <code>def</code> if the
+	 *         associated value does not exist or cannot be interpreted as a
+	 *         <code>float</code> type.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @see #putFloat(String,float)
+	 * @see #get(String,String)
+	 */
+	public float getFloat(String key, float def);
+
+	/**
+	 * Associates a <code>String</code> object representing the specified
+	 * <code>double</code> value with the specified <code>key</code> in this node.
+	 * The associated <code>String</code> object is the one that would be returned
+	 * if the <code>double</code> value were passed to
+	 * <code>Double.toString(double)</code>. This method is intended for use in
+	 * conjunction with the {@link #getDouble}method
+	 * 
+	 * <p>
+	 * Implementor's note: it is <i>not </i> necessary that the value be
+	 * represented by a string in the backing store. If the backing store
+	 * supports <code>double</code> values, it is not unreasonable to use them.
+	 * This implementation detail is not visible through the <code>Preferences
+	 * </code> API, which allows the value to be read as a <code>double</code> (with
+	 * <code>getDouble</code>) or a <code>String</code> (with <code>get</code>)
+	 * type.
+	 * 
+	 * @param key <code>key</code> with which the string form of value is to be
+	 *        associated.
+	 * @param value value whose string form is to be associated with
+	 *        <code>key</code>.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @see #getDouble(String,double)
+	 */
+	public void putDouble(String key, double value);
+
+	/**
+	 * Returns the <code>double</code> value represented by the <code>String</code>
+	 * object associated with the specified <code>key</code> in this node. The
+	 * <code>String</code> object is converted to a <code>double</code> value as by
+	 * <code>Double.parseDouble(String)</code>. Returns the specified default if
+	 * there is no value associated with the <code>key</code>, the backing store
+	 * is inaccessible, or if <code>Double.parseDouble(String)</code> would throw
+	 * a <code>NumberFormatException</code> if the associated value were passed.
+	 * This method is intended for use in conjunction with the
+	 * {@link #putDouble}method.
+	 * 
+	 * @param key <code>key</code> whose associated value is to be returned as a
+	 *        <code>double</code> value.
+	 * @param def the value to be returned in the event that this node has no
+	 *        value associated with <code>key</code> or the associated value
+	 *        cannot be interpreted as a <code>double</code> type or the backing
+	 *        store is inaccessible.
+	 * @return the <code>double</code> value represented by the <code>String</code>
+	 *         object associated with <code>key</code> in this node, or
+	 *         <code>def</code> if the associated value does not exist or cannot
+	 *         be interpreted as a <code>double</code> type.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the the {@link #removeNode()}method.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>.
+	 * @see #putDouble(String,double)
+	 * @see #get(String,String)
+	 */
+	public double getDouble(String key, double def);
+
+	/**
+	 * Associates a <code>String</code> object representing the specified
+	 * <code>byte[]</code> with the specified <code>key</code> in this node. The
+	 * associated <code>String</code> object the <i>Base64 </i> encoding of the
+	 * <code>byte[]</code>, as defined in <a
+	 * href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 </a>, Section 6.8,
+	 * with one minor change: the string will consist solely of characters from
+	 * the <i>Base64 Alphabet </i>; it will not contain any newline characters.
+	 * This method is intended for use in conjunction with the
+	 * {@link #getByteArray}method.
+	 * 
+	 * <p>
+	 * Implementor's note: it is <i>not </i> necessary that the value be
+	 * represented by a <code>String</code> type in the backing store. If the
+	 * backing store supports <code>byte[]</code> values, it is not unreasonable
+	 * to use them. This implementation detail is not visible through the <code>
+	 * Preferences</code> API, which allows the value to be read as an a
+	 * <code>byte[]</code> object (with <code>getByteArray</code>) or a
+	 * <code>String</code> object (with <code>get</code>).
+	 * 
+	 * @param key <code>key</code> with which the string form of <code>value</code>
+	 *        is to be associated.
+	 * @param value <code>value</code> whose string form is to be associated with
+	 *        <code>key</code>.
+	 * @throws NullPointerException if <code>key</code> or <code>value</code> is
+	 *         <code>null</code>.
+	 * @throws IllegalStateException if this node (or an ancestor) has been
+	 *         removed with the {@link #removeNode()}method.
+	 * @see #getByteArray(String,byte[])
+	 * @see #get(String,String)
+	 */
+	public void putByteArray(String key, byte[] value);
+
+	/**
+	 * Returns the <code>byte[]</code> value represented by the <code>String</code>
+	 * object associated with the specified <code>key</code> in this node. Valid
+	 * <code>String</code> 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
+	 * <code>key</code>, the backing store is inaccessible, or if the associated
+	 * value is not a valid Base64 encoded byte array (as defined above).
+	 * 
+	 * @param key <code>key</code> whose associated value is to be returned as a
+	 *        <code>byte[]</code> object.
+	 * @param def the value to be returned in the event that this node has no
+	 *        value associated with <code>key</code> or the associated value
+	 *        cannot be interpreted as a <code>byte[]</code> type, or the backing
+	 *        store is inaccessible.
+	 * @return the <code>byte[]</code> value represented by the <code>String</code>
+	 *         object associated with <code>key</code> in this node, or
+	 *         <code>def</code> if the associated value does not exist or cannot
+	 *         be interpreted as a <code>byte[]</code>.
+	 * @throws NullPointerException if <code>key</code> is <code>null</code>. (A
+	 *         <code>null</code> value for <code>def</code> <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 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 <code>null</code>!)
+	 * 
+	 * @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 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 <code>null</code>!)
+	 * 
+	 * @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 String[] childrenNames() throws BackingStoreException;
+
+	/**
+	 * Returns the parent of this node, or <code>null</code> 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 Preferences parent();
+
+	/**
+	 * Returns a named <code>Preferences</code> 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 <code>'/'</code>)
+	 * are interpreted relative to the root of this node. Relative pathnames
+	 * (which begin with any character other than <code>'/'</code>) are
+	 * interpreted relative to this node itself. The empty string (<code>""</code>)
+	 * 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 <code>flush</code> method is called on the returned
+	 * node (or one of its descendants).
+	 * 
+	 * @param pathName the path name of the <code>Preferences</code> object to
+	 *        return.
+	 * @return the specified <code>Preferences</code> 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 <code>null</code>.
+	 * @see #flush()
+	 */
+	public Preferences node(String pathName);
+
+	/**
+	 * Returns true if the named node exists. Accepts a relative or absolute
+	 * pathname. Absolute pathnames (which begin with <code>'/'</code>) are
+	 * interpreted relative to the root of this node. Relative pathnames (which
+	 * begin with any character other than <code>'/'</code>) are interpreted
+	 * relative to this node itself. The pathname <code>""</code> 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 <code>""</code>; the invocation will return
+	 * <code>false</code>. Thus, the idiom <code>p.nodeExists("")</code> may be
+	 * used to test whether <code>p</code> 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
+	 *         <code>pathname</code> is not the empty string (<code>""</code>).
+	 * @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 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 <code>name()</code>,<code>absolutePath()</code> or
+	 * <code>nodeExists("")</code> on the corresponding <code>Preferences</code>
+	 * instance will fail with an <code>IllegalStateException</code>. (The
+	 * methods defined on <code>Object</code> can still be invoked on a node after
+	 * it has been removed; they will not throw <code>IllegalStateException</code>.)
+	 * 
+	 * <p>
+	 * The removal is not guaranteed to be persistent until the <code>flush</code>
+	 * method is called on the parent of this node.
+	 * 
+	 * @throws IllegalStateException if this node (or an ancestor) has already
+	 *         been removed with the {@link #removeNode()}method.
+	 * @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 void removeNode() throws BackingStoreException;
+
+	/**
+	 * Returns this node's name, relative to its parent.
+	 * 
+	 * @return this node's name, relative to its parent.
+	 */
+	public String name();
+
+	/**
+	 * Returns this node's absolute path name. Note that:
+	 * <ul>
+	 * <li>Root node - The path name of the root node is <code>"/"</code>.
+	 * <li>Slash at end - Path names other than that of the root node may not
+	 * end in slash (<code>'/'</code>).
+	 * <li>Unusual names -<code>"."</code> and <code>".."</code> 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 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 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 <code>sync</code> invocation. As a side-effect, forces any changes
+	 * in the contents of this node and its descendants to the persistent store,
+	 * as if the <code>flush</code> 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 void sync() throws BackingStoreException;
+}
\ No newline at end of file

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/Preferences.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/PreferencesService.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/PreferencesService.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/PreferencesService.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/PreferencesService.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,56 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.prefs/src/org/osgi/service/prefs/PreferencesService.java,v 1.9 2006/03/14 01:21:15 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2001, 2005). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.prefs;
+
+/**
+ * The Preferences Service.
+ * 
+ * <p>
+ * Each bundle using this service has its own set of preference trees: one for
+ * system preferences, and one for each user.
+ * 
+ * <p>
+ * A <code>PreferencesService</code> object is specific to the bundle which
+ * obtained it from the service registry. If a bundle wishes to allow another
+ * bundle to access its preferences, it should pass its
+ * <code>PreferencesService</code> object to that bundle.
+ *  
+ */
+public interface PreferencesService {
+	/**
+	 * Returns the root system node for the calling bundle.
+	 * 
+	 * @return The root system node for the calling bundle.
+	 */
+	public Preferences getSystemPreferences();
+
+	/**
+	 * Returns the root node for the specified user and the calling bundle.
+	 * 
+	 * @param name The user for which to return the preference root node. 
+	 * @return The root node for the specified user and the calling bundle.
+	 */
+	public Preferences getUserPreferences(String name);
+
+	/**
+	 * Returns the names of users for which node trees exist.
+	 * 
+	 * @return The names of users for which node trees exist.
+	 */
+	public String[] getUsers();
+}

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/PreferencesService.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/package.html
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/package.html?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/package.html (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/package.html Wed Mar 29 13:05:08 2006
@@ -0,0 +1,11 @@
+<!-- $Header: /cvshome/build/org.osgi.service.prefs/src/org/osgi/service/prefs/package.html,v 1.3 2004/12/03 19:30:27 hargrave Exp $ -->
+<BODY>
+<P>The OSGi Preferences Service Package. Specification Version 1.1.
+<p>Bundles wishing to use this package must list the package
+in the Import-Package header of the bundle's manifest.
+For example:
+<pre>
+Import-Package: org.osgi.service.prefs; version=1.1
+</pre>
+</BODY>
+

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/packageinfo
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/packageinfo?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/packageinfo (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/packageinfo Wed Mar 29 13:05:08 2006
@@ -0,0 +1 @@
+version 1.1

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/prefs/packageinfo
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/ProvisioningService.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/ProvisioningService.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/ProvisioningService.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/ProvisioningService.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,181 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.provisioning/src/org/osgi/service/provisioning/ProvisioningService.java,v 1.9 2006/03/14 01:21:04 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2002, 2005). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.provisioning;
+
+import java.util.Dictionary;
+import java.util.zip.ZipInputStream;
+import java.io.IOException;
+
+/**
+ * Service for managing the initial provisioning information.
+ * <p>
+ * Initial provisioning of an OSGi device is a multi step process that
+ * culminates with the installation and execution of the initial management
+ * agent. At each step of the process, information is collected for the next
+ * step. Multiple bundles may be involved and this service provides a means for
+ * these bundles to exchange information. It also provides a means for the
+ * initial Management Bundle to get its initial configuration information.
+ * <p>
+ * The provisioning information is collected in a <code>Dictionary</code> object,
+ * called the Provisioning Dictionary. Any bundle that can access the service
+ * can get a reference to this object and read and update provisioning
+ * information. The key of the dictionary is a <code>String</code> object and the
+ * value is a <code>String</code> or <code>byte[]</code> object. The single
+ * exception is the PROVISIONING_UPDATE_COUNT value which is an Integer. The
+ * <code>provisioning</code> prefix is reserved for keys defined by OSGi, other
+ * key names may be used for implementation dependent provisioning systems.
+ * <p>
+ * Any changes to the provisioning information will be reflected immediately in
+ * all the dictionary objects obtained from the Provisioning Service.
+ * <p>
+ * Because of the specific application of the Provisioning Service, there should
+ * be only one Provisioning Service registered. This restriction will not be
+ * enforced by the Framework. Gateway operators or manufactures should ensure
+ * that a Provisioning Service bundle is not installed on a device that already
+ * has a bundle providing the Provisioning Service.
+ * <p>
+ * The provisioning information has the potential to contain sensitive
+ * information. Also, the ability to modify provisioning information can have
+ * drastic consequences. Thus, only trusted bundles should be allowed to
+ * register and get the Provisioning Service. The <code>ServicePermission</code>
+ * is used to limit the bundles that can gain access to the Provisioning
+ * Service. There is no check of <code>Permission</code> objects to read or modify
+ * the provisioning information, so care must be taken not to leak the
+ * Provisioning Dictionary received from <code>getInformation</code> method.
+ * 
+ * @version $Revision: 1.9 $
+ */
+public interface ProvisioningService {
+	/**
+	 * The key to the provisioning information that uniquely identifies the
+	 * Service Platform. The value must be of type <code>String</code>.
+	 */
+	public final static String	PROVISIONING_SPID			= "provisioning.spid";
+	/**
+	 * The key to the provisioning information that contains the location of the
+	 * provision data provider. The value must be of type <code>String</code>.
+	 */
+	public final static String	PROVISIONING_REFERENCE		= "provisioning.reference";
+	/**
+	 * The key to the provisioning information that contains the initial
+	 * configuration information of the initial Management Agent. The value will
+	 * be of type <code>byte[]</code>.
+	 */
+	public final static String	PROVISIONING_AGENT_CONFIG	= "provisioning.agent.config";
+	/**
+	 * The key to the provisioning information that contains the update count of
+	 * the info data. Each set of changes to the provisioning information must
+	 * end with this value being incremented. The value must be of type
+	 * <code>Integer</code>. This key/value pair is also reflected in the
+	 * properties of the ProvisioningService in the service registry.
+	 */
+	public final static String	PROVISIONING_UPDATE_COUNT	= "provisioning.update.count";
+	/**
+	 * The key to the provisioning information that contains the location of the
+	 * bundle to start with <code>AllPermission</code>. The bundle must have be
+	 * previously installed for this entry to have any effect.
+	 */
+	public final static String	PROVISIONING_START_BUNDLE	= "provisioning.start.bundle";
+	/**
+	 * The key to the provisioning information that contains the root X509
+	 * certificate used to esatblish trust with operator when using HTTPS.
+	 */
+	public final static String	PROVISIONING_ROOTX509		= "provisioning.rootx509";
+	/**
+	 * The key to the provisioning information that contains the shared secret
+	 * used in conjunction with the RSH protocol.
+	 */
+	public final static String	PROVISIONING_RSH_SECRET		= "provisioning.rsh.secret";
+	/**
+	 * MIME type to be stored in the extra field of a <code>ZipEntry</code> object
+	 * for String data.
+	 */
+	public final static String	MIME_STRING					= "text/plain;charset=utf-8";
+	/**
+	 * MIME type to be stored in the extra field of a <code>ZipEntry</code> object
+	 * for <code>byte[]</code> data.
+	 */
+	public final static String	MIME_BYTE_ARRAY				= "application/octet-stream";
+	/**
+	 * MIME type to be stored in the extra field of a <code>ZipEntry</code> object
+	 * for an installable bundle file. Zip entries of this type will be
+	 * installed in the framework, but not started. The entry will also not be
+	 * put into the information dictionary.
+	 */
+	public final static String	MIME_BUNDLE					= "application/x-osgi-bundle";
+	/**
+	 * MIME type to be stored in the extra field of a ZipEntry for a String that
+	 * represents a URL for a bundle. Zip entries of this type will be used to
+	 * install (but not start) a bundle from the URL. The entry will not be put
+	 * into the information dictionary.
+	 */
+	public final static String	MIME_BUNDLE_URL				= "text/x-osgi-bundle-url";
+
+	/**
+	 * Returns a reference to the Provisioning Dictionary. Any change operations
+	 * (put and remove) to the dictionary will cause an
+	 * <code>UnsupportedOperationException</code> to be thrown. Changes must be
+	 * done using the <code>setInformation</code> and <code>addInformation</code>
+	 * methods of this service.
+	 * @return A reference to the Provisioning Dictionary.
+	 */
+	public Dictionary getInformation();
+
+	/**
+	 * Replaces the Provisioning Information dictionary with the key/value pairs
+	 * contained in <code>info</code>. Any key/value pairs not in <code>info</code>
+	 * will be removed from the Provisioning Information dictionary. This method
+	 * causes the <code>PROVISIONING_UPDATE_COUNT</code> to be incremented.
+	 * 
+	 * @param info the new set of Provisioning Information key/value pairs. Any
+	 *        keys are values that are of an invalid type will be silently
+	 *        ignored.
+	 */
+	public void setInformation(Dictionary info);
+
+	/**
+	 * Adds the key/value pairs contained in <code>info</code> to the Provisioning
+	 * Information dictionary. This method causes the
+	 * <code>PROVISIONING_UPDATE_COUNT</code> to be incremented.
+	 * 
+	 * @param info the set of Provisioning Information key/value pairs to add to
+	 *        the Provisioning Information dictionary. Any keys are values that
+	 *        are of an invalid type will be silently ignored.
+	 */
+	public void addInformation(Dictionary info);
+
+	/**
+	 * Processes the <code>ZipInputStream</code> and extracts information to add
+	 * to the Provisioning Information dictionary, as well as, install/update
+	 * and start bundles. This method causes the
+	 * <code>PROVISIONING_UPDATE_COUNT</code> to be incremented.
+	 * 
+	 * @param zis the <code>ZipInputStream</code> that will be used to add
+	 *        key/value pairs to the Provisioning Information dictionary and
+	 *        install and start bundles. If a <code>ZipEntry</code> does not have
+	 *        an <code>Extra</code> field that corresponds to one of the four
+	 *        defined MIME types (<code>MIME_STRING</code>,
+	 *        <code>MIME_BYTE_ARRAY</code>,<code>MIME_BUNDLE</code>, and
+	 *        <code>MIME_BUNDLE_URL</code>) in will be silently ignored.
+	 * @throws IOException if an error occurs while processing the
+	 *            ZipInputStream. No additions will be made to the Provisioning
+	 *            Information dictionary and no bundles must be started or
+	 *            installed.
+	 */
+	public void addInformation(ZipInputStream zis) throws IOException;
+}

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/ProvisioningService.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/package.html
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/package.html?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/package.html (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/package.html Wed Mar 29 13:05:08 2006
@@ -0,0 +1,10 @@
+<!-- $Header: /cvshome/build/org.osgi.service.provisioning/src/org/osgi/service/provisioning/package.html,v 1.3 2005/08/10 02:16:40 hargrave Exp $ -->
+<BODY>
+<P>The OSGi Provisioning Service Package. Specification Version 1.1.
+<p>Bundles wishing to use this package must list the package
+in the Import-Package header of the bundle's manifest.
+For example:
+<pre>
+Import-Package: org.osgi.service.provisioning; version=1.1
+</pre>
+</BODY>

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/packageinfo
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/packageinfo?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/packageinfo (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/packageinfo Wed Mar 29 13:05:08 2006
@@ -0,0 +1 @@
+version 1.1

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/provisioning/packageinfo
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPAction.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPAction.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPAction.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPAction.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,121 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPAction.java,v 1.9 2006/03/14 01:21:11 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2002, 2005). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.upnp;
+
+import java.util.Dictionary;
+
+/**
+ * A UPnP action.
+ * 
+ * Each UPnP service contains zero or more actions. Each action may have zero or
+ * more UPnP state variables as arguments.
+ *  
+ */
+public interface UPnPAction {
+	/**
+	 * Returns the action name.
+	 * 
+	 * The action name corresponds to the <code>name</code> field in the
+	 * <code>actionList</code> of the service description.
+	 * <ul>
+	 * <li>For standard actions defined by a UPnP Forum working committee,
+	 * action names must not begin with <code>X_ </code> nor <code> A_</code>.</li>
+	 * <li>For non-standard actions specified by a UPnP vendor and added to a
+	 * standard service, action names must begin with <code>X_</code>.</li>
+	 * </ul>
+	 * 
+	 * @return Name of action, must not contain a hyphen character or a hash
+	 *         character
+	 */
+	String getName();
+
+	/**
+	 * Returns the name of the designated return argument.
+	 * <p>
+	 * One of the output arguments can be flagged as a designated return
+	 * argument.
+	 * 
+	 * @return The name of the designated return argument or <code>null</code> if
+	 *         none is marked.
+	 */
+	String getReturnArgumentName();
+
+	/**
+	 * Lists all input arguments for this action.
+	 * <p>
+	 * Each action may have zero or more input arguments.
+	 * 
+	 * @return Array of input argument names or <code>null</code> if no input
+	 *         arguments.
+	 * 
+	 * @see UPnPStateVariable
+	 */
+	String[] getInputArgumentNames();
+
+	/**
+	 * List all output arguments for this action.
+	 * 
+	 * @return Array of output argument names or <code>null</code> if there are no
+	 *         output arguments.
+	 * 
+	 * @see UPnPStateVariable
+	 */
+	String[] getOutputArgumentNames();
+
+	/**
+	 * Finds the state variable associated with an argument name.
+	 * 
+	 * Helps to resolve the association of state variables with argument names
+	 * in UPnP actions.
+	 * 
+	 * @param argumentName The name of the UPnP action argument.
+	 * @return State variable associated with the named argument or
+	 *         <code>null</code> if there is no such argument.
+	 * 
+	 * @see UPnPStateVariable
+	 */
+	UPnPStateVariable getStateVariable(String argumentName);
+
+	/**
+	 * Invokes the action.
+	 * 
+	 * The input and output arguments are both passed as <code>Dictionary</code>
+	 * objects. Each entry in the <code>Dictionary</code> object has a
+	 * <code>String</code> object as key representing the argument name and the
+	 * value is the argument itself. The class of an argument value must be
+	 * assignable from the class of the associated UPnP state variable.
+	 * 
+	 * The input argument <code>Dictionary</code> object must contain exactly
+	 * those arguments listed by <code>getInputArguments</code> method. The output
+	 * argument <code>Dictionary</code> object will contain exactly those
+	 * arguments listed by <code>getOutputArguments</code> method.
+	 *
+	 * @param args A <code>Dictionary</code> of arguments. Must contain the correct set and
+	 * type of arguments for this action. May be <code>null</code> if no
+	 * input arguments exist.
+	 *
+	 * @return A <code>Dictionary</code> with the output arguments.
+	 *         <code>null</code> if the action has no output arguments.
+	 *
+	 * @throws UPnPException  A UPnP error has occured.
+	 * @throws Exception The execution fails for some reason.
+	 *
+	 * @see UPnPStateVariable
+	 */
+	Dictionary invoke(Dictionary args) throws Exception;
+}

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPAction.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPDevice.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPDevice.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPDevice.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPDevice.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,281 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPDevice.java,v 1.8 2006/03/14 01:21:11 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2002, 2005). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.upnp;
+
+import java.util.Dictionary;
+
+/**
+ * Represents a UPnP device.
+ * 
+ * For each UPnP root and embedded device, an object is registered with the
+ * framework under the <code>UPnPDevice</code> interface.
+ * <p>
+ * The relationship between a root device and its embedded devices can be
+ * deduced using the <code>UPnPDevice.CHILDREN_UDN</code> and
+ * <code>UPnPDevice.PARENT_UDN</code> service registration properties.
+ * <p>
+ * The values of the UPnP property names are defined by the UPnP Forum.
+ * <p>
+ * All values of the UPnP properties are obtained from the device using the
+ * device's default locale.
+ * <p>
+ * If an application wants to query for a set of localized property values, it
+ * has to use the method <code>UPnPDevice.getDescriptions(String locale)</code>.
+ *  
+ */
+public interface UPnPDevice {
+	/*
+	 * Constants for the UPnP device match scale.
+	 */
+	/**
+	 * Constant for the UPnP device match scale, indicating a generic match for
+	 * the device. Value is 1.
+	 */
+	int		MATCH_GENERIC								= 1;
+	/**
+	 * Constant for the UPnP device match scale, indicating a match with the
+	 * device type. Value is 3.
+	 */
+	int		MATCH_TYPE									= 3;
+	/**
+	 * Constant for the UPnP device match scale, indicating a match with the
+	 * device model. Value is 7.
+	 */
+	int		MATCH_MANUFACTURER_MODEL					= 7;
+	/**
+	 * Constant for the UPnP device match scale, indicating a match with the
+	 * device revision. Value is 15.
+	 */
+	int		MATCH_MANUFACTURER_MODEL_REVISION			= 15;
+	/**
+	 * Constant for the UPnP device match scale, indicating a match with the
+	 * device revision and the serial number. Value is 31.
+	 */
+	int		MATCH_MANUFACTURER_MODEL_REVISION_SERIAL	= 31;
+	/**
+	 * Constant for the value of the service property <code>DEVICE_CATEGORY</code>
+	 * used for all UPnP devices. Value is "UPnP".
+	 * 
+	 * @see "<code>org.osgi.service.device.Constants.DEVICE_CATEGORY</code>"
+	 */
+	String	DEVICE_CATEGORY								= "UPnP";
+	/**
+	 * The <code>UPnP.export</code> service property is a hint that marks a device
+	 * to be picked up and exported by the UPnP Service. Imported devices do not
+	 * have this property set. The registered property requires no value.
+	 * <p>
+	 * The UPNP_EXPORT string is "UPnP.export".
+	 */
+	String	UPNP_EXPORT									= "UPnP.export";
+	/**
+	 * Property key for the Unique Device Name (UDN) property. It is the unique
+	 * identifier of an instance of a <code>UPnPDevice</code>. The value of the
+	 * property is a <code>String</code> object of the Device UDN. Value of the
+	 * key is "UPnP.device.UDN". This property must be set.
+	 */
+	String	UDN											= "UPnP.device.UDN";
+	/**
+	 * Property key for the Unique Device ID property. This property is an alias
+	 * to <code>UPnPDevice.UDN</code>. It is merely provided for reasons of
+	 * symmetry with the <code>UPnPService.ID</code> property. The value of the
+	 * property is a <code>String</code> object of the Device UDN. The value of
+	 * the key is "UPnP.device.UDN".
+	 */
+	String	ID											= UDN;
+	/**
+	 * Property key for the UPnP Device Type property. Some standard property
+	 * values are defined by the Universal Plug and Play Forum. The type string
+	 * also includes a version number as defined in the UPnP specification. This
+	 * property must be set.
+	 * <p>
+	 * For standard devices defined by a UPnP Forum working committee, this must
+	 * consist of the following components in the given order separated by
+	 * colons:
+	 * <ul>
+	 * <li><code>urn</code></li>
+	 * <li>schemas-upnp-org</li>
+	 * <li><code>device</code></li>
+	 * <li>a device type suffix</li>
+	 * <li>an integer device version</li>
+	 * </ul>
+	 * For non-standard devices specified by UPnP vendors following components
+	 * must be specified in the given order separated by colons:
+	 * <ul>
+	 * <li><code>urn</code></li>
+	 * <li>an ICANN domain name owned by the vendor</li>
+	 * <li><code>device</code></li>
+	 * <li>a device type suffix</li>
+	 * <li>an integer device version</li>
+	 * </ul>
+	 * <p>
+	 * To allow for backward compatibility the UPnP driver must automatically
+	 * generate additional Device Type property entries for smaller versions
+	 * than the current one. If for example a device announces its type as
+	 * version 3, then properties for versions 2 and 1 must be automatically
+	 * generated.
+	 * <p>
+	 * In the case of exporting a UPnPDevice, the highest available version must
+	 * be announced on the network.
+	 * <p>
+	 * Syntax Example: <code>urn:schemas-upnp-org:device:deviceType:v</code>
+	 * <p>
+	 * The value is "UPnP.device.type".
+	 */
+	String	TYPE										= "UPnP.device.type";
+	/**
+	 * Mandatory property key for the device manufacturer's property. The
+	 * property value holds a String representation of the device manufacturer's
+	 * name. Value is "UPnP.device.manufacturer".
+	 */
+	String	MANUFACTURER								= "UPnP.device.manufacturer";
+	/**
+	 * Mandatory property key for the device model name. The property value
+	 * holds a <code>String</code> object giving more information about the device
+	 * model. Value is "UPnP.device.modelName".
+	 */
+	String	MODEL_NAME									= "UPnP.device.modelName";
+	/**
+	 * Mandatory property key for a short user friendly version of the device
+	 * name. The property value holds a <code>String</code> object with the user
+	 * friendly name of the device. Value is "UPnP.device.friendlyName".
+	 */
+	String	FRIENDLY_NAME								= "UPnP.device.friendlyName";
+	/**
+	 * Optional property key for a URL to the device manufacturers Web site. The
+	 * value of the property is a <code>String</code> object representing the URL.
+	 * Value is "UPnP.device.manufacturerURL".
+	 */
+	String	MANUFACTURER_URL							= "UPnP.device.manufacturerURL";
+	/**
+	 * Optional (but recommended) property key for a <code>String</code> object
+	 * with a long description of the device for the end user. The value is
+	 * "UPnP.device.modelDescription".
+	 */
+	String	MODEL_DESCRIPTION							= "UPnP.device.modelDescription";
+	/**
+	 * Optional (but recommended) property key for a <code>String</code> class
+	 * typed property holding the model number of the device. Value is
+	 * "UPnP.device.modelNumber".
+	 */
+	String	MODEL_NUMBER								= "UPnP.device.modelNumber";
+	/**
+	 * Optional property key for a <code>String</code> typed property holding a
+	 * string representing the URL to the Web site for this model. Value is
+	 * "UPnP.device.modelURL".
+	 */
+	String	MODEL_URL									= "UPnP.device.modelURL";
+	/**
+	 * Optional (but recommended) property key for a <code>String</code> typed
+	 * property holding the serial number of the device. Value is
+	 * "UPnP.device.serialNumber".
+	 */
+	String	SERIAL_NUMBER								= "UPnP.device.serialNumber";
+	/**
+	 * Optional property key for a <code>String</code> typed property holding the
+	 * Universal Product Code (UPC) of the device. Value is "UPnP.device.UPC".
+	 */
+	String	UPC											= "UPnP.device.UPC";
+	/**
+	 * Optional (but recommended) property key for a <code>String</code> typed
+	 * property holding a string representing the URL to a device representation
+	 * Web page. Value is "UPnP.presentationURL".
+	 */
+	String	PRESENTATION_URL							= "UPnP.presentationURL";
+	/**
+	 * The property key that must be set for all embedded devices. It contains
+	 * the UDN of the parent device. The property is not set for root devices.
+	 * The value is "UPnP.device.parentUDN".
+	 */
+	String	PARENT_UDN									= "UPnP.device.parentUDN";
+	/**
+	 * The property key that must be set for all devices containing other
+	 * embedded devices.
+	 * <p>
+	 * The value is an array of UDNs for each of the device's children (
+	 * <code>String[]</code>). The array contains UDNs for the immediate
+	 * descendants only.
+	 * </p>
+	 * <p>
+	 * If an embedded device in turn contains embedded devices, the latter are
+	 * not included in the array.
+	 * </p>
+	 * The UPnP Specification does not encourage more than two levels of
+	 * nesting.
+	 * <p>
+	 * The property is not set if the device does not contain embedded devices.
+	 * <p>
+	 * The property is of type <code>String[]</code>. Value is
+	 * "UPnP.device.childrenUDN"
+	 */
+	String	CHILDREN_UDN								= "UPnP.device.childrenUDN";
+
+	/**
+	 * Locates a specific service by its service id.
+	 * 
+	 * @param serviceId The service id
+	 * @return The requested service or null if not found.
+	 */
+	UPnPService getService(String serviceId);
+
+	/**
+	 * Lists all services provided by this device.
+	 * 
+	 * @return Array of services or <code>null</code> if no services are
+	 *         available.
+	 */
+	UPnPService[] getServices();
+
+	/**
+	 * Lists all icons for this device in a given locale.
+	 * 
+	 * The UPnP specification allows a device to present different icons based
+	 * on the client's locale.
+	 * 
+	 * @param locale A language tag as defined by RFC 1766 and maintained by ISO
+	 *        639. Examples include "<code>de</code>", "<code>en</code>" or "
+	 *        <code>en-US</code>". The default locale of the device is specified
+	 *        by passing a <code>null</code> argument.
+	 * 
+	 * @return Array of icons or null if no icons are available.
+	 */
+	UPnPIcon[] getIcons(String locale);
+
+	/**
+	 * Get a set of localized UPnP properties.
+	 * 
+	 * The UPnP specification allows a device to present different device
+	 * properties based on the client's locale. The properties used to register
+	 * the UPnPDevice service in the OSGi registry are based on the device's
+	 * default locale. To obtain a localized set of the properties, an
+	 * application can use this method.
+	 * <p>
+	 * Not all properties might be available in all locales. This method does
+	 * <b>not </b> substitute missing properties with their default locale
+	 * versions.
+	 * <p>
+	 * 
+	 * @param locale A language tag as defined by RFC 1766 and maintained by ISO
+	 *        639. Examples include "<code>de</code>", "<code>en</code>" or "
+	 *        <code>en-US</code>". The default locale of the device is specified
+	 *        by passing a <code>null</code> argument.
+	 * @return Dictionary mapping property name Strings to property value
+	 *         Strings
+	 *  
+	 */
+	Dictionary getDescriptions(String locale);
+}

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPDevice.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPEventListener.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPEventListener.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPEventListener.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPEventListener.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,85 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPEventListener.java,v 1.7 2006/03/14 01:21:11 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2002, 2005). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.upnp;
+
+import java.util.Dictionary;
+
+/**
+ * UPnP Events are mapped and delivered to applications according to the OSGi
+ * whiteboard model. An application that wishes to be notified of events
+ * generated by a particular UPnP Device registers a service extending this
+ * interface.
+ * <p>
+ * The notification call from the UPnP Service to any <code>UPnPEventListener</code>
+ * object must be done asynchronous with respect to the originator (in a
+ * separate thread).
+ * <p>
+ * Upon registration of the UPnP Event Listener service with the Framework, the
+ * service is notified for each variable which it listens for with an initial
+ * event containing the current value of the variable. Subsequent notifications
+ * only happen on changes of the value of the variable.
+ * <p>
+ * A UPnP Event Listener service filter the events it receives. This event set
+ * is limited using a standard framework filter expression which is specified
+ * when the listener service is registered.
+ * <p>
+ * The filter is specified in a property named "upnp.filter" and has as a value
+ * an object of type <code>org.osgi.framework.Filter</code>.
+ * <p>
+ * When the Filter is evaluated, the folowing keywords are recognized as defined
+ * as literal constants in the <code>UPnPDevice</code> class.
+ * <p>
+ * The valid subset of properties for the registration of UPnP Event Listener
+ * services are:
+ * <ul>
+ * <li><code>UPnPDevice.TYPE</code>-- Which type of device to listen for events.
+ * </li>
+ * <li><code>UPnPDevice.ID</code>-- The ID of a specific device to listen for
+ * events.</li>
+ * <li><code>UPnPService.TYPE</code>-- The type of a specific service to listen
+ * for events.</li>
+ * <li><code>UPnPService.ID</code>-- The ID of a specific service to listen for
+ * events.</li>
+ * </ul>
+ */
+public interface UPnPEventListener {
+	/**
+	 * Key for a service property having a value that is an object of type
+	 * <code>org.osgi.framework.Filter</code> and that is used to limit received
+	 * events.
+	 */
+	static final String	UPNP_FILTER	= "upnp.filter";
+
+	/**
+	 * Callback method that is invoked for received events.
+	 * 
+	 * The events are collected in a <code>Dictionary</code> object. Each entry
+	 * has a <code>String</code> key representing the event name (= state variable
+	 * name) and the new value of the state variable. The class of the value
+	 * object must match the class specified by the UPnP State Variable
+	 * associated with the event. This method must be called asynchronously
+	 * 
+	 * @param deviceId ID of the device sending the events
+	 * @param serviceId ID of the service sending the events
+	 * @param events <code>Dictionary</code> object containing the new values for
+	 *        the state variables that have changed.
+	 * 
+	 *  
+	 */
+	void notifyUPnPEvent(String deviceId, String serviceId, Dictionary events);
+}

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPEventListener.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPException.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPException.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPException.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPException.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,84 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPException.java,v 1.11 2006/03/14 01:21:11 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.upnp;
+
+import java.lang.Exception;
+
+/**
+ * There are several defined error situations describing UPnP problems while a
+ * control point invokes actions to UPnPDevices.
+ * 
+ * @since 1.1
+ */
+public class UPnPException extends Exception {
+	static final long		serialVersionUID		= -262013318122195146L;
+
+	/**
+	 * No Action found by that name at this service.
+	 */
+	public final static int	INVALID_ACTION			= 401;
+
+	/**
+	 * Not enough arguments, too many arguments with a specific name, or one of
+	 * more of the arguments are of the wrong type.
+	 */
+	public final static int	INVALID_ARGS			= 402;
+
+	/**
+	 * The different end-points are no longer in synchronization.
+	 */
+	public final static int	INVALID_SEQUENCE_NUMBER	= 403;
+
+	/**
+	 * Refers to a non existing variable.
+	 */
+	public final static int	INVALID_VARIABLE		= 404;
+
+	/**
+	 * The invoked action failed during execution.
+	 */
+	public final static int	DEVICE_INTERNAL_ERROR	= 501;
+
+	/**
+	 * Key for an error information that is an int type variable and that is
+	 * used to identify occured errors.
+	 */
+	private int				errorCode;
+
+	/**
+	 * This constructor creates a UPnPException on the specified error code and
+	 * error description.
+	 * 
+	 * @param errorCode errorCode which defined UPnP Device Architecture V1.0.
+	 * @param errordesc errorDescription which explain the type of propblem.
+	 */
+	public UPnPException(int errorCode, String errordesc) {
+		super(errordesc);
+		this.errorCode = errorCode;
+	}
+
+	/**
+	 * Returns the UPnPError Code occured by UPnPDevices during invocation.
+	 * 
+	 * @return The UPnPErrorCode defined by a UPnP Forum working committee or
+	 *         specified by a UPnP vendor.
+	 */
+	public int getUPnPError_Code() {
+		return errorCode;
+	}
+}

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPException.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPIcon.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPIcon.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPIcon.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPIcon.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,99 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPIcon.java,v 1.10 2006/03/14 01:21:11 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2002, 2005). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.upnp;
+
+import java.io.InputStream;
+import java.io.IOException;
+
+/**
+ * A UPnP icon representation.
+ * 
+ * Each UPnP device can contain zero or more icons.
+ */
+public interface UPnPIcon {
+	/**
+	 * Returns the MIME type of the icon.
+	 * 
+	 * This method returns the format in which the icon graphics, read from the
+	 * <code>InputStream</code> object obtained by the <code>getInputStream()</code>
+	 * method, is encoded.
+	 * <p>
+	 * The format of the returned string is in accordance to RFC2046. A list of
+	 * valid MIME types is maintained by the <a
+	 * href="http://www.iana.org/assignments/media-types/">IANA</a>.
+	 * <p>
+	 * Typical values returned include: "image/jpeg" or "image/gif"
+	 * 
+	 * @return The MIME type of the encoded icon.
+	 */
+	String getMimeType();
+
+	/**
+	 * Returns the width of the icon in pixels.
+	 * 
+	 * If the actual width of the icon is unknown, -1 is returned.
+	 * 
+	 * @return The width in pixels, or -1 if unknown.
+	 */
+	int getWidth();
+
+	/**
+	 * Returns the height of the icon in pixels.
+	 * 
+	 * If the actual height of the icon is unknown, -1 is returned.
+	 * 
+	 * @return The height in pixels, or -1 if unknown.
+	 */
+	int getHeight();
+
+	/**
+	 * Returns the size of the icon in bytes.
+	 * 
+	 * This method returns the number of bytes of the icon available to read
+	 * from the <code>InputStream</code> object obtained by the
+	 * <code>getInputStream()</code> method. If the actual size can not be
+	 * determined, -1 is returned.
+	 * 
+	 * @return The icon size in bytes, or -1 if the size is unknown.
+	 */
+	int getSize();
+
+	/**
+	 * Returns the color depth of the icon in bits.
+	 * 
+	 * @return The color depth in bits. If the actual color depth of the icon is
+	 *         unknown, -1 is returned.
+	 */
+	int getDepth();
+
+	/**
+	 * Returns an <code>InputStream</code> object for the icon data.
+	 * 
+	 * The <code>InputStream</code> object provides a way for a client to read the
+	 * actual icon graphics data. The number of bytes available from this
+	 * <code>InputStream</code> object can be determined via the
+	 * <code>getSize()</code> method. The format of the data encoded can be
+	 * determined by the MIME type availble via the <code>getMimeType()</code>
+	 * method.
+	 * 
+	 * @return An InputStream to read the icon graphics data from.
+	 * @throws IOException If the <code>InputStream</code> cannot be returned.
+	 * @see UPnPIcon#getMimeType()
+	 */
+	InputStream getInputStream() throws IOException;
+}

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPIcon.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPLocalStateVariable.java
URL: http://svn.apache.org/viewcvs/incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPLocalStateVariable.java?rev=389891&view=auto
==============================================================================
--- incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPLocalStateVariable.java (added)
+++ incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPLocalStateVariable.java Wed Mar 29 13:05:08 2006
@@ -0,0 +1,44 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPLocalStateVariable.java,v 1.11 2006/03/14 01:21:11 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * To keep the current values getting from subscribed UPnPDevices. 
+ * 
+ * The actual values of the UPnPStateVaraible are passed as Java object type. 
+ * 
+ * @since 1.1
+ **/
+package org.osgi.service.upnp;
+
+/**
+ * A local UPnP state variable which allows the value of the state variable to
+ * be queried.
+ * 
+ * @since 1.1
+ */
+public interface UPnPLocalStateVariable extends UPnPStateVariable {
+	/**
+	 * This method will keep the current values of UPnPStateVariables of a
+	 * UPnPDevice whenever UPnPStateVariable's value is changed , this method
+	 * must be called.
+	 * 
+	 * @return <code>Object</code> current value of UPnPStateVariable. if the
+	 *         current value is initialized with the default value defined UPnP
+	 *         service description.
+	 */
+	public Object getCurrentValue();
+}

Propchange: incubator/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/upnp/UPnPLocalStateVariable.java
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message