Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThomas Watson2012-06-07 13:57:19 +0000
committerThomas Watson2012-06-07 13:57:19 +0000
commit499ac70cc96fd37279f31bb8b700f9c6b7778391 (patch)
tree8cc40c5fa0a631fba4fc5a9f088a24351ba152c5 /bundles/org.eclipse.osgi/osgi/src/org
parent9e72295bde3e8a47f8121d4122d535a35143e5a0 (diff)
downloadrt.equinox.framework-499ac70cc96fd37279f31bb8b700f9c6b7778391.tar.gz
rt.equinox.framework-499ac70cc96fd37279f31bb8b700f9c6b7778391.tar.xz
rt.equinox.framework-499ac70cc96fd37279f31bb8b700f9c6b7778391.zip
Move org.osgi.service.resolver package to the framework
Diffstat (limited to 'bundles/org.eclipse.osgi/osgi/src/org')
-rw-r--r--bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/HostedCapability.java53
-rw-r--r--bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/ResolutionException.java103
-rw-r--r--bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/ResolveContext.java184
-rw-r--r--bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/Resolver.java72
-rw-r--r--bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/package-info.java39
-rw-r--r--bundles/org.eclipse.osgi/osgi/src/org/osgi/service/resolver/packageinfo1
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

Back to the top