Bug 552573 - Update OSGi Connect API

- Rename ConnectFactory to ConnectFramework
- Move newFramework with ConnectFramework from FrameworkFactory
to ConnectFrameworkFactory in the connect package

Change-Id: I71044befd16542bc84d2fc4c9b7ffdeb8a32eba5
Signed-off-by: Thomas Watson <tjwatson@us.ibm.com>

9 files changed, 180 insertions, 87 deletions

diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkUtil.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkUtil.java
index 8bd7c5b44..0c31d9f7b 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkUtil.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkUtil.java
@@ -37,6 +37,7 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.ServiceLoader;
 import java.util.Set;
 
@@ -203,33 +204,45 @@ public class FrameworkUtil {
 	}
 
 	/**
-	 * Return a {@code Bundle} for the specified bundle class. The returned
-	 * {@code Bundle} is the bundle associated with the bundle class loader
-	 * which defined the specified class.
+	 * Return a {@code Bundle} for the specified bundle class loader.
 	 * 
-	 * @param classFromBundle A class defined by a bundle class loader.
+	 * @param bundleClassLoader A bundle class loader.
+	 * @return An Optional containing {@code Bundle} for the specified bundle
+	 *         class loader or an empty Optional if the specified class loader
+	 *         is not associated with a specific bundle.
+	 * @since 1.10
+	 */
+	public static Optional<Bundle> getBundle(ClassLoader bundleClassLoader) {
+		requireNonNull(bundleClassLoader);
+		return Optional
+				.ofNullable((bundleClassLoader instanceof BundleReference)
+						? ((BundleReference) bundleClassLoader).getBundle()
+						: null);
+	}
+
+	/**
+	 * Return a {@code Bundle} for the specified bundle class.
+	 * 
+	 * @param classFromBundle A class defined by a bundle.
 	 * @return A {@code Bundle} for the specified bundle class or {@code null}
-	 *         if the specified class was not defined by a bundle class loader.
+	 *         if the specified class was not defined by a bundle.
 	 * @since 1.5
 	 */
-	public static Bundle getBundle(final Class<?> classFromBundle) {
+	public static Bundle getBundle(Class< ? > classFromBundle) {
 		// We use doPriv since the caller may not have permission
 		// to call getClassLoader.
-		ClassLoader cl = AccessController
-				.doPrivileged( (PrivilegedAction<ClassLoader>) 
-						() -> classFromBundle.getClassLoader());
-
-		if (cl instanceof BundleReference) {
-			return ((BundleReference) cl).getBundle();
-		}
-
-		for (FrameworkUtilHelper helper : helpers) {
-			Bundle b = helper.getBundle(classFromBundle);
-			if (b != null) {
-				return b;
-			}
-		}
-		return null;
+		Optional<ClassLoader> cl = Optional
+				.ofNullable(AccessController.doPrivileged(
+						(PrivilegedAction<ClassLoader>) () -> classFromBundle
+								.getClassLoader()));
+
+		return cl.flatMap(FrameworkUtil::getBundle)
+				.orElseGet(() -> helpers.stream()
+						.map(helper -> helper.getBundle(classFromBundle))
+						.filter(Optional::isPresent)
+						.map(Optional::get)
+						.findFirst()
+						.orElse(null));
 	}
 
 	private final static List<FrameworkUtilHelper> helpers;
@@ -240,9 +253,9 @@ public class FrameworkUtil {
 					.doPrivileged(
 							(PrivilegedAction<ServiceLoader<FrameworkUtilHelper>>) () -> ServiceLoader
 									.load(FrameworkUtilHelper.class,
-											FrameworkUtilHelper.class.getClassLoader()));
-
-			helperLoader.forEach((h) -> l.add(h));
+											FrameworkUtilHelper.class
+													.getClassLoader()));
+			helperLoader.forEach(l::add);
 		} catch (Throwable error) {
 			// try hard not to fail static <clinit>
 			try {
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceReference.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceReference.java
index 1454244c3..4d412aa61 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceReference.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/ServiceReference.java
@@ -53,7 +53,8 @@ import org.osgi.annotation.versioning.ProviderType;
  * @author $Id$
  */
 @ProviderType
-public interface ServiceReference<S> extends Comparable<Object> {
+public interface ServiceReference<S>
+		extends Comparable<Object>, BundleReference {
 	/**
 	 * Returns the property value to which the specified property key is mapped
 	 * in the properties {@code Dictionary} object of the service referenced by
@@ -109,6 +110,7 @@ public interface ServiceReference<S> extends Comparable<Object> {
 	 *         already been unregistered.
 	 * @see BundleContext#registerService(String[],Object,Dictionary)
 	 */
+	@Override
 	public Bundle getBundle();
 
 	/**
@@ -212,4 +214,27 @@ public interface ServiceReference<S> extends Comparable<Object> {
 	 * @since 1.9
 	 */
 	public Dictionary<String,Object> getProperties();
+
+	/**
+	 * Adapt this {@code ServiceReference} object to the specified type.
+	 * <p>
+	 * Adapting this {@code ServiceReference} object to the specified type may
+	 * require certain checks, including security checks, to succeed. If a check
+	 * does not succeed, then this {@code ServiceReference} object cannot be
+	 * adapted and {@code null} is returned.
+	 * 
+	 * @param <A> The type to which this {@code ServiceReference} object is to
+	 *            be adapted.
+	 * @param type Class object for the type to which this
+	 *            {@code ServiceReference} object is to be adapted.
+	 * @return The object, of the specified type, to which this
+	 *         {@code ServiceReference} object has been adapted or {@code null}
+	 *         if this {@code ServiceReference} object cannot be adapted to the
+	 *         specified type.
+	 * @throws SecurityException If the caller does not have the appropriate
+	 *             {@code AdaptPermission[type,this,ADAPT]}, and the Java
+	 *             Runtime Environment supports permissions.
+	 * @since 1.10
+	 */
+	<A> A adapt(Class<A> type);
 }
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java
index 1d3691dbb..a109b609c 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java
@@ -95,16 +95,18 @@ public interface ConnectContent {
 	 * connect content. The framework may lazily open the content until the
 	 * first request is made to access the bundle revision content.
 	 * 
+	 * @return a reference to this object
 	 * @throws IOException if an error occurred opening the content
 	 */
-	void open() throws IOException;
+	ConnectContent open() throws IOException;
 
 	/**
 	 * Closes this connect content.
 	 * 
+	 * @return a reference to this object
 	 * @throws IOException if an error occurred closing the connect content
 	 */
-	void close() throws IOException;
+	ConnectContent close() throws IOException;
 
 	/**
 	 * Represents the entry of a connect module
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFramework.java
index 31e1a83a2..a1f4f0adc 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFactory.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFramework.java
@@ -22,29 +22,28 @@ import java.util.Optional;
 import org.osgi.framework.BundleActivator;
 import org.osgi.framework.Constants;
 import org.osgi.framework.launch.Framework;
-import org.osgi.framework.launch.FrameworkFactory;
 
 /**
- * A connect factory creates instances of {@link ConnectModule} that are used by
- * a {@link Framework} instance to provide content and classes for a bundle
- * installed in the Framework. A connect factory is provided when
- * {@link FrameworkFactory#newFramework(java.util.Map) creating} a framework
- * instance. Because a connect factory instance can participate in the
- * initialization of the framework and the lifecycle of a framework instance the
- * connect factory instance should only be used with a single framework
- * instance.
+ * A connect framework provides access to instances of {@link ConnectModule}
+ * that are used by a {@link Framework} instance to provide content and classes
+ * for a bundle installed in the Framework. A connect framework is provided when
+ * {@link ConnectFrameworkFactory#newFramework(java.util.Map, ConnectFramework)
+ * creating} a framework instance. Because a connect framework instance can
+ * participate in the initialization of the framework and the life cycle of a
+ * framework instance the connect framework instance should only be used with a
+ * single framework instance.
  * 
  * @ThreadSafe
  * @author $Id$
  */
-public interface ConnectFactory {
+public interface ConnectFramework {
 
 	/**
-	 * Initializes the connect factory with the
+	 * Initializes the connect framework with the
 	 * {@link Constants#FRAMEWORK_STORAGE framework persistent storage} file and
 	 * framework properties configured for a {@link Framework} instance. This
 	 * method is called once by a {@link Framework} instance and is called
-	 * before any other methods on this factory are called.
+	 * before any other methods on this connect framework are called.
 	 * 
 	 * @param configuration The framework properties to used configure the new
 	 *            framework instance. An unmodifiable map of framework
@@ -53,8 +52,9 @@ public interface ConnectFactory {
 	 * @param storage the persistent storage area used by the {@link Framework}
 	 *            or {@code null} if the if the platform does not have file
 	 *            system support.
+	 * @return a reference to this object
 	 */
-	void initialize(File storage, Map<String,String> configuration);
+	ConnectFramework initialize(File storage, Map<String,String> configuration);
 
 	/**
 	 * Returns the connect module for the specified bundle location. If an
@@ -71,19 +71,19 @@ public interface ConnectFactory {
 	Optional<ConnectModule> getModule(String location);
 
 	/**
-	 * Creates a new activator for this factory. A new activator is created by
-	 * the framework each time the framework is {@link Framework#init()
-	 * initialized}. An activator allows the factory to participate in the
-	 * framework lifecyle. When the framework is {@link Framework#init()
-	 * initialized} the activator
+	 * Creates a new activator for this connect framework. A new activator is
+	 * created by the framework each time the framework is
+	 * {@link Framework#init() initialized}. An activator allows the connect
+	 * framework to participate in the framework life cyle. When the framework
+	 * is {@link Framework#init() initialized} the activator
 	 * {@link BundleActivator#start(org.osgi.framework.BundleContext) start}
 	 * method is called. When the framework is {@link Framework#stop() stopped}
 	 * the activator
 	 * {@link BundleActivator#stop(org.osgi.framework.BundleContext) stop}
 	 * method is called
 	 * 
-	 * @return a new activator for this factory or {@link Optional#empty()
-	 *         empty} if no activator is available for the factory
+	 * @return a new activator for this connect framework or
+	 *         {@link Optional#empty() empty} if no activator is available
 	 */
 	Optional<BundleActivator> createBundleActivator();
 }
\ No newline at end of file
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java
new file mode 100644
index 000000000..cb596326b
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java
@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) OSGi Alliance (2019). 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.connect;
+
+import java.util.Map;
+
+import org.osgi.annotation.versioning.ProviderType;
+import org.osgi.framework.Bundle;
+import org.osgi.framework.launch.Framework;
+
+/**
+ * A factory for creating {@link Framework} instances.
+ * <p>
+ * If a framework supports {@link ConnectFramework} then the implementation jar
+ * must contain the following resource:
+ * 
+ * <pre>
+ * /META-INF/services/org.osgi.framework.connect.ConnectFrameworkFactory
+ * </pre>
+ * 
+ * This UTF-8 encoded resource must contain the name of the framework
+ * implementation's ConnectFrameworkFactory implementation class. Space and tab
+ * characters, including blank lines, in the resource must be ignored. The
+ * number sign ({@code '#'} &#92;u0023) and all characters following it on each
+ * line are a comment and must be ignored.
+ * <p>
+ * Launchers can find the name of the ConnectFrameworkFactory implementation
+ * class in the resource and then load and construct a ConnectFrameworkFactory
+ * object for the framework implementation. The ConnectFrameworkFactory
+ * implementation class must have a public, no-argument constructor. Java&#8482;
+ * SE 6 introduced the {@code ServiceLoader} class which can create a
+ * ConnectFrameworkFactory instance from the resource.
+ * 
+ * @ThreadSafe
+ * @author $Id$
+ */
+@ProviderType
+public interface ConnectFrameworkFactory {
+	/**
+	 * Create a new {@link Framework} instance using the specified
+	 * {@link ConnectFramework connect framework}.
+	 * 
+	 * @param configuration The framework properties to configure the new
+	 *            framework instance. If framework properties are not provided
+	 *            by the configuration argument, the created framework instance
+	 *            must use some reasonable default configuration appropriate for
+	 *            the current VM. For example, the system packages for the
+	 *            current execution environment should be properly exported. The
+	 *            specified configuration argument may be {@code null}. The
+	 *            created framework instance must copy any information needed
+	 *            from the specified configuration argument since the
+	 *            configuration argument can be changed after the framework
+	 *            instance has been created.
+	 * @param connectFramework The connect framework that the new framework
+	 *            instance will use. The specified connect framework argument
+	 *            may be {@code null}.
+	 * @return A new, configured {@link Framework} instance. The framework
+	 *         instance must be in the {@link Bundle#INSTALLED} state.
+	 * @throws SecurityException If the caller does not have
+	 *             {@code AllPermission}, and the Java Runtime Environment
+	 *             supports permissions.
+	 * @see ConnectFramework
+	 * @since 1.3
+	 */
+	Framework newFramework(Map<String,String> configuration,
+			ConnectFramework connectFramework);
+}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java
index 8c8da1842..3b1164ea6 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java
@@ -16,6 +16,8 @@
 
 package org.osgi.framework.connect;
 
+import java.util.Optional;
+
 import org.osgi.framework.Bundle;
 import org.osgi.framework.FrameworkUtil;
 
@@ -27,15 +29,15 @@ public interface FrameworkUtilHelper {
 	/**
 	 * Return a {@code Bundle} associated with the specified class.
 	 * <p>
-	 * This helper method is called by
-	 * {@link FrameworkUtil#getBundle(Class)} if the standard implementation
-	 * of {@code FrameworkUtil} cannot find the bundle.
+	 * This helper method is called by {@link FrameworkUtil#getBundle(Class)} if
+	 * the standard implementation of {@code FrameworkUtil} cannot find the
+	 * bundle.
 	 * 
 	 * @param classFromBundle A class associated with a bundle
-	 * @return A {@code Bundle} for the specified class or {@code null} if
-	 *         the specified class is not from a bundle.
+	 * @return An Optional containing a {@code Bundle} for the specified class
+	 *         or an empty Optional if the specified class is not from a bundle.
 	 */
-	default Bundle getBundle(Class< ? > classFromBundle) {
-		return null;
+	default Optional<Bundle> getBundle(Class< ? > classFromBundle) {
+		return Optional.empty();
 	}
 }
\ No newline at end of file
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/dto/ServiceReferenceDTO.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/dto/ServiceReferenceDTO.java
index 87265ded2..40c0eda3a 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/dto/ServiceReferenceDTO.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/dto/ServiceReferenceDTO.java
@@ -17,16 +17,17 @@
 package org.osgi.framework.dto;
 
 import java.util.Map;
+
 import org.osgi.dto.DTO;
 import org.osgi.framework.Constants;
 import org.osgi.framework.ServiceReference;
 
 /**
  * Data Transfer Object for a ServiceReference.
- * 
  * <p>
  * {@code ServiceReferenceDTO}s for all registered services can be obtained from
- * a {@link FrameworkDTO}. A started Bundle can be adapted to provide a
+ * a {@link FrameworkDTO}. A {@link ServiceReference} can be adapted to a
+ * {@code ServiceReferenceDTO}. A started Bundle can be adapted to provide a
  * {@code ServiceReferenceDTO[]} of the services registered by the Bundle. A
  * {@code ServiceReferenceDTO} obtained from a framework must convert service
  * property values which are not valid value types for DTOs to type
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/FrameworkFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/FrameworkFactory.java
index eb28dcaad..5f20eb739 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/FrameworkFactory.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/FrameworkFactory.java
@@ -20,7 +20,6 @@ import java.util.Map;
 
 import org.osgi.annotation.versioning.ProviderType;
 import org.osgi.framework.Bundle;
-import org.osgi.framework.connect.ConnectFactory;
 
 /**
  * A factory for creating {@link Framework} instances.
@@ -72,33 +71,4 @@ public interface FrameworkFactory {
 	 *         permissions.
 	 */
 	Framework newFramework(Map<String, String> configuration);
-
-	/**
-	 * Create a new {@link Framework} instance using the specified
-	 * {@link ConnectFactory connect factory}.
-	 * 
-	 * @param configuration The framework properties to configure the new
-	 *            framework instance. If framework properties are not provided
-	 *            by the configuration argument, the created framework instance
-	 *            must use some reasonable default configuration appropriate for
-	 *            the current VM. For example, the system packages for the
-	 *            current execution environment should be properly exported. The
-	 *            specified configuration argument may be {@code null}. The
-	 *            created framework instance must copy any information needed
-	 *            from the specified configuration argument since the
-	 *            configuration argument can be changed after the framework
-	 *            instance has been created.
-	 * @param connectFactory The connect factory that the new framework instance
-	 *            will use. The specified connect factory argument may be
-	 *            {@code null}.
-	 * @return A new, configured {@link Framework} instance. The framework
-	 *         instance must be in the {@link Bundle#INSTALLED} state.
-	 * @throws SecurityException If the caller does not have
-	 *             {@code AllPermission}, and the Java Runtime Environment
-	 *             supports permissions.
-	 * @see ConnectFactory
-	 * @since 1.3
-	 */
-	Framework newFramework(Map<String,String> configuration,
-			ConnectFactory connectFactory);
 }
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 b4e9d8e0e..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
@@ -29,7 +29,7 @@
  * @author $Id$
  */
 
-@Version("1.3")
+@Version("1.2")
 package org.osgi.framework.launch;
 
 import org.osgi.annotation.versioning.Version;