Update OSGi API for R6I20140114-0800

9 files changed, 86 insertions, 86 deletions

diff --git a/bundles/org.eclipse.osgi/.settings/.api_filters b/bundles/org.eclipse.osgi/.settings/.api_filters
index ad7c7c286..ba20c94f1 100644
--- a/bundles/org.eclipse.osgi/.settings/.api_filters
+++ b/bundles/org.eclipse.osgi/.settings/.api_filters
@@ -320,8 +320,10 @@
         </filter>
     </resource>
     <resource path="osgi/src/org/osgi/framework/launch/Framework.java" type="org.osgi.framework.launch.Framework">
-        <filter comment="Ignore OSGi API" id="1211105284">
+        <filter comment="Ignore OSGi API" id="1209008130">
             <message_arguments>
+                <message_argument value="1.2"/>
+                <message_argument value="3.10"/>
                 <message_argument value="init(FrameworkListener[])"/>
             </message_arguments>
         </filter>
diff --git a/bundles/org.eclipse.osgi/META-INF/MANIFEST.MF b/bundles/org.eclipse.osgi/META-INF/MANIFEST.MF
index 291f731b1..90d902e78 100644
--- a/bundles/org.eclipse.osgi/META-INF/MANIFEST.MF
+++ b/bundles/org.eclipse.osgi/META-INF/MANIFEST.MF
@@ -53,7 +53,7 @@ Export-Package: org.eclipse.core.runtime.adaptor;x-friends:="org.eclipse.core.ru
  org.osgi.framework.hooks.resolver;version="1.0",
  org.osgi.framework.hooks.service;version="1.1",
  org.osgi.framework.hooks.weaving;version="1.1",
- org.osgi.framework.launch;version="1.1",
+ org.osgi.framework.launch;version="1.2",
  org.osgi.framework.namespace;version="1.1",
  org.osgi.framework.startlevel;version="1.0",
  org.osgi.framework.wiring;version="1.2",
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/BundleContext.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/BundleContext.java
index fcda6d1f1..62bcb7917 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/BundleContext.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/BundleContext.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -747,16 +747,15 @@ public interface BundleContext extends BundleReference {
 	 * 
 	 * <p>
 	 * A bundle's use of a service object obtained from this method is tracked
-	 * by the bundle's use count of that service object. Each time the service
-	 * object is returned by {@link #getService(ServiceReference)} the context
-	 * bundle's use count for the service object is incremented by one. Each
-	 * time the service object is released by
-	 * {@link #ungetService(ServiceReference)} the context bundle's use count
-	 * for the service object is decremented by one.
+	 * 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 the service object drops to zero, the
-	 * bundle should no longer use the service object.
+	 * 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
@@ -766,23 +765,23 @@ public interface BundleContext extends BundleReference {
 	 * The following steps are required to get the service object:
 	 * <ol>
 	 * <li>If the service has been unregistered, {@code null} is returned.</li>
-	 * <li>If the context bundle's use count for the service object is currently
-	 * zero and the service was registered with an object implementing the
-	 * {@code ServiceFactory} interface, the
+	 * <li>If the context bundle's use count for the service is currently zero
+	 * 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 the service object for the context bundle. If the
+	 * 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. This service object is cached by the
-	 * Framework. While the context bundle's use count for the service object is
-	 * greater than zero, subsequent calls to get the services's service object
-	 * for the context bundle will return the cached service object.</li>
-	 * <li>The context bundle's use count for the service object is incremented
-	 * by one.</li>
+	 * 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>
 	 * 
@@ -810,25 +809,23 @@ public interface BundleContext extends BundleReference {
 	/**
 	 * Releases the service object for the service referenced by the specified
 	 * {@code ServiceReference} object. If the context bundle's use count for
-	 * the service object is zero, this method returns {@code false}. Otherwise,
-	 * the context bundle's use count for the service object is decremented by
-	 * one.
+	 * 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 object must no longer be used and all references to it should
-	 * be destroyed when a bundle's use count for the service object drops to
-	 * zero.
+	 * 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 object is zero or
-	 * the service has been unregistered, {@code false} is returned.</li>
-	 * <li>The context bundle's use count for the service object is decremented
-	 * by one.</li>
-	 * <li>If the context bundle's use count for the service object is currently
-	 * zero and the service was registered with a {@code ServiceFactory} object,
-	 * the
+	 * <li>If the context bundle's use count for the service is zero or 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>
 	 * <li>{@code true} is returned.</li>
@@ -836,8 +833,8 @@ public interface BundleContext extends BundleReference {
 	 * 
 	 * @param reference A reference to the service to be released.
 	 * @return {@code false} if the context bundle's use count for the service
-	 *         object is zero or if the service has been unregistered;
-	 *         {@code true} otherwise.
+	 *         is zero or if the service has been unregistered; {@code true}
+	 *         otherwise.
 	 * @throws IllegalStateException If this BundleContext is no longer valid.
 	 * @throws IllegalArgumentException If the specified
 	 *         {@code ServiceReference} was not created by the same framework
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/PrototypeServiceFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/PrototypeServiceFactory.java
index ed860a9d0..12129fe6e 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/PrototypeServiceFactory.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/PrototypeServiceFactory.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2012, 2013). All Rights Reserved.
+ * 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.
@@ -20,18 +20,19 @@ import org.osgi.annotation.versioning.ConsumerType;
 
 /**
  * A factory for {@link Constants#SCOPE_PROTOTYPE prototype scope} services. The
- * factory can provide multiple, unique service objects in the OSGi environment.
+ * 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
- * unique service object for each caller that is using the service.
+ * 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 instance, the framework
+ * {@link ServiceObjects#getService() request} a service object, the framework
  * calls the {@link #getService(Bundle, ServiceRegistration) getService} method
- * to return a service object specifically for the requesting caller. The caller
+ * 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}
@@ -42,17 +43,17 @@ import org.osgi.annotation.versioning.ConsumerType;
  * 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 instance which will be cached and have a use count.
- * See {@link ServiceFactory}.
+ * 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 an
- * instance provided by a call to
+ * 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 instance.
+ * bundle-scoped service object.
  * 
  * <p>
  * {@code PrototypeServiceFactory} objects are only used by the Framework and
@@ -74,7 +75,7 @@ public interface PrototypeServiceFactory<S> extends ServiceFactory<S> {
 	 * <p>
 	 * The Framework invokes this method for each caller requesting a service
 	 * object using {@link ServiceObjects#getService()}. The factory can then
-	 * return a specific service object for the caller.
+	 * return a customized service object for the caller.
 	 * 
 	 * <p>
 	 * The Framework must check that the returned service object is valid. If
@@ -88,7 +89,6 @@ public interface PrototypeServiceFactory<S> extends ServiceFactory<S> {
 	 * 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.
@@ -99,7 +99,7 @@ public interface PrototypeServiceFactory<S> extends ServiceFactory<S> {
 	public S getService(Bundle bundle, ServiceRegistration<S> registration);
 
 	/**
-	 * Releases a service object created for a caller.
+	 * Releases a service object customized for a caller.
 	 * 
 	 * <p>
 	 * The Framework invokes this method when a service has been released by a
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceFactory.java
index e1b3f496c..f11fc6bee 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceFactory.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceFactory.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2000, 2013). 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,19 +20,19 @@ import org.osgi.annotation.versioning.ConsumerType;
 
 /**
  * A factory for {@link Constants#SCOPE_BUNDLE bundle scope} services. The
- * factory can provide service objects unique to each bundle in the OSGi
+ * 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 create a unique
- * service object for each 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 a bundle {@link BundleContext#getService(ServiceReference) requests} the
  * service object, the framework calls the
- * {@link #getService(Bundle, ServiceRegistration) getService} method to create
- * a service object specifically for the requesting bundle. The returned service
+ * {@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.
@@ -64,7 +64,7 @@ public interface ServiceFactory<S> {
 	 * The Framework invokes this method the first time the specified
 	 * {@code bundle} requests a service object using the
 	 * {@link BundleContext#getService(ServiceReference)} method. The factory
-	 * can then return a specific service object for each bundle.
+	 * can then return a customized service object for each bundle.
 	 * 
 	 * <p>
 	 * The Framework must check that the returned service object is valid. If
@@ -99,7 +99,7 @@ public interface ServiceFactory<S> {
 	public S getService(Bundle bundle, ServiceRegistration<S> registration);
 
 	/**
-	 * Releases a service object created for a bundle.
+	 * Releases a service object customized for a bundle.
 	 * 
 	 * <p>
 	 * The Framework invokes this method when a service has been released by a
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceObjects.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceObjects.java
index 0d87a30cc..e2f8df48f 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceObjects.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceObjects.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2012, 2013). All Rights Reserved.
+ * 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.
@@ -44,45 +44,45 @@ import org.osgi.annotation.versioning.ProviderType;
 public interface ServiceObjects<S> {
 	/**
 	 * Returns a service object for the {@link #getServiceReference()
-	 * referenced} service.
+	 * associated} service.
 	 * 
 	 * <p>
 	 * This {@code ServiceObjects} object can be used to obtain multiple service
-	 * objects for the referenced service if the service has
-	 * {@link Constants#SCOPE_PROTOTYPE prototype} scope. If the referenced
+	 * 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#getService(ServiceReference)} method
-	 * for the referenced service. That is, only one, use-counted service object
+	 * 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 referenced service
+	 * 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 get
-	 * the service object:
+	 * For a prototype scope service, the following steps are required to obtain
+	 * a service object:
 	 * <ol>
-	 * <li>If the referenced service has been unregistered, {@code null} is
+	 * <li>If the associated service has been unregistered, {@code null} is
 	 * returned.</li>
 	 * <li>The
 	 * {@link PrototypeServiceFactory#getService(Bundle, ServiceRegistration)}
-	 * method is called to create a service object for the caller.</li>
+	 * 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 service object is returned.</li>
+	 * <li>The customized service object is returned.</li>
 	 * </ol>
 	 * 
-	 * @return A service object for the referenced service or {@code null} if
-	 *         the service is not registered, the service object returned by a
-	 *         {@code ServiceFactory} does not implement the classes under which
-	 *         it was registered or the {@code ServiceFactory} threw an
-	 *         exception.
+	 * @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)
@@ -91,23 +91,23 @@ public interface ServiceObjects<S> {
 
 	/**
 	 * Releases a service object for the {@link #getServiceReference()
-	 * referenced} service.
+	 * associated} service.
 	 * 
 	 * <p>
 	 * This {@code ServiceObjects} object can be used to obtain multiple service
-	 * objects for the referenced service if the service has
-	 * {@link Constants#SCOPE_PROTOTYPE prototype} scope. If the referenced
+	 * 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 referenced service. That is, only one, use-counted service
+	 * 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 the service object:
+	 * release a service object:
 	 * <ol>
-	 * <li>If the referenced service has been unregistered, this method returns
+	 * <li>If the associated service has been unregistered, this method returns
 	 * without doing anything.</li>
 	 * <li>The
 	 * {@link PrototypeServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
@@ -122,7 +122,7 @@ public interface ServiceObjects<S> {
 	 *        {@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 was not
+	 * @throws IllegalArgumentException If the specified service object was not
 	 *         provided by this {@code ServiceObjects} object.
 	 * @see #getService()
 	 */
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java
index 7cbbf0086..0fa043dd9 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2008, 2013). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2008, 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.
@@ -100,6 +100,7 @@ public interface Framework extends Bundle {
 	 *         manager already installed and the
 	 *         {@link Constants#FRAMEWORK_SECURITY} configuration property is
 	 *         set.
+	 * @since 1.2
 	 */
 	void init(FrameworkListener... listeners) throws BundleException;
 
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/package-info.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/package-info.java
index 5557485f7..db5e926ca 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/package-info.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/package-info.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2010, 2013). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2010, 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.
@@ -15,7 +15,7 @@
  */
 
 /**
- * Framework Launch Package Version 1.1.
+ * Framework Launch Package Version 1.2.
  *
  * <p>
  * Bundles wishing to use this package must list the package in the
@@ -24,12 +24,12 @@
  * <p>
  * Example import for consumers using the API in this package:
  * <p>
- * {@code  Import-Package: org.osgi.framework.launch; version="[1.1,2.0)"}
+ * {@code  Import-Package: org.osgi.framework.launch; version="[1.2,2.0)"}
  *
  * @author $Id$
  */
 
-@Version("1.1")
+@Version("1.2")
 package org.osgi.framework.launch;
 
 import org.osgi.annotation.versioning.Version;
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/packageinfo b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/packageinfo
index 3987f9c4e..ef7df68cb 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/packageinfo
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/packageinfo
@@ -1 +1 @@
-version 1.1
+version 1.2