Move org.osgi.service.resolver package to the framework

6 files changed, 452 insertions, 0 deletions

diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/HostedCapability.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/HostedCapability.java
new file mode 100644
index 000000000..db698baa0
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/HostedCapability.java
@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) OSGi Alliance (2012). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.resolver;
+
+import org.osgi.resource.Capability;
+import org.osgi.resource.Resource;
+
+/**
+ * A capability hosted by a resource.
+ * 
+ * <p>
+ * A HostedCapability is a Capability where the {@link #getResource()} method
+ * returns a Resource that hosts this Capability instead of declaring it. This
+ * is necessary for cases where the declaring Resource of a Capability does not
+ * match the runtime state. For example, this is the case for fragments attached
+ * to a host. Most fragment declared capabilities and requirements become hosted
+ * by the host resource. Since a fragment can attach to multiple hosts, a single
+ * capability can actually be hosted multiple times.
+ * 
+ * @ThreadSafe
+ * @noimplement
+ * @version $Id$
+ */
+public interface HostedCapability extends Capability {
+
+	/**
+	 * Return the Resource that hosts this Capability.
+	 * 
+	 * @return The Resource that hosts this Capability.
+	 */
+	Resource getResource();
+
+	/**
+	 * Return the Capability hosted by the Resource.
+	 * 
+	 * @return The Capability hosted by the Resource.
+	 */
+	Capability getDeclaredCapability();
+}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/ResolutionException.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/ResolutionException.java
new file mode 100644
index 000000000..42e5773e3
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/ResolutionException.java
@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) OSGi Alliance (2011, 2012). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.resolver;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import org.osgi.resource.Requirement;
+
+/**
+ * Indicates failure to resolve a set of requirements.
+ * 
+ * <p>
+ * If a resolution failure is caused by a missing mandatory dependency a
+ * resolver may include any requirements it has considered in the resolution
+ * exception. Clients may access this set of dependencies via the
+ * {@link #getUnresolvedRequirements()} method.
+ * 
+ * <p>
+ * Resolver implementations may extend this class to provide extra state
+ * information about the reason for the resolution failure.
+ * 
+ * @version $Id$
+ */
+public class ResolutionException extends Exception {
+
+	private static final long				serialVersionUID	= 1L;
+
+	private final Collection<Requirement>	unresolvedRequirements;
+
+	/**
+	 * Create a {@code ResolutionException} with the specified message, cause
+	 * and unresolved requirements.
+	 * 
+	 * @param message The message.
+	 * @param cause The cause of this exception.
+	 * @param unresolvedRequirements The unresolved mandatory requirements from
+	 *        mandatory resources or {@code null} if no unresolved requirements
+	 *        information is provided.
+	 */
+	public ResolutionException(String message, Throwable cause, Collection<Requirement> unresolvedRequirements) {
+		super(message, cause);
+		if ((unresolvedRequirements == null) || unresolvedRequirements.isEmpty()) {
+			this.unresolvedRequirements = emptyCollection();
+		} else {
+			this.unresolvedRequirements = Collections.unmodifiableCollection(new ArrayList<Requirement>(unresolvedRequirements));
+		}
+	}
+
+	/**
+	 * Create a {@code ResolutionException} with the specified message.
+	 * 
+	 * @param message The message.
+	 */
+	public ResolutionException(String message) {
+		super(message);
+		unresolvedRequirements = emptyCollection();
+	}
+
+	/**
+	 * Create a {@code ResolutionException} with the specified cause.
+	 * 
+	 * @param cause The cause of this exception.
+	 */
+	public ResolutionException(Throwable cause) {
+		super(cause);
+		unresolvedRequirements = emptyCollection();
+	}
+
+	private static <T> Collection<T> emptyCollection() {
+		return Collections.EMPTY_LIST;
+	}
+
+	/**
+	 * Return the unresolved requirements, if any, for this exception.
+	 * 
+	 * <p>
+	 * The unresolved requirements are provided for informational purposes and
+	 * the specific set of unresolved requirements that are provided after a
+	 * resolve failure is not defined.
+	 * 
+	 * @return A collection of the unresolved requirements for this exception.
+	 *         The returned collection may be empty if no unresolved
+	 *         requirements information is provided.
+	 */
+	public Collection<Requirement> getUnresolvedRequirements() {
+		return unresolvedRequirements;
+	}
+}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/ResolveContext.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/ResolveContext.java
new file mode 100644
index 000000000..f92eae32a
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/ResolveContext.java
@@ -0,0 +1,184 @@
+/*
+ * Copyright (c) OSGi Alliance (2011, 2012). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.resolver;
+
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import org.osgi.resource.Capability;
+import org.osgi.resource.Requirement;
+import org.osgi.resource.Resource;
+import org.osgi.resource.Wiring;
+
+/**
+ * A resolve context provides resources, options and constraints to the
+ * potential solution of a {@link Resolver#resolve(ResolveContext) resolve}
+ * operation.
+ * 
+ * <p>
+ * Resolve Contexts:
+ * <ul>
+ * <li>Specify the mandatory and optional resources to resolve. The mandatory
+ * and optional resources must be consistent and correct. For example, they must
+ * not violate the singleton policy of the implementer.</li>
+ * <li>Provide {@link Capability capabilities} that the Resolver can use to
+ * satisfy {@link Requirement requirements} via the
+ * {@link #findProviders(Requirement)} method</li>
+ * <li>Constrain solutions via the {@link #getWirings()} method. A wiring
+ * consists of a map of existing {@link Resource resources} to {@link Wiring
+ * wiring}.</li>
+ * <li>Filter requirements that are part of a resolve operation via the
+ * {@link #isEffective(Requirement)}.</li>
+ * </ul>
+ * 
+ * <p>
+ * A resolver may call the methods on the resolve context any number of times
+ * during a resolve operation using any thread. Implementors should ensure that
+ * this class is properly thread safe.
+ * 
+ * <p>
+ * Except for {@link #insertHostedCapability(List, HostedCapability)}, the
+ * resolve context methods must be <i>idempotent</i>. This means that resources
+ * must have constant capabilities and requirements and the resolve context must
+ * return a consistent set of capabilities, wires and effective requirements.
+ * 
+ * @ThreadSafe
+ * @version $Id$
+ */
+public abstract class ResolveContext {
+	/**
+	 * Return the resources that must be resolved for this resolve context.
+	 * 
+	 * <p>
+	 * The default implementation returns an empty collection.
+	 * 
+	 * @return The resources that must be resolved for this resolve context. May
+	 *         be empty if there are no mandatory resources.
+	 */
+	public Collection<Resource> getMandatoryResources() {
+		return emptyCollection();
+	}
+
+	/**
+	 * Return the resources that the resolver should attempt to resolve for this
+	 * resolve context. Inability to resolve one of the specified resources will
+	 * not result in a resolution exception.
+	 * 
+	 * <p>
+	 * The default implementation returns an empty collection.
+	 * 
+	 * @return The resources that the resolver should attempt to resolve for
+	 *         this resolve context. May be empty if there are no mandatory
+	 *         resources.
+	 */
+	public Collection<Resource> getOptionalResources() {
+		return emptyCollection();
+	}
+
+	private static <T> Collection<T> emptyCollection() {
+		return Collections.EMPTY_LIST;
+	}
+
+	/**
+	 * Find Capabilities that match the given Requirement.
+	 * <p>
+	 * The returned list contains {@link Capability} objects where the Resource
+	 * must be the declared Resource of the Capability. The Resolver can then
+	 * add additional {@link HostedCapability} objects with the
+	 * {@link #insertHostedCapability(List, HostedCapability)} method when it,
+	 * for example, attaches fragments. Those {@link HostedCapability} objects
+	 * will then use the host's Resource which likely differs from the declared
+	 * Resource of the corresponding Capability.
+	 * 
+	 * <p>
+	 * The returned list is in priority order such that the Capabilities with a
+	 * lower index have a preference over those with a higher index. The
+	 * resolver must use the
+	 * {@link #insertHostedCapability(List, HostedCapability)} method to add
+	 * additional Capabilities to maintain priority order. In general, this is
+	 * necessary when the Resolver uses Capabilities declared in a Resource but
+	 * that must originate from an attached host.
+	 * 
+	 * <p>
+	 * Each returned Capability must match the given Requirement. This implies
+	 * that the filter in the Requirement must match as well as any namespace
+	 * specific directives. For example, the mandatory attributes for the
+	 * {@code osgi.wiring.package} namespace.
+	 * 
+	 * @param requirement The requirement that a resolver is attempting to
+	 *        satisfy. Must not be {@code null}.
+	 * @return A list of {@link Capability} objects that match the specified
+	 *         requirement.
+	 */
+	public abstract List<Capability> findProviders(Requirement requirement);
+
+	/**
+	 * Add a {@link HostedCapability} to the list of capabilities returned from
+	 * {@link #findProviders(Requirement)}.
+	 * 
+	 * <p>
+	 * This method is used by the {@link Resolver} to add Capabilities that are
+	 * hosted by another Resource to the list of Capabilities returned from
+	 * {@link #findProviders(Requirement)}. This function is necessary to allow
+	 * fragments to attach to hosts, thereby changing the origin of a
+	 * Capability. This method must insert the specified HostedCapability in a
+	 * place that makes the list maintain the preference order. It must return
+	 * the index in the list of the inserted {@link HostedCapability}.
+	 * 
+	 * @param capabilities The list returned from
+	 *        {@link #findProviders(Requirement)}. Must not be {@code null}.
+	 * @param hostedCapability The HostedCapability to insert in the specified
+	 *        list. Must not be {@code null}.
+	 * @return The index in the list of the inserted HostedCapability.
+	 * 
+	 */
+	public abstract int insertHostedCapability(List<Capability> capabilities, HostedCapability hostedCapability);
+
+	/**
+	 * Test if a given requirement should be wired in the resolve operation. If
+	 * this method returns {@code false}, then the resolver should ignore this
+	 * requirement during the resolve operation.
+	 * 
+	 * <p>
+	 * The primary use case for this is to test the {@code effective} directive
+	 * on the requirement, though implementations are free to use any effective
+	 * test.
+	 * 
+	 * @param requirement The Requirement to test. Must not be {@code null}.
+	 * @return {@code true} if the requirement should be considered as part of
+	 *         the resolve operation.
+	 */
+	public abstract boolean isEffective(Requirement requirement);
+
+	/**
+	 * Returns the wirings for existing resolved resources.
+	 * 
+	 * <p>
+	 * For example, if this resolve context is for an OSGi framework, then the
+	 * result would contain all the currently resolved bundles with each
+	 * bundle's current wiring.
+	 * 
+	 * <p>
+	 * Multiple calls to this method for this resolve context must return the
+	 * same result.
+	 * 
+	 * @return The wirings for existing resolved resources. The returned map is
+	 *         unmodifiable.
+	 */
+	public abstract Map<Resource, Wiring> getWirings();
+}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/Resolver.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/Resolver.java
new file mode 100644
index 000000000..dfb89b8d0
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/Resolver.java
@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) OSGi Alliance (2006, 2012). 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.
+ */
+
+// This document is an experimental draft to enable interoperability
+// between bundle repositories. There is currently no commitment to
+// turn this draft into an official specification.
+
+package org.osgi.service.resolver;
+
+import java.util.List;
+import java.util.Map;
+import org.osgi.resource.Resource;
+import org.osgi.resource.Wire;
+
+/**
+ * A resolver service resolves the specified resources in the context supplied
+ * by the caller.
+ * 
+ * @ThreadSafe
+ * @noimplement
+ * @version $Id$
+ */
+public interface Resolver {
+	/**
+	 * Resolve the specified resolve context and return any new resources and
+	 * wires to the caller.
+	 * 
+	 * <p>
+	 * The resolver considers two groups of resources:
+	 * <ul>
+	 * <li>Mandatory - any resource in the
+	 * {@link ResolveContext#getMandatoryResources() mandatory group} must be
+	 * resolved. A failure to satisfy any mandatory requirement for these
+	 * resources will result in throwing a {@link ResolutionException}</li>
+	 * <li>Optional - any resource in the
+	 * {@link ResolveContext#getOptionalResources() optional group} may be
+	 * resolved. A failure to satisfy a mandatory requirement for a resource in
+	 * this group will not fail the overall resolution but no resources or wires
+	 * will be returned for that resource.</li>
+	 * </ul>
+	 * 
+	 * <p>
+	 * The resolve method returns the delta between the start state defined by
+	 * {@link ResolveContext#getWirings()} and the end resolved state. That is,
+	 * only new resources and wires are included.
+	 * 
+	 * <p>
+	 * The behavior of the resolver is not defined if the specified resolve
+	 * context supplies inconsistent information.
+	 * 
+	 * @param context The resolve context for the resolve operation. Must not be
+	 *        {@code null}.
+	 * @return The new resources and wires required to satisfy the specified
+	 *         resolve context. The returned map is the property of the caller
+	 *         and can be modified by the caller.
+	 * @throws ResolutionException If the resolution cannot be satisfied.
+	 */
+	Map<Resource, List<Wire>> resolve(ResolveContext context) throws ResolutionException;
+}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/package-info.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/package-info.java
new file mode 100644
index 000000000..db1706d83
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/package-info.java
@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) OSGi Alliance (2010, 2012). 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.
+ */
+
+/**
+ * Resolver Service Package Version 1.0.
+ * 
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest. This package has two types of
+ * users: the consumers that use the API in this package and the providers that
+ * implement the API in this package.
+ * 
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code  Import-Package: org.osgi.service.resolver; version="[1.0,2.0)"}
+ * <p>
+ * Example import for providers implementing the API in this package:
+ * <p>
+ * {@code  Import-Package: org.osgi.service.resolver; version="[1.0,1.1)"}
+ * 
+ * @version $Id$
+ */
+
+package org.osgi.service.resolver;
+
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/packageinfo b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/packageinfo
new file mode 100644
index 000000000..7c8de0324
--- /dev/null
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/packageinfo
@@ -0,0 +1 @@
+version 1.0