felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cziege...@apache.org
Subject svn commit: r1614569 [2/5] - in /felix/trunk/framework: ./ src/main/appended-resources/META-INF/ src/main/java/org/apache/felix/framework/ src/main/java/org/osgi/dto/ src/main/java/org/osgi/framework/ src/main/java/org/osgi/framework/dto/ src/main/java...
Date Wed, 30 Jul 2014 07:22:35 GMT
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleContext.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleContext.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleContext.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleContext.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2014). 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.
@@ -20,6 +20,7 @@ import java.io.File;
 import java.io.InputStream;
 import java.util.Collection;
 import java.util.Dictionary;
+import org.osgi.annotation.versioning.ProviderType;
 
 /**
  * A bundle's execution context within the Framework. The context is used to
@@ -29,15 +30,15 @@ import java.util.Dictionary;
  * <p>
  * {@code BundleContext} methods allow a bundle to:
  * <ul>
- * <li>Subscribe to events published by the Framework.
- * <li>Register service objects with the Framework service registry.
- * <li>Retrieve {@code ServiceReferences} from the Framework service registry.
- * <li>Get and release service objects for a referenced service.
- * <li>Install new bundles in the Framework.
- * <li>Get the list of bundles installed in the Framework.
- * <li>Get the {@link Bundle} object for a bundle.
+ * <li>Subscribe to events published by the Framework.</li>
+ * <li>Register service objects with the Framework service registry.</li>
+ * <li>Retrieve {@code ServiceReferences} from the Framework service registry.</li>
+ * <li>Get and release service objects for a referenced service.</li>
+ * <li>Install new bundles in the Framework.</li>
+ * <li>Get the list of bundles installed in the Framework.</li>
+ * <li>Get the {@link Bundle} object for a bundle.</li>
  * <li>Create {@code File} objects for files in a persistent storage area
- * provided for the bundle by the Framework.
+ * provided for the bundle by the Framework.</li>
  * </ul>
  * 
  * <p>
@@ -57,8 +58,17 @@ import java.util.Dictionary;
  * <p>
  * The {@code BundleContext} object is only valid during the execution of its
  * context bundle; that is, during the period from when the context bundle is in
- * the {@code STARTING}, {@code STOPPING}, and {@code ACTIVE} bundle states. If
- * the {@code BundleContext} object is used subsequently, an
+ * the {@code STARTING}, {@code STOPPING}, and {@code ACTIVE} bundle states.
+ * However, the {@code BundleContext} object becomes invalid after
+ * {@link BundleActivator#stop(BundleContext)} returns (if the bundle has a
+ * Bundle Activator). The {@code BundleContext} object becomes invalid before
+ * disposing of any remaining registered services and releasing any remaining
+ * services in use. Since those activities can result in other bundles being
+ * called (for example, {@link ServiceListener}s for
+ * {@link ServiceEvent#UNREGISTERING} events and {@link ServiceFactory}s for
+ * unget operations), those other bundles can observe the stopping bundle in the
+ * {@code STOPPING} state but with an invalid {@code BundleContext} object. If
+ * the {@code BundleContext} object is used after it has become invalid, an
  * {@code IllegalStateException} must be thrown. The {@code BundleContext}
  * object must never be reused after its context bundle is stopped.
  * 
@@ -75,10 +85,9 @@ import java.util.Dictionary;
  * Environment supports permissions.
  * 
  * @ThreadSafe
- * @noimplement
- * @version $Id: 4f166fd274f3965e48a7dbc239213d00e062b6d0 $
+ * @author $Id: fbf0b18296a0b85d628ee8c47d0f0f213a914e48 $
  */
-
+@ProviderType
 public interface BundleContext extends BundleReference {
 
 	/**
@@ -127,29 +136,24 @@ public interface BundleContext extends B
 	 * The following steps are required to install a bundle:
 	 * <ol>
 	 * <li>If a bundle containing the same location identifier is already
-	 * installed, the {@code Bundle} object for that bundle is returned.
-	 * 
+	 * installed, the {@code Bundle} object for that bundle is returned.</li>
 	 * <li>The bundle's content is read from the input stream. If this fails, a
-	 * {@link BundleException} is thrown.
-	 * 
+	 * {@link BundleException} is thrown.</li>
 	 * <li>The bundle's associated resources are allocated. The associated
 	 * resources minimally consist of a unique identifier and a persistent
 	 * storage area if the platform has file system support. If this step fails,
-	 * a {@code BundleException} is thrown.
-	 * 
-	 * <li>The bundle's state is set to {@code INSTALLED}.
-	 * 
-	 * <li>A bundle event of type {@link BundleEvent#INSTALLED} is fired.
-	 * 
+	 * a {@code BundleException} is thrown.</li>
+	 * <li>The bundle's state is set to {@code INSTALLED}.</li>
+	 * <li>A bundle event of type {@link BundleEvent#INSTALLED} is fired.</li>
 	 * <li>The {@code Bundle} object for the newly or previously installed
-	 * bundle is returned.
+	 * bundle is returned.</li>
 	 * </ol>
 	 * 
 	 * <b>Postconditions, no exceptions thrown </b>
 	 * <ul>
 	 * <li>{@code getState()} in &#x007B; {@code INSTALLED}, {@code RESOLVED}
-	 * &#x007D;.
-	 * <li>Bundle has a unique ID.
+	 * &#x007D;.</li>
+	 * <li>Bundle has a unique ID.</li>
 	 * </ul>
 	 * <b>Postconditions, when an exception is thrown </b>
 	 * <ul>
@@ -386,29 +390,36 @@ public interface BundleContext extends B
 	 * <p>
 	 * The following steps are required to register a service:
 	 * <ol>
-	 * <li>If {@code service} is not a {@code ServiceFactory}, an
+	 * <li>If {@code service} does not implement {@code ServiceFactory}, an
 	 * {@code IllegalArgumentException} is thrown if {@code service} is not an
-	 * {@code instanceof} all the specified class names.
+	 * {@code instanceof} all the specified class names.</li>
 	 * <li>The Framework adds the following service properties to the service
 	 * properties from the specified {@code Dictionary} (which may be
-	 * {@code null}): <br/>
-	 * A property named {@link Constants#SERVICE_ID} identifying the
-	 * registration number of the service <br/>
-	 * A property named {@link Constants#OBJECTCLASS} containing all the
-	 * specified classes. <br/>
+	 * {@code null}):
+	 * <ul>
+	 * <li>A property named {@link Constants#SERVICE_ID} identifying the
+	 * registration number of the service</li>
+	 * <li>A property named {@link Constants#OBJECTCLASS} containing all the
+	 * specified classes.</li>
+	 * <li>A property named {@link Constants#SERVICE_SCOPE} identifying the
+	 * scope of the service.</li>
+	 * <li>A property named {@link Constants#SERVICE_BUNDLEID} identifying the
+	 * the context bundle.</li>
+	 * </ul>
 	 * Properties with these names in the specified {@code Dictionary} will be
-	 * ignored.
+	 * ignored.</li>
 	 * <li>The service is added to the Framework service registry and may now be
-	 * used by other bundles.
-	 * <li>A service event of type {@link ServiceEvent#REGISTERED} is fired.
+	 * used by other bundles.</li>
+	 * <li>A service event of type {@link ServiceEvent#REGISTERED} is fired.</li>
 	 * <li>A {@code ServiceRegistration} object for this registration is
-	 * returned.
+	 * returned.</li>
 	 * </ol>
 	 * 
 	 * @param clazzes The class names under which the service can be located.
 	 *        The class names in this array will be stored in the service's
 	 *        properties under the key {@link Constants#OBJECTCLASS}.
-	 * @param service The service object or a {@code ServiceFactory} object.
+	 * @param service The service object or an object implementing
+	 *        {@code ServiceFactory}.
 	 * @param properties The properties for this service. The keys in the
 	 *        properties object must all be {@code String} objects. See
 	 *        {@link Constants} for a list of standard service property keys.
@@ -422,10 +433,10 @@ public interface BundleContext extends B
 	 *         unregister the service.
 	 * @throws IllegalArgumentException If one of the following is true:
 	 *         <ul>
-	 *         <li>{@code service} is {@code null}. <li>{@code service} is not a
-	 *         {@code ServiceFactory} object and is not an instance of all the
-	 *         named classes in {@code clazzes}. <li> {@code properties}
-	 *         contains case variants of the same key name.
+	 *         <li>{@code service} is {@code null}.</li><li>{@code service} does
+	 *         not implement {@code ServiceFactory} and is not an instance of
+	 *         all the specified classes.</li><li> {@code properties} contains
+	 *         case variants of the same key name.</li>
 	 *         </ul>
 	 * @throws SecurityException If the caller does not have the
 	 *         {@code ServicePermission} to register the service for all the
@@ -433,6 +444,7 @@ public interface BundleContext extends B
 	 *         permissions.
 	 * @throws IllegalStateException If this BundleContext is no longer valid.
 	 * @see ServiceRegistration
+	 * @see PrototypeServiceFactory
 	 * @see ServiceFactory
 	 */
 	ServiceRegistration<?> registerService(String[] clazzes, Object service, Dictionary<String, ?> properties);
@@ -450,7 +462,8 @@ public interface BundleContext extends B
 	 * than just a single string.
 	 * 
 	 * @param clazz The class name under which the service can be located.
-	 * @param service The service object or a {@code ServiceFactory} object.
+	 * @param service The service object or an object implementing
+	 *        {@code ServiceFactory}.
 	 * @param properties The properties for this service.
 	 * @return A {@code ServiceRegistration} object for use by the bundle
 	 *         registering the service to update the service's properties or to
@@ -471,7 +484,8 @@ public interface BundleContext extends B
 	 * 
 	 * @param <S> Type of Service.
 	 * @param clazz The class under whose name the service can be located.
-	 * @param service The service object or a {@code ServiceFactory} object.
+	 * @param service The service object or an object implementing
+	 *        {@code ServiceFactory}.
 	 * @param properties The properties for this service.
 	 * @return A {@code ServiceRegistration} object for use by the bundle
 	 *         registering the service to update the service's properties or to
@@ -483,6 +497,29 @@ public interface BundleContext extends B
 	<S> ServiceRegistration<S> registerService(Class<S> clazz, S service, Dictionary<String, ?> properties);
 
 	/**
+	 * Registers the specified service factory object with the specified
+	 * properties under the name of the specified class with the Framework.
+	 * 
+	 * <p>
+	 * This method is otherwise identical to
+	 * {@link #registerService(Class, Object, Dictionary)} and is provided to
+	 * return a type safe {@code ServiceRegistration} when registering a
+	 * {@link ServiceFactory}.
+	 * 
+	 * @param <S> Type of Service.
+	 * @param clazz The class under whose name the service can be located.
+	 * @param factory The {@code ServiceFactory} object.
+	 * @param properties The properties for this service.
+	 * @return A {@code ServiceRegistration} object for use by the bundle
+	 *         registering the service to update the service's properties or to
+	 *         unregister the service.
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
+	 * @see #registerService(Class, Object, Dictionary)
+	 * @since 1.8
+	 */
+	<S> ServiceRegistration<S> registerService(Class<S> clazz, ServiceFactory<S> factory, Dictionary<String, ?> properties);
+
+	/**
 	 * Returns an array of {@code ServiceReference} objects. The returned array
 	 * of {@code ServiceReference} objects contains services that were
 	 * registered under the specified class, match the specified filter
@@ -513,16 +550,16 @@ public interface BundleContext extends B
 	 * service must have been registered with the specified class name. The
 	 * complete list of class names with which a service was registered is
 	 * available from the service's {@link Constants#OBJECTCLASS objectClass}
-	 * property.
+	 * property.</li>
 	 * <li>If the specified {@code filter} is not {@code null}, the filter
-	 * expression must match the service.
+	 * expression must match the service.</li>
 	 * <li>If the Java Runtime Environment supports permissions, the caller must
 	 * have {@code ServicePermission} with the {@code GET} action for at least
-	 * one of the class names under which the service was registered.
+	 * one of the class names under which the service was registered.</li>
 	 * <li>For each class name with which the service was registered, calling
 	 * {@link ServiceReference#isAssignableTo(Bundle, String)} with the context
 	 * bundle and the class name on the service's {@code ServiceReference}
-	 * object must return {@code true}
+	 * object must return {@code true}</li>
 	 * </ul>
 	 * 
 	 * @param clazz The class name with which the service was registered or
@@ -565,12 +602,12 @@ public interface BundleContext extends B
 	 * service must have been registered with the specified class name. The
 	 * complete list of class names with which a service was registered is
 	 * available from the service's {@link Constants#OBJECTCLASS objectClass}
-	 * property.
+	 * property.</li>
 	 * <li>If the specified {@code filter} is not {@code null}, the filter
-	 * expression must match the service.
+	 * expression must match the service.</li>
 	 * <li>If the Java Runtime Environment supports permissions, the caller must
 	 * have {@code ServicePermission} with the {@code GET} action for at least
-	 * one of the class names under which the service was registered.
+	 * one of the class names under which the service was registered.</li>
 	 * </ul>
 	 * 
 	 * @param clazz The class name with which the service was registered or
@@ -606,7 +643,7 @@ public interface BundleContext extends B
 	 * highest ranking (as specified in its {@link Constants#SERVICE_RANKING}
 	 * property) is returned.
 	 * <p>
-	 * If there is a tie in ranking, the service with the lowest service ID (as
+	 * If there is a tie in ranking, the service with the lowest service id (as
 	 * specified in its {@link Constants#SERVICE_ID} property); that is, the
 	 * service that was registered first is returned.
 	 * 
@@ -636,7 +673,7 @@ public interface BundleContext extends B
 	 * If multiple such services exist, the service with the highest ranking (as
 	 * specified in its {@link Constants#SERVICE_RANKING} property) is returned.
 	 * <p>
-	 * If there is a tie in ranking, the service with the lowest service ID (as
+	 * If there is a tie in ranking, the service with the lowest service id (as
 	 * specified in its {@link Constants#SERVICE_ID} property); that is, the
 	 * service that was registered first is returned.
 	 * 
@@ -681,16 +718,16 @@ public interface BundleContext extends B
 	 * <li>The service must have been registered with the name of the specified
 	 * class. The complete list of class names with which a service was
 	 * registered is available from the service's {@link Constants#OBJECTCLASS
-	 * objectClass} property.
+	 * objectClass} property.</li>
 	 * <li>If the specified {@code filter} is not {@code null}, the filter
-	 * expression must match the service.
+	 * expression must match the service.</li>
 	 * <li>If the Java Runtime Environment supports permissions, the caller must
 	 * have {@code ServicePermission} with the {@code GET} action for at least
-	 * one of the class names under which the service was registered.
+	 * one of the class names under which the service was registered.</li>
 	 * <li>For each class name with which the service was registered, calling
 	 * {@link ServiceReference#isAssignableTo(Bundle, String)} with the context
 	 * bundle and the class name on the service's {@code ServiceReference}
-	 * object must return {@code true}
+	 * object must return {@code true}</li>
 	 * </ul>
 	 * 
 	 * @param <S> Type of Service
@@ -707,45 +744,47 @@ public interface BundleContext extends B
 	<S> Collection<ServiceReference<S>> getServiceReferences(Class<S> clazz, String filter) throws InvalidSyntaxException;
 
 	/**
-	 * Returns the service object referenced by the specified
+	 * Returns the service object for the service referenced by the specified
 	 * {@code ServiceReference} object.
+	 * 
 	 * <p>
-	 * A bundle's use of a service is tracked by the bundle's use count of that
-	 * service. Each time a service's service object is returned by
-	 * {@link #getService(ServiceReference)} the context bundle's use count for
-	 * that service is incremented by one. Each time the service is released by
-	 * {@link #ungetService(ServiceReference)} the context bundle's use count
-	 * for that service is decremented by one.
+	 * A bundle's use of a service object obtained from this method is tracked
+	 * by the bundle's use count of that service. Each time the service object
+	 * is returned by {@link #getService(ServiceReference)} the context bundle's
+	 * use count for the service is incremented by one. Each time the service
+	 * object is released by {@link #ungetService(ServiceReference)} the context
+	 * bundle's use count for the service is decremented by one.
+	 * 
 	 * <p>
-	 * When a bundle's use count for a service drops to zero, the bundle should
-	 * no longer use that service.
+	 * When a bundle's use count for the service drops to zero, the bundle
+	 * should no longer use the service object.
 	 * 
 	 * <p>
 	 * This method will always return {@code null} when the service associated
-	 * with this {@code reference} has been unregistered.
+	 * with the specified {@code reference} has been unregistered.
 	 * 
 	 * <p>
 	 * The following steps are required to get the service object:
 	 * <ol>
-	 * <li>If the service has been unregistered, {@code null} is returned.
+	 * <li>If the service has been unregistered, {@code null} is returned.</li>
 	 * <li>If the context bundle's use count for the service is currently zero
-	 * and the service was registered with an object implementing the
-	 * {@code ServiceFactory} interface, the
+	 * and the service has {@link Constants#SCOPE_BUNDLE bundle} or
+	 * {@link Constants#SCOPE_PROTOTYPE prototype} scope, the
 	 * {@link ServiceFactory#getService(Bundle, ServiceRegistration)} method is
-	 * called to create a service object for the context bundle. If the service
-	 * object returned by the {@code ServiceFactory} object is {@code null}, not
-	 * an {@code instanceof} all the classes named when the service was
-	 * registered or the {@code ServiceFactory} object throws an exception or
-	 * will be recursively called for the context bundle, {@code null} is
-	 * returned and a Framework event of type {@link FrameworkEvent#ERROR}
-	 * containing a {@link ServiceException} describing the error is fired. <br>
-	 * This service object is cached by the Framework. While the context
-	 * bundle's use count for the service is greater than zero, subsequent calls
-	 * to get the services's service object for the context bundle will return
-	 * the cached service object.
-	 * <li>The context bundle's use count for this service is incremented by
-	 * one.
-	 * <li>The service object for the service is returned.
+	 * called to supply the service object for the context bundle. If the
+	 * service object returned by the {@code ServiceFactory} object is
+	 * {@code null}, not an {@code instanceof} all the classes named when the
+	 * service was registered or the {@code ServiceFactory} object throws an
+	 * exception or will be recursively called for the context bundle,
+	 * {@code null} is returned and a Framework event of type
+	 * {@link FrameworkEvent#ERROR} containing a {@link ServiceException}
+	 * describing the error is fired. The supplied service object is cached by
+	 * the Framework. While the context bundle's use count for the service is
+	 * greater than zero, subsequent calls to get the service object for the
+	 * context bundle will return the cached service object.</li>
+	 * <li>The context bundle's use count for the service is incremented by one.
+	 * </li>
+	 * <li>The service object for the service is returned.</li>
 	 * </ol>
 	 * 
 	 * @param <S> Type of Service.
@@ -770,28 +809,28 @@ public interface BundleContext extends B
 	<S> S getService(ServiceReference<S> reference);
 
 	/**
-	 * Releases the service object referenced by the specified
+	 * Releases the service object for the service referenced by the specified
 	 * {@code ServiceReference} object. If the context bundle's use count for
 	 * the service is zero, this method returns {@code false}. Otherwise, the
 	 * context bundle's use count for the service is decremented by one.
 	 * 
 	 * <p>
-	 * The service's service object should no longer be used and all references
-	 * to it should be destroyed when a bundle's use count for the service drops
-	 * to zero.
+	 * The service object must no longer be used and all references to it should
+	 * be destroyed when a bundle's use count for the service drops to zero.
 	 * 
 	 * <p>
-	 * The following steps are required to unget the service object:
+	 * The following steps are required to release the service object:
 	 * <ol>
 	 * <li>If the context bundle's use count for the service is zero or the
-	 * service has been unregistered, {@code false} is returned.
-	 * <li>The context bundle's use count for this service is decremented by
-	 * one.
-	 * <li>If the context bundle's use count for the service is currently zero
-	 * and the service was registered with a {@code ServiceFactory} object, the
+	 * service has been unregistered, {@code false} is returned.</li>
+	 * <li>The context bundle's use count for the service is decremented by one.
+	 * </li>
+	 * <li>If the context bundle's use count for the service is now zero and the
+	 * service has {@link Constants#SCOPE_BUNDLE bundle} or
+	 * {@link Constants#SCOPE_PROTOTYPE prototype} scope, the
 	 * {@link ServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
-	 * method is called to release the service object for the context bundle.
-	 * <li>{@code true} is returned.
+	 * method is called to release the service object for the context bundle.</li>
+	 * <li>{@code true} is returned.</li>
 	 * </ol>
 	 * 
 	 * @param reference A reference to the service to be released.
@@ -808,6 +847,47 @@ public interface BundleContext extends B
 	boolean ungetService(ServiceReference<?> reference);
 
 	/**
+	 * Returns the {@link ServiceObjects} object for the service referenced by
+	 * the specified {@code ServiceReference} object.
+	 * 
+	 * <p>
+	 * The {@link ServiceObjects} object can be used to obtain multiple service
+	 * objects for services with {@link Constants#SCOPE_PROTOTYPE prototype}
+	 * scope.
+	 * 
+	 * <p>
+	 * For services with {@link Constants#SCOPE_SINGLETON singleton} or
+	 * {@link Constants#SCOPE_BUNDLE bundle} scope, the
+	 * {@link ServiceObjects#getService()} method behaves the same as the
+	 * {@link #getService(ServiceReference)} method and the
+	 * {@link ServiceObjects#ungetService(Object)} method behaves the same as
+	 * the {@link #ungetService(ServiceReference)} method. That is, only one,
+	 * use-counted service object is available from the {@link ServiceObjects}
+	 * object.
+	 * 
+	 * <p>
+	 * This method will always return {@code null} when the service associated
+	 * with the specified {@code reference} has been unregistered.
+	 * 
+	 * @param <S> Type of Service.
+	 * @param reference A reference to the service.
+	 * @return A {@link ServiceObjects} object for the service associated with
+	 *         the specified {@code reference} or {@code null} if the service is
+	 *         not registered.
+	 * @throws SecurityException If the caller does not have the
+	 *         {@code ServicePermission} to get the service using at least one
+	 *         of the named classes the service was registered under and the
+	 *         Java Runtime Environment supports permissions.
+	 * @throws IllegalStateException If this BundleContext is no longer valid.
+	 * @throws IllegalArgumentException If the specified
+	 *         {@code ServiceReference} was not created by the same framework
+	 *         instance as this {@code BundleContext}.
+	 * @see PrototypeServiceFactory
+	 * @since 1.8
+	 */
+	<S> ServiceObjects<S> getServiceObjects(ServiceReference<S> reference);
+
+	/**
 	 * Creates a {@code File} object for a file in the persistent storage area
 	 * provided for the bundle by the Framework. This method will return
 	 * {@code null} if the platform does not have file system support.

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleEvent.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleEvent.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleEvent.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -32,7 +32,7 @@ import java.util.EventObject;
  * @Immutable
  * @see BundleListener
  * @see SynchronousBundleListener
- * @version $Id: 9e2102212eb526b5f11fdde4b0fc5c171a0b39c8 $
+ * @author $Id: cd49848213816c4f76541b70be12ac3af7900972 $
  */
 
 public class BundleEvent extends EventObject {
@@ -201,16 +201,16 @@ public class BundleEvent extends EventOb
 	/**
 	 * Returns the type of lifecyle event. The type values are:
 	 * <ul>
-	 * <li>{@link #INSTALLED}
-	 * <li>{@link #RESOLVED}
-	 * <li>{@link #LAZY_ACTIVATION}
-	 * <li>{@link #STARTING}
-	 * <li>{@link #STARTED}
-	 * <li>{@link #STOPPING}
-	 * <li>{@link #STOPPED}
-	 * <li>{@link #UPDATED}
-	 * <li>{@link #UNRESOLVED}
-	 * <li>{@link #UNINSTALLED}
+	 * <li>{@link #INSTALLED}</li>
+	 * <li>{@link #RESOLVED}</li>
+	 * <li>{@link #LAZY_ACTIVATION}</li>
+	 * <li>{@link #STARTING}</li>
+	 * <li>{@link #STARTED}</li>
+	 * <li>{@link #STOPPING}</li>
+	 * <li>{@link #STOPPED}</li>
+	 * <li>{@link #UPDATED}</li>
+	 * <li>{@link #UNRESOLVED}</li>
+	 * <li>{@link #UNINSTALLED}</li>
 	 * </ul>
 	 * 
 	 * @return The type of lifecycle event.

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleException.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleException.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleException.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleException.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -32,7 +32,7 @@ package org.osgi.framework;
  * <p>
  * This exception conforms to the general purpose exception chaining mechanism.
  * 
- * @version $Id: 0c97ed2696b4576d61440020922b1a97545beb1e $
+ * @author $Id: a0d23c4cb73b0d6386bcd6b9eebed29fdd9a4deb $
  */
 
 public class BundleException extends Exception {
@@ -203,6 +203,7 @@ public class BundleException extends Exc
 	 * @return The cause of this exception or {@code null} if no cause was set.
 	 * @since 1.3
 	 */
+	@Override
 	public Throwable getCause() {
 		return super.getCause();
 	}
@@ -218,6 +219,7 @@ public class BundleException extends Exc
 	 *         been set.
 	 * @since 1.3
 	 */
+	@Override
 	public Throwable initCause(Throwable cause) {
 		return super.initCause(cause);
 	}

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleListener.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleListener.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleListener.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2011). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -17,6 +17,7 @@
 package org.osgi.framework;
 
 import java.util.EventListener;
+import org.osgi.annotation.versioning.ConsumerType;
 
 /**
  * A {@code BundleEvent} listener. {@code BundleListener} is a listener
@@ -34,9 +35,9 @@ import java.util.EventListener;
  * 
  * @see BundleEvent
  * @NotThreadSafe
- * @version $Id: d48b4a8a59c839466a3d749dde23980d236f58c6 $
+ * @author $Id: 2c27d37a3a77e1c80f9b022f8dc2f614dff5f5ef $
  */
-
+@ConsumerType
 public interface BundleListener extends EventListener {
 	/**
 	 * Receives notification that a bundle has had a lifecycle change.

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundlePermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundlePermission.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundlePermission.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundlePermission.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2004, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2004, 2013). 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.
@@ -58,7 +58,7 @@ import java.util.Map;
  * 
  * @since 1.3
  * @ThreadSafe
- * @version $Id: ccba905e3373800dfdb080118e97145abf778da2 $
+ * @author $Id: 5d3a115a2622919f564e2a2f46d70090ad9859cb $
  */
 
 public final class BundlePermission extends BasicPermission {
@@ -287,6 +287,7 @@ public final class BundlePermission exte
 	 * @return {@code true} if the specified {@code BundlePermission} action is
 	 *         implied by this object; {@code false} otherwise.
 	 */
+	@Override
 	public boolean implies(Permission p) {
 		if (!(p instanceof BundlePermission)) {
 			return false;
@@ -309,6 +310,7 @@ public final class BundlePermission exte
 	 * @return Canonical string representation of the {@code BundlePermission
 	 *         } actions.
 	 */
+	@Override
 	public String getActions() {
 		String result = actions;
 		if (result == null) {
@@ -351,6 +353,7 @@ public final class BundlePermission exte
 	 * 
 	 * @return A new {@code PermissionCollection} object.
 	 */
+	@Override
 	public PermissionCollection newPermissionCollection() {
 		return new BundlePermissionCollection();
 	}
@@ -368,6 +371,7 @@ public final class BundlePermission exte
 	 *         has the same bundle symbolic name and actions as this
 	 *         {@code BundlePermission} object; {@code false} otherwise.
 	 */
+	@Override
 	public boolean equals(Object obj) {
 		if (obj == this) {
 			return true;
@@ -387,6 +391,7 @@ public final class BundlePermission exte
 	 * 
 	 * @return A hash code value for this object.
 	 */
+	@Override
 	public int hashCode() {
 		int h = 31 * 17 + getName().hashCode();
 		h = 31 * h + getActions().hashCode();
@@ -461,6 +466,7 @@ final class BundlePermissionCollection e
 	 * @throws SecurityException If this {@code BundlePermissionCollection}
 	 *         object has been marked read-only.
 	 */
+	@Override
 	public void add(final Permission permission) {
 		if (!(permission instanceof BundlePermission)) {
 			throw new IllegalArgumentException("invalid permission: " + permission);
@@ -500,6 +506,7 @@ final class BundlePermissionCollection e
 	 * @return {@code true} if {@code permission} is a proper subset of a
 	 *         permission in the set; {@code false} otherwise.
 	 */
+	@Override
 	public boolean implies(final Permission permission) {
 		if (!(permission instanceof BundlePermission)) {
 			return false;
@@ -559,6 +566,7 @@ final class BundlePermissionCollection e
 	 * 
 	 * @return Enumeration of all {@code BundlePermission} objects.
 	 */
+	@Override
 	public synchronized Enumeration<Permission> elements() {
 		List<Permission> all = new ArrayList<Permission>(permissions.values());
 		return Collections.enumeration(all);
@@ -577,6 +585,7 @@ final class BundlePermissionCollection e
 
 	private synchronized void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException {
 		ObjectInputStream.GetField gfields = in.readFields();
+		@SuppressWarnings("unchecked")
 		Hashtable<String, BundlePermission> hashtable = (Hashtable<String, BundlePermission>) gfields.get("permissions", null);
 		permissions = new HashMap<String, BundlePermission>(hashtable);
 		all_allowed = gfields.get("all_allowed", false);

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleReference.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleReference.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleReference.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleReference.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2009, 2010). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2009, 2013). 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.
@@ -16,14 +16,16 @@
 
 package org.osgi.framework;
 
+import org.osgi.annotation.versioning.ProviderType;
+
 /**
  * A reference to a Bundle.
  * 
  * @since 1.5
  * @ThreadSafe
- * @noimplement
- * @version $Id: e61bd3e020264b04022a430fe09a85ee3aabf1a3 $
+ * @author $Id: ad4e0b99177540205a1a8f37f9075989434cc59f $
  */
+@ProviderType
 public interface BundleReference {
 	/**
 	 * Returns the {@code Bundle} object associated with this

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/CapabilityPermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/CapabilityPermission.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/CapabilityPermission.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/CapabilityPermission.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -41,13 +41,13 @@ import java.util.Set;
  * A bundle's authority to provide or require a capability.
  * <ul>
  * <li>The {@code provide} action allows a bundle to provide a capability
- * matching the specified filter.
+ * matching the specified filter.</li>
  * <li>The {@code require} action allows a bundle to require a capability
- * matching the specified filter.
+ * matching the specified filter.</li>
  * </ul>
  * 
  * @ThreadSafe
- * @version $Id: b17bcaec959f67c3eae4c4c80c39a0a8716b22dc $
+ * @author $Id: 1d8e892cf46d7410cd3fdff1f5ca2fb010a33ae6 $
  * @since 1.6
  */
 
@@ -334,6 +334,7 @@ public final class CapabilityPermission 
 	 * @return {@code true} if the specified permission is implied by this
 	 *         object; {@code false} otherwise.
 	 */
+	@Override
 	public boolean implies(Permission p) {
 		if (!(p instanceof CapabilityPermission)) {
 			return false;
@@ -382,6 +383,7 @@ public final class CapabilityPermission 
 	 * 
 	 * @return The canonical string representation of the actions.
 	 */
+	@Override
 	public String getActions() {
 		String result = actions;
 		if (result == null) {
@@ -413,6 +415,7 @@ public final class CapabilityPermission 
 	 * @return A new {@code PermissionCollection} object suitable for storing
 	 *         {@code CapabilityPermission} objects.
 	 */
+	@Override
 	public PermissionCollection newPermissionCollection() {
 		return new CapabilityPermissionCollection();
 	}
@@ -428,6 +431,7 @@ public final class CapabilityPermission 
 	 *         name and actions as this {@code CapabilityPermission} object;
 	 *         {@code false} otherwise.
 	 */
+	@Override
 	public boolean equals(Object obj) {
 		if (obj == this) {
 			return true;
@@ -448,6 +452,7 @@ public final class CapabilityPermission 
 	 * 
 	 * @return Hash code value for this object.
 	 */
+	@Override
 	public int hashCode() {
 		int h = 31 * 17 + getName().hashCode();
 		h = 31 * h + getActions().hashCode();
@@ -486,9 +491,8 @@ public final class CapabilityPermission 
 	}
 
 	/**
-	 * Called by {@code <@link CapabilityPermission#implies(Permission)>}. This
-	 * method is only called on a requested permission which cannot have a
-	 * filter set.
+	 * Called by {@link CapabilityPermission#implies(Permission)}. This method
+	 * is only called on a requested permission which cannot have a filter set.
 	 * 
 	 * @return a map of properties for this permission.
 	 */
@@ -502,8 +506,8 @@ public final class CapabilityPermission 
 		if (bundle == null) {
 			return properties = props;
 		}
-		AccessController.doPrivileged(new PrivilegedAction<Object>() {
-			public Object run() {
+		AccessController.doPrivileged(new PrivilegedAction<Void>() {
+			public Void run() {
 				props.put("id", new Long(bundle.getBundleId()));
 				props.put("location", bundle.getLocation());
 				String name = bundle.getSymbolicName();
@@ -531,6 +535,7 @@ public final class CapabilityPermission 
 			entries = null;
 		}
 
+		@Override
 		public Object get(Object k) {
 			if (!(k instanceof String)) {
 				return null;
@@ -609,6 +614,7 @@ final class CapabilityPermissionCollecti
 	 * @throws SecurityException If this {@code CapabilityPermissionCollection}
 	 *         object has been marked read-only.
 	 */
+	@Override
 	public void add(final Permission permission) {
 		if (!(permission instanceof CapabilityPermission)) {
 			throw new IllegalArgumentException("invalid permission: " + permission);
@@ -663,6 +669,7 @@ final class CapabilityPermissionCollecti
 	 * @return {@code true} if {@code permission} is a proper subset of a
 	 *         permission in the set; {@code false} otherwise.
 	 */
+	@Override
 	public boolean implies(final Permission permission) {
 		if (!(permission instanceof CapabilityPermission)) {
 			return false;
@@ -743,6 +750,7 @@ final class CapabilityPermissionCollecti
 	 * 
 	 * @return Enumeration of all the CapabilityPermission objects.
 	 */
+	@Override
 	public synchronized Enumeration<Permission> elements() {
 		List<Permission> all = new ArrayList<Permission>(permissions.values());
 		Map<String, CapabilityPermission> pc = filterPermissions;
@@ -766,9 +774,11 @@ final class CapabilityPermissionCollecti
 
 	private synchronized void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException {
 		ObjectInputStream.GetField gfields = in.readFields();
+		@SuppressWarnings("unchecked")
 		HashMap<String, CapabilityPermission> p = (HashMap<String, CapabilityPermission>) gfields.get("permissions", null);
 		permissions = p;
 		all_allowed = gfields.get("all_allowed", false);
+		@SuppressWarnings("unchecked")
 		HashMap<String, CapabilityPermission> fp = (HashMap<String, CapabilityPermission>) gfields.get("filterPermissions", null);
 		filterPermissions = fp;
 	}

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/Configurable.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/Configurable.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/Configurable.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/Configurable.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -26,7 +26,7 @@ package org.osgi.framework;
  * {@code instanceof Configurable}.
  * 
  * @deprecated As of 1.2. Please use Configuration Admin service.
- * @version $Id: 1018601ae90d2d16ec34136db4b04dca3ccf8e65 $
+ * @author $Id: dce95833dd076e870099385a306989959a84aafd $
  */
 public interface Configurable {
 	/**

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/Constants.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/Constants.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/Constants.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/Constants.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2014). 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.
@@ -16,6 +16,7 @@
 
 package org.osgi.framework;
 
+import org.osgi.annotation.versioning.ProviderType;
 import org.osgi.framework.hooks.bundle.CollisionHook;
 import org.osgi.framework.launch.Framework;
 
@@ -28,10 +29,9 @@ import org.osgi.framework.launch.Framewo
  * otherwise indicated.
  * 
  * @since 1.1
- * @noimplement
- * @version $Id: 6d07a4c3e29a5cd93b3daf0f9fcdab5472b357f6 $
+ * @author $Id: 6873c6f7d537ddbe39a6a2eba107ca3c2de49ce5 $
  */
-
+@ProviderType
 public interface Constants {
 	/**
 	 * Location identifier of the OSGi <i>system bundle </i>, which is defined
@@ -48,6 +48,14 @@ public interface Constants {
 	String	SYSTEM_BUNDLE_SYMBOLICNAME				= "system.bundle";
 
 	/**
+	 * Identifier of the OSGi <i>system bundle </i>, which is defined to be
+	 * {@code 0}.
+	 * 
+	 * @since 1.8
+	 */
+	long	SYSTEM_BUNDLE_ID						= 0L;
+
+	/**
 	 * Manifest header identifying the bundle's category.
 	 * <p>
 	 * The header value may be retrieved from the {@code Dictionary} object
@@ -196,7 +204,7 @@ public interface Constants {
 	String	BUNDLE_CONTACTADDRESS					= "Bundle-ContactAddress";
 
 	/**
-	 * Manifest header attribute identifying the bundle's activator class.
+	 * Manifest header identifying the bundle's activator class.
 	 * 
 	 * <p>
 	 * If present, this header specifies the name of the bundle resource class
@@ -211,6 +219,19 @@ public interface Constants {
 	String	BUNDLE_ACTIVATOR						= "Bundle-Activator";
 
 	/**
+	 * Manifest header identifying the extension bundle's activator class.
+	 * 
+	 * <p>
+	 * If present, this header specifies the name of the extension bundle
+	 * resource class that implements the {@code BundleActivator} interface and
+	 * whose {@code start} and {@code stop} methods are called by the Framework
+	 * when the Framework is initialized and shutdown, respectively.
+	 * 
+	 * @since 1.8
+	 */
+	String	EXTENSION_BUNDLE_ACTIVATOR				= "ExtensionBundle-Activator";
+
+	/**
 	 * Manifest header identifying the location from which a new bundle version
 	 * is obtained during a bundle update operation.
 	 * 
@@ -387,7 +408,8 @@ public interface Constants {
 	 * like:
 	 * 
 	 * <pre>
-	 *     Bundle-SymbolicName: com.acme.module.test; fragment-attachment:=&quot;resolve-time&quot;
+	 *     Bundle-SymbolicName: com.acme.module.test;
+	 *       fragment-attachment:=&quot;resolve-time&quot;
 	 * </pre>
 	 * 
 	 * @see #FRAGMENT_ATTACHMENT_DIRECTIVE
@@ -543,7 +565,8 @@ public interface Constants {
 	 * like:
 	 * 
 	 * <pre>
-	 *     Import-Package: org.osgi.framework; bundle-symbolic-name=&quot;com.acme.module.test&quot;
+	 *     Import-Package: org.osgi.framework;
+	 *       bundle-symbolic-name=&quot;com.acme.module.test&quot;
 	 * </pre>
 	 * 
 	 * @see #IMPORT_PACKAGE
@@ -786,6 +809,9 @@ public interface Constants {
 	 *     Fragment-Host: system.bundle; extension:=&quot;framework&quot;
 	 * </pre>
 	 * 
+	 * <p>
+	 * The default value is {@link #EXTENSION_FRAMEWORK framework}.
+	 * 
 	 * @see #FRAGMENT_HOST
 	 * @see #EXTENSION_FRAMEWORK
 	 * @see #EXTENSION_BOOTCLASSPATH
@@ -1257,9 +1283,10 @@ public interface Constants {
 	 * 
 	 * <p>
 	 * The value of this property is assigned by the Framework when a service is
-	 * registered. The Framework assigns a unique value that is larger than all
-	 * previously assigned values since the Framework was started. These values
-	 * are NOT persistent across restarts of the Framework.
+	 * registered. The Framework assigns a unique, non-negative value that is
+	 * larger than all previously assigned values since the Framework was
+	 * started. These values are NOT persistent across restarts of the
+	 * Framework.
 	 */
 	String	SERVICE_ID								= "service.id";
 
@@ -1331,6 +1358,66 @@ public interface Constants {
 	String	SERVICE_DESCRIPTION						= "service.description";
 
 	/**
+	 * Service property identifying the {@link Bundle#getBundleId() bundle id}
+	 * of the {@link ServiceReference#getBundle() bundle registering the
+	 * service}.
+	 * 
+	 * <p>
+	 * This property is set by the Framework when a service is registered. The
+	 * value of this property must be of type {@code Long}.
+	 * 
+	 * @since 1.8
+	 */
+	String	SERVICE_BUNDLEID						= "service.bundleid";
+
+	/**
+	 * Service property identifying a service's scope.
+	 * 
+	 * <p>
+	 * This property is set by the Framework when a service is registered. If
+	 * the registered object implements {@link PrototypeServiceFactory}, then
+	 * the value of this service property will be {@link #SCOPE_PROTOTYPE}.
+	 * Otherwise, if the registered object implements {@link ServiceFactory},
+	 * then the value of this service property will be {@link #SCOPE_BUNDLE}.
+	 * Otherwise, the value of this service property will be
+	 * {@link #SCOPE_SINGLETON}.
+	 * 
+	 * @since 1.8
+	 * @see #SCOPE_SINGLETON
+	 * @see #SCOPE_BUNDLE
+	 * @see #SCOPE_PROTOTYPE
+	 */
+	String	SERVICE_SCOPE							= "service.scope";
+
+	/**
+	 * Service scope is singleton. All bundles using the service receive the
+	 * same service object.
+	 * 
+	 * @since 1.8
+	 * @see #SERVICE_SCOPE
+	 */
+	String	SCOPE_SINGLETON							= "singleton";
+
+	/**
+	 * Service scope is bundle. Each bundle using the service receives a
+	 * customized service object.
+	 * 
+	 * @since 1.8
+	 * @see #SERVICE_SCOPE
+	 */
+	String	SCOPE_BUNDLE							= "bundle";
+
+	/**
+	 * Service scope is prototype. Each bundle using the service receives either
+	 * a customized service object or can request multiple customized service
+	 * objects via {@link ServiceObjects}.
+	 * 
+	 * @since 1.8
+	 * @see #SERVICE_SCOPE
+	 */
+	String	SCOPE_PROTOTYPE							= "prototype";
+
+	/**
 	 * Framework environment property identifying the Framework's universally
 	 * unique identifier (UUID). A UUID represents a 128-bit value. A new UUID
 	 * is generated by the {@link Framework#init()} method each time a framework
@@ -1700,4 +1787,26 @@ public interface Constants {
 	 * @see BundleException#DUPLICATE_BUNDLE_ERROR
 	 */
 	String	FRAMEWORK_BSNVERSION_MANAGED			= "managed";
+
+	/**
+	 * Manifest header identifying the bundle's icon URLs.
+	 * 
+	 * <p>
+	 * The header value may be retrieved from the {@code Dictionary} object
+	 * returned by the {@code Bundle.getHeaders} method.
+	 * 
+	 * @since 1.8
+	 */
+	String	BUNDLE_ICON								= "Bundle-Icon";
+
+	/**
+	 * Manifest header identifying the bundle's license information.
+	 * 
+	 * <p>
+	 * The header value may be retrieved from the {@code Dictionary} object
+	 * returned by the {@code Bundle.getHeaders} method.
+	 * 
+	 * @since 1.8
+	 */
+	String	BUNDLE_LICENSE							= "Bundle-License";
 }

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/Filter.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/Filter.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/Filter.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/Filter.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -18,6 +18,7 @@ package org.osgi.framework;
 
 import java.util.Dictionary;
 import java.util.Map;
+import org.osgi.annotation.versioning.ProviderType;
 
 /**
  * An <a href="http://www.ietf.org/rfc/rfc1960.txt">RFC 1960</a>-based Filter.
@@ -41,9 +42,9 @@ import java.util.Map;
  * @since 1.1
  * @see "Core Specification, Filters, for a description of the filter string syntax."
  * @ThreadSafe
- * @noimplement
- * @version $Id: 807a04ac07c3230b8f4d4e0f9588a35fbdc41e18 $
+ * @author $Id: 58cd4db16892b20e44be1288ccac929a5a26c53a $
  */
+@ProviderType
 public interface Filter {
 	/**
 	 * Filter using a service's properties.

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkEvent.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkEvent.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkEvent.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2004, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2004, 2013). 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.
@@ -33,7 +33,7 @@ import org.osgi.framework.wiring.Framewo
  * 
  * @Immutable
  * @see FrameworkListener
- * @version $Id: f679c7581879a2e6006ecdd317a5dd5f735764e3 $
+ * @author $Id: 7b74a68311acf2116ccf21e589ece0ce2cd383ba $
  */
 
 public class FrameworkEvent extends EventObject {
@@ -223,16 +223,16 @@ public class FrameworkEvent extends Even
 	 * <p>
 	 * The type values are:
 	 * <ul>
-	 * <li>{@link #STARTED}
-	 * <li>{@link #ERROR}
-	 * <li>{@link #WARNING}
-	 * <li>{@link #INFO}
-	 * <li>{@link #PACKAGES_REFRESHED}
-	 * <li>{@link #STARTLEVEL_CHANGED}
-	 * <li>{@link #STOPPED}
-	 * <li>{@link #STOPPED_BOOTCLASSPATH_MODIFIED}
-	 * <li>{@link #STOPPED_UPDATE}
-	 * <li>{@link #WAIT_TIMEDOUT}
+	 * <li>{@link #STARTED}</li>
+	 * <li>{@link #ERROR}</li>
+	 * <li>{@link #WARNING}</li>
+	 * <li>{@link #INFO}</li>
+	 * <li>{@link #PACKAGES_REFRESHED}</li>
+	 * <li>{@link #STARTLEVEL_CHANGED}</li>
+	 * <li>{@link #STOPPED}</li>
+	 * <li>{@link #STOPPED_BOOTCLASSPATH_MODIFIED}</li>
+	 * <li>{@link #STOPPED_UPDATE}</li>
+	 * <li>{@link #WAIT_TIMEDOUT}</li>
 	 * </ul>
 	 * 
 	 * @return The type of state change.

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkListener.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkListener.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkListener.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2011). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -17,6 +17,7 @@
 package org.osgi.framework;
 
 import java.util.EventListener;
+import org.osgi.annotation.versioning.ConsumerType;
 
 /**
  * A {@code FrameworkEvent} listener. {@code FrameworkListener} is a listener
@@ -34,9 +35,9 @@ import java.util.EventListener;
  * 
  * @see FrameworkEvent
  * @NotThreadSafe
- * @version $Id: ad7f563bd13b60e2b8a378f147057ca7f0accae2 $
+ * @author $Id: 97c76c64c6e6595ad445dcc2d8083d52540f73b8 $
  */
-
+@ConsumerType
 public interface FrameworkListener extends EventListener {
 
 	/**

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkUtil.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkUtil.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkUtil.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkUtil.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2005, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2005, 2013). 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.
@@ -43,7 +43,7 @@ import javax.security.auth.x500.X500Prin
  * 
  * @since 1.3
  * @ThreadSafe
- * @version $Id: 1f46ea2bbbe2a1242fdaf0877709fb9c02eefae1 $
+ * @author $Id: e93d15cef98c0e7f425f3b076d317c46ebb9a52a $
  */
 public class FrameworkUtil {
 	/**
@@ -539,6 +539,7 @@ public class FrameworkUtil {
 		 * 
 		 * @return This {@code Filter}'s filter string.
 		 */
+		@Override
 		public String toString() {
 			String result = filterString;
 			if (result == null) {
@@ -661,6 +662,7 @@ public class FrameworkUtil {
 		 *         {@code this.toString().equals(obj.toString()}; {@code false}
 		 *         otherwise.
 		 */
+		@Override
 		public boolean equals(Object obj) {
 			if (obj == this) {
 				return true;
@@ -682,6 +684,7 @@ public class FrameworkUtil {
 		 * 
 		 * @return The hashCode of this {@code Filter}.
 		 */
+		@Override
 		public int hashCode() {
 			return this.toString().hashCode();
 		}
@@ -768,6 +771,7 @@ public class FrameworkUtil {
 				return compare_Boolean(operation, ((Boolean) value1).booleanValue(), value2);
 			}
 			if (value1 instanceof Comparable<?>) {
+				@SuppressWarnings("unchecked")
 				Comparable<Object> comparable = (Comparable<Object>) value1;
 				return compare_Comparable(operation, comparable, value2);
 			}
@@ -1615,6 +1619,7 @@ public class FrameworkUtil {
 			this.keys = keyList.toArray(new String[keyList.size()]);
 		}
 
+		@Override
 		public Object get(Object o) {
 			String k = (String) o;
 			for (String key : keys) {
@@ -1643,6 +1648,7 @@ public class FrameworkUtil {
 			this.reference = reference;
 		}
 
+		@Override
 		public Object get(Object key) {
 			if (reference == null) {
 				return null;
@@ -1655,14 +1661,14 @@ public class FrameworkUtil {
 		}
 	}
 
-	static private final class SetAccessibleAction implements PrivilegedAction<Object> {
+	static private final class SetAccessibleAction implements PrivilegedAction<Void> {
 		private final AccessibleObject	accessible;
 
 		SetAccessibleAction(AccessibleObject accessible) {
 			this.accessible = accessible;
 		}
 
-		public Object run() {
+		public Void run() {
 			accessible.setAccessible(true);
 			return null;
 		}
@@ -1772,45 +1778,51 @@ public class FrameworkUtil {
 		 * wildcard ("*"), or a List of Strings, each String representing a
 		 * name/value pair in the RDN.
 		 * 
-		 * @param dnChain
+		 * @param pattern
 		 * @return a list of DNs.
 		 * @throws IllegalArgumentException
 		 */
-		private static List<Object> parseDNchainPattern(String dnChain) {
-			if (dnChain == null) {
-				throw new IllegalArgumentException("The DN chain must not be null.");
+		private static List<Object> parseDNchainPattern(String pattern) {
+			if (pattern == null) {
+				throw new IllegalArgumentException("The pattern must not be null.");
 			}
 			List<Object> parsed = new ArrayList<Object>();
-			int startIndex = 0;
-			startIndex = skipSpaces(dnChain, startIndex);
-			while (startIndex < dnChain.length()) {
+			final int length = pattern.length();
+			char c = ';'; // start with semi-colon to detect empty pattern
+			for (int startIndex = skipSpaces(pattern, 0); startIndex < length;) {
+				int cursor = startIndex;
 				int endIndex = startIndex;
-				boolean inQuote = false;
-				out: while (endIndex < dnChain.length()) {
-					char c = dnChain.charAt(endIndex);
+				out: for (boolean inQuote = false; cursor < length; cursor++) {
+					c = pattern.charAt(cursor);
 					switch (c) {
 						case '"' :
 							inQuote = !inQuote;
 							break;
 						case '\\' :
-							endIndex++; // skip the escaped char
+							cursor++; // skip the escaped char
+							if (cursor == length) {
+								throw new IllegalArgumentException("unterminated escape");
+							}
 							break;
 						case ';' :
-							if (!inQuote)
-								break out;
+							if (!inQuote) {
+								break out; // end of pattern
+							}
+							break;
+					}
+					if (c != ' ') { // ignore trailing whitespace
+						endIndex = cursor + 1;
 					}
-					endIndex++;
-				}
-				if (endIndex > dnChain.length()) {
-					throw new IllegalArgumentException("unterminated escape");
 				}
-				parsed.add(dnChain.substring(startIndex, endIndex));
-				startIndex = endIndex + 1;
-				startIndex = skipSpaces(dnChain, startIndex);
+				parsed.add(pattern.substring(startIndex, endIndex));
+				startIndex = skipSpaces(pattern, cursor + 1);
+			}
+			if (c == ';') { // last non-whitespace character was a semi-colon
+				throw new IllegalArgumentException("empty pattern");
 			}
 
-			// Now we parse is a list of strings, lets make List of rdn out
-			// of them
+			// Now we have parsed into a list of strings, lets make List of rdn
+			// out of them
 			for (int i = 0; i < parsed.size(); i++) {
 				String dn = (String) parsed.get(i);
 				if (dn.equals(STAR_WILDCARD) || dn.equals(MINUS_WILDCARD)) {
@@ -1818,11 +1830,12 @@ public class FrameworkUtil {
 				}
 				List<Object> rdns = new ArrayList<Object>();
 				if (dn.charAt(0) == '*') {
-					if (dn.charAt(1) != ',') {
+					int index = skipSpaces(dn, 1);
+					if (dn.charAt(index) != ',') {
 						throw new IllegalArgumentException("invalid wildcard prefix");
 					}
 					rdns.add(STAR_WILDCARD);
-					dn = new X500Principal(dn.substring(2)).getName(X500Principal.CANONICAL);
+					dn = new X500Principal(dn.substring(index + 1)).getName(X500Principal.CANONICAL);
 				} else {
 					dn = new X500Principal(dn).getName(X500Principal.CANONICAL);
 				}
@@ -1830,9 +1843,6 @@ public class FrameworkUtil {
 				parseDN(dn, rdns);
 				parsed.set(i, rdns);
 			}
-			if (parsed.size() == 0) {
-				throw new IllegalArgumentException("empty DN chain");
-			}
 			return parsed;
 		}
 
@@ -2056,7 +2066,7 @@ public class FrameworkUtil {
 		 *        "cn=me,c=US;*;cn=you" will match
 		 *        "cn=me,c=US";cn=you" and "cn=me,c=US;cn=her;cn=you". The
 		 *        pattern "cn=me,c=US;-;cn=you" will match "cn=me,c=US";cn=you"
-		 *        and "cn=me,c=US;cn=her;cn=him;cn=you".
+		 *        and "cn=me,c=US;cn=her;cn=him;cn=you".</li>
 		 *        <li>As a DN prefix. In this case, the DN must start with "*,".
 		 *        The wild card will match zero or more RDNs at the start of a
 		 *        DN. For example, "*,cn=me,c=US;cn=you" will match

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/InvalidSyntaxException.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/InvalidSyntaxException.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/InvalidSyntaxException.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/InvalidSyntaxException.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -28,7 +28,7 @@ package org.osgi.framework;
  * <p>
  * This exception conforms to the general purpose exception chaining mechanism.
  * 
- * @version $Id: 8820ca2db85b557cef8da09ee861249dfb5ee914 $
+ * @author $Id: 59696296eff1574fa844e3a0a975ba6c83ec59af $
  */
 
 public class InvalidSyntaxException extends Exception {
@@ -99,6 +99,7 @@ public class InvalidSyntaxException exte
 	 * @return The cause of this exception or {@code null} if no cause was set.
 	 * @since 1.3
 	 */
+	@Override
 	public Throwable getCause() {
 		return super.getCause();
 	}
@@ -114,6 +115,7 @@ public class InvalidSyntaxException exte
 	 *         been set.
 	 * @since 1.3
 	 */
+	@Override
 	public Throwable initCause(Throwable cause) {
 		return super.initCause(cause);
 	}

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/PackagePermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/PackagePermission.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/PackagePermission.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/PackagePermission.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -54,7 +54,7 @@ import java.util.Map;
  * deprecated, implies the {@code import} action.
  * 
  * @ThreadSafe
- * @version $Id: e993fbc36b6bff84182a8594af5af3cad8c4e2a3 $
+ * @author $Id: c2d45ff158a6a19ff7bc155af3ac9941cb6a89d6 $
  */
 
 public final class PackagePermission extends BasicPermission {
@@ -372,6 +372,7 @@ public final class PackagePermission ext
 	 * @return {@code true} if the specified permission is implied by this
 	 *         object; {@code false} otherwise.
 	 */
+	@Override
 	public boolean implies(Permission p) {
 		if (!(p instanceof PackagePermission)) {
 			return false;
@@ -424,6 +425,7 @@ public final class PackagePermission ext
 	 * @return Canonical string representation of the {@code PackagePermission}
 	 *         actions.
 	 */
+	@Override
 	public String getActions() {
 		String result = actions;
 		if (result == null) {
@@ -453,6 +455,7 @@ public final class PackagePermission ext
 	 * 
 	 * @return A new {@code PermissionCollection} object.
 	 */
+	@Override
 	public PermissionCollection newPermissionCollection() {
 		return new PackagePermissionCollection();
 	}
@@ -470,6 +473,7 @@ public final class PackagePermission ext
 	 *         has the same package name and actions as this
 	 *         {@code PackagePermission} object; {@code false} otherwise.
 	 */
+	@Override
 	public boolean equals(Object obj) {
 		if (obj == this) {
 			return true;
@@ -489,6 +493,7 @@ public final class PackagePermission ext
 	 * 
 	 * @return A hash code value for this object.
 	 */
+	@Override
 	public int hashCode() {
 		int h = 31 * 17 + getName().hashCode();
 		h = 31 * h + getActions().hashCode();
@@ -525,9 +530,8 @@ public final class PackagePermission ext
 	}
 
 	/**
-	 * Called by {@code <@link PackagePermission#implies(Permission)>}. This
-	 * method is only called on a requested permission which cannot have a
-	 * filter set.
+	 * Called by {@link PackagePermission#implies(Permission)}. This method is
+	 * only called on a requested permission which cannot have a filter set.
 	 * 
 	 * @return a map of properties for this permission.
 	 */
@@ -539,8 +543,8 @@ public final class PackagePermission ext
 		final Map<String, Object> map = new HashMap<String, Object>(5);
 		map.put("package.name", getName());
 		if (bundle != null) {
-			AccessController.doPrivileged(new PrivilegedAction<Object>() {
-				public Object run() {
+			AccessController.doPrivileged(new PrivilegedAction<Void>() {
+				public Void run() {
 					map.put("id", new Long(bundle.getBundleId()));
 					map.put("location", bundle.getLocation());
 					String name = bundle.getSymbolicName();
@@ -610,6 +614,7 @@ final class PackagePermissionCollection 
 	 * @throws SecurityException If this {@code PackagePermissionCollection}
 	 *         object has been marked read-only.
 	 */
+	@Override
 	public void add(final Permission permission) {
 		if (!(permission instanceof PackagePermission)) {
 			throw new IllegalArgumentException("invalid permission: " + permission);
@@ -666,6 +671,7 @@ final class PackagePermissionCollection 
 	 * @return {@code true} if {@code permission} is a proper subset of a
 	 *         permission in the set; {@code false} otherwise.
 	 */
+	@Override
 	public boolean implies(final Permission permission) {
 		if (!(permission instanceof PackagePermission)) {
 			return false;
@@ -744,6 +750,7 @@ final class PackagePermissionCollection 
 	 * 
 	 * @return Enumeration of all {@code PackagePermission} objects.
 	 */
+	@Override
 	public synchronized Enumeration<Permission> elements() {
 		List<Permission> all = new ArrayList<Permission>(permissions.values());
 		Map<String, PackagePermission> pc = filterPermissions;
@@ -768,9 +775,11 @@ final class PackagePermissionCollection 
 
 	private synchronized void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException {
 		ObjectInputStream.GetField gfields = in.readFields();
+		@SuppressWarnings("unchecked")
 		Hashtable<String, PackagePermission> hashtable = (Hashtable<String, PackagePermission>) gfields.get("permissions", null);
 		permissions = new HashMap<String, PackagePermission>(hashtable);
 		all_allowed = gfields.get("all_allowed", false);
+		@SuppressWarnings("unchecked")
 		HashMap<String, PackagePermission> fp = (HashMap<String, PackagePermission>) gfields.get("filterPermissions", null);
 		filterPermissions = fp;
 	}

Added: felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java?rev=1614569&view=auto
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java (added)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java Wed Jul 30 07:22:32 2014
@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). 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.framework;
+
+import org.osgi.annotation.versioning.ConsumerType;
+
+/**
+ * A factory for {@link Constants#SCOPE_PROTOTYPE prototype scope} services. The
+ * factory can provide multiple, customized service objects in the OSGi
+ * environment.
+ * 
+ * <p>
+ * When registering a service, a {@code PrototypeServiceFactory} object can be
+ * used instead of a service object, so that the bundle developer can create a
+ * customized service object for each caller that is using the service.
+ * 
+ * <p>
+ * When a caller uses a {@link ServiceObjects} to
+ * {@link ServiceObjects#getService() request} a service object, the framework
+ * calls the {@link #getService(Bundle, ServiceRegistration) getService} method
+ * to return a service object customized for the requesting caller. The caller
+ * can {@link ServiceObjects#ungetService(Object) release} the returned service
+ * object and the framework will call the
+ * {@link #ungetService(Bundle, ServiceRegistration, Object) ungetService}
+ * method with the service object.
+ * 
+ * <p>
+ * When a bundle uses the {@link BundleContext#getService(ServiceReference)}
+ * method to obtain a service object, the framework must act as if the service
+ * has {@link Constants#SCOPE_BUNDLE bundle scope}. That is, the framework will
+ * call the {@link #getService(Bundle, ServiceRegistration) getService} method
+ * to obtain a bundle-scoped service object which will be cached and have a use
+ * count. See {@link ServiceFactory}.
+ * 
+ * <p>
+ * A bundle can use both {@link ServiceObjects} and
+ * {@link BundleContext#getService(ServiceReference)} to obtain a service object
+ * for a service. {@link ServiceObjects#getService()} will always return a
+ * service object provided by a call to
+ * {@link #getService(Bundle, ServiceRegistration)} and
+ * {@link BundleContext#getService(ServiceReference)} will always return the
+ * bundle-scoped service object.
+ * 
+ * <p>
+ * {@code PrototypeServiceFactory} objects are only used by the Framework and
+ * are not made available to other bundles in the OSGi environment. The
+ * Framework may concurrently call a {@code PrototypeServiceFactory}.
+ * 
+ * @param <S> Type of Service
+ * @see BundleContext#getServiceObjects(ServiceReference)
+ * @see ServiceObjects
+ * @ThreadSafe
+ * @since 1.8
+ * @author $Id$
+ */
+@ConsumerType
+public interface PrototypeServiceFactory<S> extends ServiceFactory<S> {
+	/**
+	 * Returns a service object for a caller.
+	 * 
+	 * <p>
+	 * The Framework invokes this method for each caller requesting a service
+	 * object using {@link ServiceObjects#getService()}. The factory can then
+	 * return a customized service object for the caller.
+	 * 
+	 * <p>
+	 * The Framework must check that the returned service object is valid. If
+	 * the returned service object is {@code null} or is not an
+	 * {@code instanceof} all the classes named when the service was registered,
+	 * a framework event of type {@link FrameworkEvent#ERROR} is fired
+	 * containing a service exception of type
+	 * {@link ServiceException#FACTORY_ERROR} and {@code null} is returned to
+	 * the caller. If this method throws an exception, a framework event of type
+	 * {@link FrameworkEvent#ERROR} is fired containing a service exception of
+	 * type {@link ServiceException#FACTORY_EXCEPTION} with the thrown exception
+	 * as the cause and {@code null} is returned to the caller.
+	 * 
+	 * @param bundle The bundle requesting the service.
+	 * @param registration The {@code ServiceRegistration} object for the
+	 *        requested service.
+	 * @return A service object that <strong>must</strong> be an instance of all
+	 *         the classes named when the service was registered.
+	 * @see ServiceObjects#getService()
+	 */
+	public S getService(Bundle bundle, ServiceRegistration<S> registration);
+
+	/**
+	 * Releases a service object customized for a caller.
+	 * 
+	 * <p>
+	 * The Framework invokes this method when a service has been released by a
+	 * bundle such as by calling {@link ServiceObjects#ungetService(Object)}.
+	 * The service object may then be destroyed.
+	 * 
+	 * <p>
+	 * If this method throws an exception, a framework event of type
+	 * {@link FrameworkEvent#ERROR} is fired containing a service exception of
+	 * type {@link ServiceException#FACTORY_EXCEPTION} with the thrown exception
+	 * as the cause.
+	 * 
+	 * @param bundle The bundle releasing the service.
+	 * @param registration The {@code ServiceRegistration} object for the
+	 *        service being released.
+	 * @param service The service object returned by a previous call to the
+	 *        {@link #getService(Bundle, ServiceRegistration) getService}
+	 *        method.
+	 * @see ServiceObjects#ungetService(Object)
+	 */
+	public void ungetService(Bundle bundle, ServiceRegistration<S> registration, S service);
+}

Propchange: felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java
------------------------------------------------------------------------------
    svn:keywords = author date id revision rev url

Propchange: felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceEvent.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceEvent.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceEvent.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -32,7 +32,7 @@ import java.util.EventObject;
  * @Immutable
  * @see ServiceListener
  * @see AllServiceListener
- * @version $Id: 49e34e0ad5564d6f4ca0ab0053b272c22b9fb917 $
+ * @author $Id: b27a941cb68e6416825b1b717090a2eb098733f3 $
  */
 
 public class ServiceEvent extends EventObject {

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceException.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceException.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceException.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceException.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2007, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2007, 2014). 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.
@@ -30,7 +30,7 @@ package org.osgi.framework;
  * <p>
  * This exception conforms to the general purpose exception chaining mechanism.
  * 
- * @version $Id: 9f763412635f59585bb615cbc449fc7ab72b7103 $
+ * @author $Id: 32a515460813c702b127f65dda91cd23781b2a98 $
  * @since 1.5
  */
 
@@ -74,6 +74,12 @@ public class ServiceException extends Ru
 	 * @since 1.6
 	 */
 	public static final int	FACTORY_RECURSION	= 6;
+	/**
+	 * An asynchronous operation was unable to obtain the service.
+	 * 
+	 * @since 1.8
+	 */
+	public static final int	ASYNC_ERROR			= 7;
 
 	/**
 	 * Creates a {@code ServiceException} with the specified message and

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceFactory.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceFactory.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceFactory.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceFactory.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2014). 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.
@@ -16,26 +16,34 @@
 
 package org.osgi.framework;
 
+import org.osgi.annotation.versioning.ConsumerType;
+
 /**
- * Allows services to provide customized service objects in the OSGi
+ * A factory for {@link Constants#SCOPE_BUNDLE bundle scope} services. The
+ * factory can provide service objects customized for each bundle in the OSGi
  * environment.
  * 
  * <p>
  * When registering a service, a {@code ServiceFactory} object can be used
- * instead of a service object, so that the bundle developer can gain control of
- * the specific service object granted to a bundle that is using the service.
+ * instead of a service object, so that the bundle developer can create a
+ * customized service object for each bundle that is using the service.
  * 
  * <p>
- * When this happens, the {@code BundleContext.getService(ServiceReference)}
- * method calls the {@code ServiceFactory.getService} method to create a service
- * object specifically for the requesting bundle. The service object returned by
- * the {@code ServiceFactory} is cached by the Framework until the bundle
- * releases its use of the service.
+ * When a bundle {@link BundleContext#getService(ServiceReference) requests} the
+ * service object, the framework calls the
+ * {@link #getService(Bundle, ServiceRegistration) getService} method to return
+ * a service object customized for the requesting bundle. The returned service
+ * object is cached by the Framework for subsequent calls to
+ * {@link BundleContext#getService(ServiceReference)} until the bundle releases
+ * its use of the service.
  * 
  * <p>
- * When the bundle's use count for the service is decremented to zero (including
- * the bundle stopping or the service being unregistered), the
- * {@code ServiceFactory.ungetService} method is called.
+ * When the bundle's use count for the service is
+ * {@link BundleContext#ungetService(ServiceReference) decremented} to zero
+ * (including the bundle stopping or the service being unregistered), the
+ * framework will call the
+ * {@link #ungetService(Bundle, ServiceRegistration, Object) ungetService}
+ * method.
  * 
  * <p>
  * {@code ServiceFactory} objects are only used by the Framework and are not
@@ -45,18 +53,18 @@ package org.osgi.framework;
  * @param <S> Type of Service
  * @see BundleContext#getService(ServiceReference)
  * @ThreadSafe
- * @version $Id: 535776e702ec5ace54f577218ff8f7920741558b $
+ * @author $Id: f11fc6bee18315fb659c7987d1b66f1c9c95548a $
  */
-
+@ConsumerType
 public interface ServiceFactory<S> {
 	/**
-	 * Creates a new service object.
+	 * Returns a service object for a bundle.
 	 * 
 	 * <p>
 	 * The Framework invokes this method the first time the specified
 	 * {@code bundle} requests a service object using the
-	 * {@code BundleContext.getService(ServiceReference)} method. The service
-	 * factory can then return a specific service object for each bundle.
+	 * {@link BundleContext#getService(ServiceReference)} method. The factory
+	 * can then return a customized service object for each bundle.
 	 * 
 	 * <p>
 	 * The Framework must check that the returned service object is valid. If
@@ -76,9 +84,10 @@ public interface ServiceFactory<S> {
 	 * 
 	 * <p>
 	 * The Framework caches the valid service object and will return the same
-	 * service object on any future call to {@code BundleContext.getService} for
-	 * the specified bundle. This means the Framework must not allow this method
-	 * to be concurrently called for the specified bundle.
+	 * service object on any future call to
+	 * {@link BundleContext#getService(ServiceReference)} for the specified
+	 * bundle. This means the Framework must not allow this method to be
+	 * concurrently called for the specified bundle.
 	 * 
 	 * @param bundle The bundle requesting the service.
 	 * @param registration The {@code ServiceRegistration} object for the
@@ -90,7 +99,7 @@ public interface ServiceFactory<S> {
 	public S getService(Bundle bundle, ServiceRegistration<S> registration);
 
 	/**
-	 * Releases a service object.
+	 * Releases a service object customized for a bundle.
 	 * 
 	 * <p>
 	 * The Framework invokes this method when a service has been released by a

Modified: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceListener.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceListener.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceListener.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -17,6 +17,7 @@
 package org.osgi.framework;
 
 import java.util.EventListener;
+import org.osgi.annotation.versioning.ConsumerType;
 
 /**
  * A {@code ServiceEvent} listener. {@code ServiceListener} is a listener
@@ -49,9 +50,9 @@ import java.util.EventListener;
  * @see ServiceEvent
  * @see ServicePermission
  * @ThreadSafe
- * @version $Id: 601dfda6183ab7f18cd3916958a39734ea141c25 $
+ * @author $Id: 8468dbc769382269184c932d41e084cb2fa58eb9 $
  */
-
+@ConsumerType
 public interface ServiceListener extends EventListener {
 	/**
 	 * Receives notification that a service has had a lifecycle change.

Added: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceObjects.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceObjects.java?rev=1614569&view=auto
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceObjects.java (added)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceObjects.java Wed Jul 30 07:22:32 2014
@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). 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.framework;
+
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Allows multiple service objects for a service to be obtained.
+ * 
+ * <p>
+ * For services with {@link Constants#SCOPE_PROTOTYPE prototype} scope, multiple
+ * service objects for the service can be obtained. For services with
+ * {@link Constants#SCOPE_SINGLETON singleton} or {@link Constants#SCOPE_BUNDLE
+ * bundle} scope, only one, use-counted service object is available to a
+ * requesting bundle.
+ * 
+ * <p>
+ * Any unreleased service objects obtained from this {@code ServiceObjects}
+ * object are automatically released by the framework when the bundle associated
+ * with the BundleContext used to create this {@code ServiceObjects} object is
+ * stopped.
+ * 
+ * @param <S> Type of Service
+ * @see BundleContext#getServiceObjects(ServiceReference)
+ * @see PrototypeServiceFactory
+ * @ThreadSafe
+ * @since 1.8
+ * @author $Id$
+ */
+@ProviderType
+public interface ServiceObjects<S> {
+	/**
+	 * Returns a service object for the {@link #getServiceReference()
+	 * associated} service.
+	 * 
+	 * <p>
+	 * This {@code ServiceObjects} object can be used to obtain multiple service
+	 * objects for the associated service if the service has
+	 * {@link Constants#SCOPE_PROTOTYPE prototype} scope.
+	 * 
+	 * <p>
+	 * If the associated service has {@link Constants#SCOPE_SINGLETON singleton}
+	 * or {@link Constants#SCOPE_BUNDLE bundle} scope, this method behaves the
+	 * same as calling the {@link BundleContext#getService(ServiceReference)}
+	 * method for the associated service. That is, only one, use-counted service
+	 * object is available from this {@link ServiceObjects} object.
+	 * 
+	 * <p>
+	 * This method will always return {@code null} when the associated service
+	 * has been unregistered.
+	 * 
+	 * <p>
+	 * For a prototype scope service, the following steps are required to obtain
+	 * a service object:
+	 * <ol>
+	 * <li>If the associated service has been unregistered, {@code null} is
+	 * returned.</li>
+	 * <li>The
+	 * {@link PrototypeServiceFactory#getService(Bundle, ServiceRegistration)}
+	 * method is called to supply a customized service object for the caller.</li>
+	 * <li>If the service object returned by the {@code PrototypeServiceFactory}
+	 * object is {@code null}, not an {@code instanceof} all the classes named
+	 * when the service was registered or the {@code PrototypeServiceFactory}
+	 * object throws an exception, {@code null} is returned and a Framework
+	 * event of type {@link FrameworkEvent#ERROR} containing a
+	 * {@link ServiceException} describing the error is fired.</li>
+	 * <li>The customized service object is returned.</li>
+	 * </ol>
+	 * 
+	 * @return A service object for the associated service or {@code null} if
+	 *         the service is not registered, the customized service object
+	 *         returned by a {@code ServiceFactory} does not implement the
+	 *         classes under which it was registered or the
+	 *         {@code ServiceFactory} threw an exception.
+	 * @throws IllegalStateException If the BundleContext used to create this
+	 *         {@code ServiceObjects} object is no longer valid.
+	 * @see #ungetService(Object)
+	 */
+	public S getService();
+
+	/**
+	 * Releases a service object for the {@link #getServiceReference()
+	 * associated} service.
+	 * 
+	 * <p>
+	 * This {@code ServiceObjects} object can be used to obtain multiple service
+	 * objects for the associated service if the service has
+	 * {@link Constants#SCOPE_PROTOTYPE prototype} scope. If the associated
+	 * service has {@link Constants#SCOPE_SINGLETON singleton} or
+	 * {@link Constants#SCOPE_BUNDLE bundle} scope, this method behaves the same
+	 * as calling the {@link BundleContext#ungetService(ServiceReference)}
+	 * method for the associated service. That is, only one, use-counted service
+	 * object is available from this {@link ServiceObjects} object.
+	 * 
+	 * <p>
+	 * For a prototype scope service, the following steps are required to
+	 * release a service object:
+	 * <ol>
+	 * <li>If the associated service has been unregistered, this method returns
+	 * without doing anything.</li>
+	 * <li>The
+	 * {@link PrototypeServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
+	 * method is called to release the specified service object.</li>
+	 * </ol>
+	 * 
+	 * <p>
+	 * The specified service object must no longer be used and all references to
+	 * it should be destroyed after calling this method.
+	 * 
+	 * @param service A service object previously provided by this
+	 *        {@code ServiceObjects} object.
+	 * @throws IllegalStateException If the BundleContext used to create this
+	 *         {@code ServiceObjects} object is no longer valid.
+	 * @throws IllegalArgumentException If the specified service object was not
+	 *         provided by this {@code ServiceObjects} object.
+	 * @see #getService()
+	 */
+	public void ungetService(S service);
+
+	/**
+	 * Returns the {@link ServiceReference} for the service associated with this
+	 * {@code ServiceObjects} object.
+	 * 
+	 * @return The {@link ServiceReference} for the service associated with this
+	 *         {@code ServiceObjects} object.
+	 */
+	public ServiceReference<S> getServiceReference();
+}



Mime
View raw message