You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ri...@apache.org on 2011/10/20 22:54:20 UTC
svn commit: r1187045 [3/3] - in /felix/sandbox/rickhall/obr-resolver: ./
src/ src/main/ src/main/java/ src/main/java/org/ src/main/java/org/apache/
src/main/java/org/apache/felix/ src/main/java/org/apache/felix/resolver/
src/main/java/org/apache/felix/...
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Capability.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Capability.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Capability.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Capability.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.resource;
+
+import java.util.Map;
+
+/**
+ * A capability that has been declared from a {@link Resource}.
+ *
+ * @ThreadSafe
+ * @version $Id: 5597c6dd01b34d5e3a2ec05f83b6f895f114d45a $
+ */
+public interface Capability {
+
+ /**
+ * Returns the name space of this capability.
+ *
+ * @return The name space of this capability.
+ */
+ String getNamespace();
+
+ /**
+ * Returns the directives of this capability.
+ *
+ * <p>
+ * Only the following list of directives have specified semantics:
+ * <ul>
+ * <li> {@link ResourceConstants#CAPABILITY_EFFECTIVE_DIRECTIVE effective}
+ * <li> {@link ResourceConstants#CAPABILITY_USES_DIRECTIVE uses}
+ * <li> {@link ResourceConstants#CAPABILITY_MANDATORY_DIRECTIVE mandatory} -
+ * only recognized for the {@link ResourceConstants#WIRING_BUNDLE_NAMESPACE
+ * osgi.wiring.bundle} and
+ * {@link ResourceConstants#WIRING_PACKAGE_NAMESPACE osgi.wiring.package}
+ * name spaces.
+ * <li> {@link ResourceConstants#CAPABILITY_EXCLUDE_DIRECTIVE exclude} - only
+ * recognized for the {@link ResourceConstants#WIRING_PACKAGE_NAMESPACE
+ * osgi.wiring.package} name space.
+ * <li> {@link ResourceConstants#CAPABILITY_INCLUDE_DIRECTIVE include} - only
+ * recognized for the {@link ResourceConstants#WIRING_PACKAGE_NAMESPACE
+ * osgi.wiring.package} name space.
+ * </ul>
+ * All other directives have no specified semantics and are considered extra
+ * user defined information. The OSGi Alliance reserves the right to extend
+ * the set of directives which have specified semantics.
+ *
+ * @return An unmodifiable map of directive names to directive values for
+ * this capability, or an empty map if this capability has no
+ * directives.
+ */
+ Map<String, String> getDirectives();
+
+ /**
+ * Returns the attributes of this capability.
+ *
+ * @return An unmodifiable map of attribute names to attribute values for
+ * this capability, or an empty map if this capability has no
+ * attributes.
+ */
+ Map<String, Object> getAttributes();
+
+ /**
+ * Returns the resource declaring this capability.
+ *
+ * @return The resource declaring this capability.
+ */
+ Resource getResource();
+}
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Requirement.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Requirement.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Requirement.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Requirement.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.resource;
+
+import java.util.Map;
+
+import org.osgi.framework.Constants;
+
+/**
+ * A requirement that has been declared from a {@link Resource} .
+ *
+ * @ThreadSafe
+ * @version $Id: 46f600c32e563cfe617fb94ab4e308f5be2b9217 $
+ */
+public interface Requirement {
+ /**
+ * Returns the name space of this requirement.
+ *
+ * @return The name space of this requirement.
+ */
+ String getNamespace();
+
+ /**
+ * Returns the directives of this requirement.
+ *
+ * <p>
+ * Only the following list of directives have specified semantics:
+ * <ul>
+ * <li> {@link ResourceConstants#REQUIREMENT_EFFECTIVE_DIRECTIVE effective}
+ * <li> {@link ResourceConstants#REQUIREMENT_FILTER_DIRECTIVE filter}
+ * <li> {@link ResourceConstants#REQUIREMENT_CARDINALITY_DIRECTIVE
+ * cardinality}
+ * <li> {@link ResourceConstants#REQUIREMENT_RESOLUTION_DIRECTIVE resolution}
+ * <li> {@link ResourceConstants#REQUIREMENT_VISIBILITY_DIRECTIVE visibility}
+ * - only recognized for the
+ * {@link ResourceConstants#WIRING_BUNDLE_NAMESPACE osgi.wiring.bundle} name
+ * space.
+ * </ul>
+ * All other directives have no specified semantics and are considered extra
+ * user defined information. The OSGi Alliance reserves the right to extend
+ * the set of directives which have specified semantics.
+ *
+ * @return An unmodifiable map of directive names to directive values for
+ * this requirement, or an empty map if this requirement has no
+ * directives.
+ */
+ Map<String, String> getDirectives();
+
+ /**
+ * Returns the attributes of this requirement.
+ *
+ * <p>
+ * Requirement attributes have no specified semantics and are considered
+ * extra user defined information.
+ *
+ * @return An unmodifiable map of attribute names to attribute values for
+ * this requirement, or an empty map if this requirement has no
+ * attributes.
+ */
+ Map<String, Object> getAttributes();
+
+ /**
+ * Returns the resource declaring this requirement.
+ *
+ * @return The resource declaring this requirement.
+ */
+ Resource getResource();
+
+ /**
+ * Returns whether the specified capability matches this requirement.
+ *
+ * <p>
+ * A capability matches this requirement when all of the following are true:
+ * <ul>
+ * <li>The specified capability has the same {@link #getNamespace() name
+ * space} as this requirement.
+ * <li>The filter specified by the {@link Constants#FILTER_DIRECTIVE filter}
+ * directive of this requirement matches the
+ * {@link Capability#getAttributes() attributes of the specified capability}.
+ * <li>The standard capability {@link Capability#getDirectives() directives}
+ * that influence matching and that apply to the name space are satisfied.
+ * See the capability
+ * {@link ResourceConstants#CAPABILITY_MANDATORY_DIRECTIVE mandatory}
+ * directive.
+ * </ul>
+ *
+ * @param capability The capability to match to this requirement.
+ * @return {@code true} if the specified capability matches this this
+ * requirement; {@code false} otherwise.
+ */
+ boolean matches(Capability capability);
+}
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Resource.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Resource.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Resource.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Resource.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.resource;
+
+import java.util.List;
+
+
+/**
+ * A resource is the representation of a uniquely identified and typed data.
+ *
+ * A resources can be wired together via capabilities and requirements.
+ *
+ * @ThreadSafe
+ * @version $Id: 56916cb2597067bdf63e757c078787eccebf3953 $
+ */
+public interface Resource {
+ /**
+ * Returns the capabilities declared by this resource.
+ *
+ * @param namespace
+ * The name space of the declared capabilities to return or
+ * {@code null} to return the declared capabilities from all name
+ * spaces.
+ * @return A list containing a snapshot of the declared {@link Capability}s,
+ * or an empty list if this resource declares no capabilities in the
+ * specified name space.
+ */
+ List<Capability> getCapabilities(String namespace);
+
+ /**
+ * Returns the requirements declared by this bundle resource.
+ *
+ * @param namespace
+ * The name space of the declared requirements to return or
+ * {@code null} to return the declared requirements from all name
+ * spaces.
+ * @return A list containing a snapshot of the declared {@link Requirement}
+ * s, or an empty list if this resource declares no requirements in
+ * the specified name space.
+ */
+ List<Requirement> getRequirements(String namespace);
+}
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/ResourceConstants.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/ResourceConstants.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/ResourceConstants.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/ResourceConstants.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,377 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.resource;
+
+import org.osgi.framework.Constants;
+import org.osgi.framework.Version;
+import org.osgi.framework.wiring.BundleRevision;
+import org.osgi.framework.wiring.BundleWiring;
+
+/**
+ * Defines standard names for the attributes, directives and name spaces for
+ * resources, capabilities and requirements.
+ *
+ * <p>
+ * The values associated with these keys are of type {@code String}, unless
+ * otherwise indicated.
+ *
+ * @Immutable
+ * @version $Id: ab8d42db8d410c81bccb93effa990bed1f4414df $
+ */
+public final class ResourceConstants {
+
+ private ResourceConstants() {
+ // keep others from creating objects of this type.
+ }
+
+ /**
+ * Name space for the identity capability. Each {@link Resource resource}
+ * provides exactly one<sup>†</sup> identity capability that can be
+ * used to identify the resource.
+ *
+ * For identity capability attributes the following applies:
+ * <ul>
+ * <li>The
+ * <q>osgi.identity</q> attribute contains the symbolic name of the
+ * resource.
+ * <li>The {@link #IDENTITY_VERSION_ATTRIBUTE version} attribute contains
+ * the {@link Version} of the resource.
+ * <li>The {@link #IDENTITY_TYPE_ATTRIBUTE type} attribute contains the
+ * resource type.
+ * </ul>
+ * <p>
+ * A resource with a symbolic name
+ * {@link Resource#getCapabilities(String) provides} exactly one
+ * <sup>†</sup> identity
+ * {@link Resource#getCapabilities(String) capability}.
+ * <p>
+ * For a {@link BundleRevision revision} with a symbolic name the
+ * {@link BundleWiring wiring} for the revision
+ * {@link BundleWiring#getCapabilities(String) provides} exactly
+ * one<sup>†</sup> identity capability.
+ * <p>
+ * † A resource with no symbolic name must not provide an identity
+ * capability.
+ */
+ public static final String IDENTITY_NAMESPACE = "osgi.identity";
+
+ /**
+ * An {@link #IDENTITY_NAMESPACE identity} capability attribute identifying the
+ * {@link Version version} of the resource. This attribute must be set to a value of
+ * type {@link Version}. If the resource has no version then the value
+ * {@link Version#emptyVersion 0.0.0} must be used for the attribute.
+ */
+ public static final String IDENTITY_VERSION_ATTRIBUTE = Constants.VERSION_ATTRIBUTE;
+
+ /**
+ * An {@link #IDENTITY_NAMESPACE identity} capability attribute identifying the
+ * resource type. This attribute must be set to a value of type {@link String}.
+ * if the resource has no type then the value
+ * {@link ResourceConstants#IDENTITY_TYPE_UNKNOWN unknown} must be used for the
+ * attribute.
+ */
+ public static final String IDENTITY_TYPE_ATTRIBUTE = "type";
+
+ /**
+ * An {@link #IDENTITY_NAMESPACE identity} capability {@link #IDENTITY_TYPE_ATTRIBUTE type}
+ * attribute value identifying the resource type as an OSGi bundle.
+ */
+ public static final String IDENTITY_TYPE_BUNDLE = "osgi.bundle";
+
+ /**
+ * An {@link #IDENTITY_NAMESPACE identity} capability {@link #IDENTITY_TYPE_ATTRIBUTE type}
+ * attribute value identifying the resource type as an OSGi fragment.
+ */
+ public static final String IDENTITY_TYPE_FRAGMENT = "osgi.fragment";
+
+ /**
+ * An {@link #IDENTITY_NAMESPACE identity} capability {@link #IDENTITY_TYPE_ATTRIBUTE type}
+ * attribute value identifying the resource type as unknown.
+ */
+ public static final String IDENTITY_TYPE_UNKNOWN = "unknown";
+
+ /**
+ * An {@link #IDENTITY_NAMESPACE identity} capability {@link Requirement#getDirectives() directive}
+ * identifying if the resource is a singleton. A {@link String} value of "true" indicates
+ * the resource is a singleton; any other value or <code>null</code> indicates the resource is not a
+ * singleton.
+ */
+ public static final String IDENTITY_SINGLETON_DIRECTIVE = Constants.SINGLETON_DIRECTIVE;
+
+ /**
+ * Name space for package capabilities and requirements.
+ *
+ * For capability attributes the following applies:
+ * <ul>
+ * <li>The
+ * <q>osgi.wiring.package</q> attribute contains the name of the package.
+ * <li>The {@link Constants#VERSION_ATTRIBUTE version} attribute contains
+ * the the {@link Version} of the package if one is specified or
+ * {@link Version#emptyVersion} if not specified.
+ * <li>The {@link Constants#BUNDLE_SYMBOLICNAME_ATTRIBUTE
+ * bundle-symbolic-name} attribute contains the symbolic name of the
+ * resource providing the package if one is specified.
+ * <li>The {@link Constants#BUNDLE_VERSION_ATTRIBUTE bundle-version}
+ * attribute contains the {@link Version} of resource providing the package
+ * if one is specified or {@link Version#emptyVersion} if not specified.
+ * <li>All other attributes are of type {@link String} and are used as
+ * arbitrary matching attributes for the capability.
+ * </ul>
+ * <p>
+ * A resource provides zero or more package
+ * {@link Resource#getCapabilities(String) capabilities} (this is, exported
+ * packages) and requires zero or more package
+ * {@link Resource#getRequirements(String) requirements} (that is, imported
+ * packages).
+ */
+ public static final String WIRING_PACKAGE_NAMESPACE = "osgi.wiring.package";
+
+ /**
+ * Name space for bundle capabilities and requirements.
+ *
+ * For capability attributes the following applies:
+ * <ul>
+ * <li>The
+ * <q>osgi.wiring.bundle</q> attribute contains the symbolic name of the
+ * bundle.
+ * <li>The {@link Constants#BUNDLE_VERSION_ATTRIBUTE bundle-version}
+ * attribute contains the {@link Version} of the bundle if one is specified
+ * or {@link Version#emptyVersion} if not specified.
+ * <li>All other attributes are of type {@link String} and are used as
+ * arbitrary matching attributes for the capability.
+ * </ul>
+ * <p>
+ * A non-fragment resource with the {@link #IDENTITY_TYPE_BUNDLE
+ * osgi.bundle} type {@link #IDENTITY_TYPE_ATTRIBUTE identity} provides
+ * exactly one <sup>†</sup> bundle
+ * {@link Resource#getCapabilities(String) capability} (that is, the bundle
+ * can be required by another bundle). A fragment resource with the
+ * {@link #IDENTITY_TYPE_FRAGMENT osgi.fragment} type
+ * {@link #IDENTITY_TYPE_ATTRIBUTE identity} must not declare
+ * a bundle capability. A resource requires zero or more bundle
+ * {@link Resource#getRequirements(String) requirements} (that is, required
+ * bundles).
+ * <p>
+ * † A resource with no symbolic name must not provide a bundle
+ * capability.
+ */
+ public static final String WIRING_BUNDLE_NAMESPACE = "osgi.wiring.bundle";
+
+ /**
+ * Name space for host capabilities and requirements.
+ *
+ * For capability attributes the following applies:
+ * <ul>
+ * <li>The
+ * <q>osgi.wiring.host</q> attribute contains the symbolic name of the
+ * bundle.
+ * <li>The {@link Constants#BUNDLE_VERSION_ATTRIBUTE bundle-version}
+ * attribute contains the {@link Version} of the bundle if one is specified
+ * or {@link Version#emptyVersion} if not specified.
+ * <li>All other attributes are of type {@link String} and are used as
+ * arbitrary matching attributes for the capability.
+ * </ul>
+ * <p>
+ * <p>
+ * A non-fragment resource with the with the {@link #IDENTITY_TYPE_BUNDLE
+ * osgi.bundle} type {@link #IDENTITY_TYPE_ATTRIBUTE identity} provides
+ * zero or one <sup>†</sup> host
+ * {@link Resource#getCapabilities(String) capabilities}.
+ * A fragment resource with the
+ * {@link #IDENTITY_TYPE_FRAGMENT osgi.fragment} type
+ * {@link #IDENTITY_TYPE_ATTRIBUTE identity} must not declare
+ * a host capability and must
+ * {@link Resource#getRequirements(String) declare} exactly one host
+ * requirement.
+ * <p>
+ * † A resource with no bundle symbolic name must not provide a host
+ * capability.
+ */
+ public static final String WIRING_HOST_NAMESPACE = "osgi.wiring.host";
+
+ /**
+ * A requirement {@link Requirement#getDirectives() directive} used to
+ * specify a capability filter. This filter is used to match against a
+ * capability's {@link Capability#getAttributes() attributes}.
+ */
+ public final static String REQUIREMENT_FILTER_DIRECTIVE = Constants.FILTER_DIRECTIVE;
+
+ /**
+ * A requirement {@link Requirement#getDirectives() directive} used to
+ * specify the resolution type for a requirement. The default value is
+ * {@link #REQUIREMENT_RESOLUTION_MANDATORY mandatory}.
+ *
+ * @see #REQUIREMENT_RESOLUTION_MANDATORY mandatory
+ * @see #REQUIREMENT_RESOLUTION_OPTIONAL optional
+ */
+ public final static String REQUIREMENT_RESOLUTION_DIRECTIVE = Constants.RESOLUTION_DIRECTIVE;
+ /**
+ * A directive value identifying a mandatory
+ * {@link Resource#getRequirements(String) requirement} resolution type. A
+ * mandatory resolution type indicates that the requirement must be resolved
+ * when the {@link Resource resource} is resolved. If such requirement
+ * cannot be resolved, the resource fails to resolve.
+ *
+ * @see #REQUIREMENT_RESOLUTION_DIRECTIVE
+ */
+ public final static String REQUIREMENT_RESOLUTION_MANDATORY = Constants.RESOLUTION_MANDATORY;
+
+ /**
+ * A directive value identifying an optional
+ * {@link Resource#getRequirements(String) requirement} resolution type. An
+ * optional resolution type indicates that the requirement is optional and
+ * the {@link Resource resource} may be resolved without requirement being
+ * resolved.
+ *
+ * @see #REQUIREMENT_RESOLUTION_DIRECTIVE
+ */
+ public final static String REQUIREMENT_RESOLUTION_OPTIONAL = Constants.RESOLUTION_OPTIONAL;
+
+ /**
+ * A requirement {@link Requirement#getDirectives() directive} used to
+ * specify the effective time for the requirement. The default value is
+ * {@link #EFFECTIVE_RESOLVE resolve}.
+ *
+ * @see #EFFECTIVE_RESOLVE resolve
+ * @see #EFFECTIVE_ACTIVE active
+ */
+ public final static String REQUIREMENT_EFFECTIVE_DIRECTIVE = Constants.EFFECTIVE_DIRECTIVE;
+
+ /**
+ * A directive value identifying a {@link #CAPABILITY_EFFECTIVE_DIRECTIVE
+ * capability} or {@link #REQUIREMENT_EFFECTIVE_DIRECTIVE requirement} that
+ * is effective at resolve time. Capabilities and requirements with an
+ * effective time of resolve are the only capabilities which are processed
+ * while resolving a resource.
+ *
+ * @see #REQUIREMENT_EFFECTIVE_DIRECTIVE
+ * @see #CAPABILITY_EFFECTIVE_DIRECTIVE
+ */
+ public final static String EFFECTIVE_RESOLVE = Constants.EFFECTIVE_RESOLVE;
+
+ /**
+ * A directive value identifying a {@link #CAPABILITY_EFFECTIVE_DIRECTIVE
+ * capability} or {@link #REQUIREMENT_EFFECTIVE_DIRECTIVE requirement} that
+ * is effective at active time. Capabilities and requirements with an
+ * effective time of active are ignored while resolving a resource.
+ *
+ * @see #REQUIREMENT_EFFECTIVE_DIRECTIVE
+ * @see #CAPABILITY_EFFECTIVE_DIRECTIVE
+ */
+ public final static String EFFECTIVE_ACTIVE = Constants.EFFECTIVE_ACTIVE;
+
+ /**
+ * A requirement {@link Requirement#getDirectives() directive} used to
+ * specify the visibility type for a requirement. The default value is
+ * {@link #REQUIREMENT_VISIBILITY_PRIVATE private}. This directive must only
+ * be used for requirements with the require
+ * {@link #WIRING_BUNDLE_NAMESPACE bundle} name space.
+ *
+ * @see #REQUIREMENT_VISIBILITY_PRIVATE private
+ * @see #REQUIREMENT_VISIBILITY_REEXPORT reexport
+ */
+ public final static String REQUIREMENT_VISIBILITY_DIRECTIVE = Constants.VISIBILITY_DIRECTIVE;
+
+ /**
+ * A directive value identifying a private
+ * {@link #REQUIREMENT_VISIBILITY_DIRECTIVE visibility} type. A private
+ * visibility type indicates that any {@link #WIRING_PACKAGE_NAMESPACE
+ * packages} that are exported by the required
+ * {@link #WIRING_BUNDLE_NAMESPACE bundle} are not made visible on the
+ * export signature of the requiring {@link #WIRING_BUNDLE_NAMESPACE bundle}
+ * .
+ *
+ * @see #REQUIREMENT_VISIBILITY_DIRECTIVE
+ */
+ public final static String REQUIREMENT_VISIBILITY_PRIVATE = Constants.VISIBILITY_PRIVATE;
+
+ /**
+ * A directive value identifying a reexport
+ * {@link #REQUIREMENT_VISIBILITY_DIRECTIVE visibility} type. A reexport
+ * visibility type indicates any {@link #WIRING_PACKAGE_NAMESPACE packages}
+ * that are exported by the required {@link #WIRING_BUNDLE_NAMESPACE bundle}
+ * are re-exported by the requiring {@link #WIRING_BUNDLE_NAMESPACE bundle}.
+ */
+ public final static String REQUIREMENT_VISIBILITY_REEXPORT = Constants.VISIBILITY_REEXPORT;
+
+ /**
+ * A requirement {@link Requirement#getDirectives() directive} used to
+ * specify the cardinality for a requirement. The default value is
+ * {@link #REQUIREMENT_CARDINALITY_SINGULAR singular}.
+ *
+ * @see #REQUIREMENT_CARDINALITY_MULTIPLE multiple
+ * @see #REQUIREMENT_CARDINALITY_SINGULAR singular
+ */
+ public final static String REQUIREMENT_CARDINALITY_DIRECTIVE = "cardinality";
+
+ /**
+ * A directive value identifying a multiple
+ * {@link #REQUIREMENT_CARDINALITY_DIRECTIVE cardinality} type.
+ */
+ public final static String REQUIREMENT_CARDINALITY_MULTIPLE = "multiple";
+
+ /**
+ * A directive value identifying a singular
+ * {@link #REQUIREMENT_CARDINALITY_DIRECTIVE cardinality} type.
+ */
+ public final static String REQUIREMENT_CARDINALITY_SINGULAR = "singular";
+
+
+ /**
+ * A capability {@link Capability#getDirectives() directive} used to specify
+ * the comma separated list of {@link #WIRING_PACKAGE_NAMESPACE package}
+ * names a capability uses.
+ */
+ public final static String CAPABILITY_USES_DIRECTIVE = Constants.USES_DIRECTIVE;
+
+ /**
+ * A capability {@link Capability#getDirectives() directive} used to specify
+ * the effective time for the capability. The default value is
+ * {@link #EFFECTIVE_RESOLVE resolve}.
+ *
+ * @see #EFFECTIVE_RESOLVE resolve
+ * @see #EFFECTIVE_ACTIVE active
+ */
+ public final static String CAPABILITY_EFFECTIVE_DIRECTIVE = Constants.EFFECTIVE_DIRECTIVE;
+
+ /**
+ * A capability {@link Capability#getDirectives() directive} used to specify
+ * the comma separated list of mandatory attributes which must be specified
+ * in the {@link #REQUIREMENT_FILTER_DIRECTIVE filter} of a requirement in
+ * order for the capability to match the requirement. This directive must
+ * only be used for capabilities with the {@link #WIRING_PACKAGE_NAMESPACE
+ * package}, {@link #WIRING_BUNDLE_NAMESPACE bundle}, or
+ * {@link #WIRING_HOST_NAMESPACE host} name space.
+ */
+ public final static String CAPABILITY_MANDATORY_DIRECTIVE = "mandatory";
+
+ /**
+ * A capability {@link Capability#getDirectives() directive} used to specify
+ * the comma separated list of classes which must be allowed to be exported.
+ * This directive must only be used for capabilities with the
+ * {@link #WIRING_PACKAGE_NAMESPACE package} name space.
+ */
+ public final static String CAPABILITY_INCLUDE_DIRECTIVE = "include";
+
+ /**
+ * A capability {@link Capability#getDirectives() directive} used to specify
+ * the comma separated list of classes which must not be allowed to be
+ * exported. This directive must only be used for capabilities with the
+ * {@link #WIRING_PACKAGE_NAMESPACE package} name space.
+ */
+ public final static String CAPABILITY_EXCLUDE_DIRECTIVE = "exclude";
+}
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Wire.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Wire.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Wire.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Wire.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.resource;
+
+/**
+ * A wire connecting a {@link Capability} to a {@link Requirement}.
+ *
+ * @ThreadSafe
+ * @version $Id: c099368f7ee5b4c485e58dbc512c9c458e5fa03c $
+ */
+public interface Wire {
+ /**
+ * Returns the {@link Capability} for this wire.
+ *
+ * @return The {@link Capability} for this wire.
+ */
+ Capability getCapability();
+
+ /**
+ * Return the {@link Requirement} for this wire.
+ *
+ * @return The {@link Requirement} for this wire.
+ */
+ Requirement getRequirement();
+
+ /**
+ * Returns the wiring {@link Wiring#getProvidedResourceWires(String)
+ * providing} the {@link #getCapability() capability}.
+ *
+ * <p>
+ * The resource referenced by the returned wiring may differ from the
+ * resource referenced by the {@link #getCapability() capability}.
+ *
+ * @return The wiring providing the capability.
+ */
+ Wiring getProviderWiring();
+
+ /**
+ * Returns the wiring who {@link Wiring#getRequiredResourceWires(String)
+ * requires} the {@link #getCapability() capability}.
+ *
+ * <p>
+ * The resource referenced by the returned wiring may differ from the
+ * resource referenced by the {@link #getRequirement() requirement}.
+ *
+ * @return The wiring whose requirement is wired to the capability.
+ */
+ Wiring getRequirerWiring();
+}
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Wiring.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Wiring.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Wiring.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/Wiring.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.resource;
+
+import java.util.List;
+
+/**
+ * A wiring for a resource. A wiring is associated with a resource and
+ * represents the dependencies with other wirings.
+ *
+ * @ThreadSafe
+ * @version $Id: 1dcd04f839191a84860d83b62124d2c35c433f08 $
+ */
+public interface Wiring {
+ /**
+ * Returns the capabilities provided by this wiring.
+ *
+ * <p>
+ * Only capabilities considered by the resolver are returned. For example,
+ * capabilities with
+ * {@link ResourceConstants#CAPABILITY_EFFECTIVE_DIRECTIVE effective}
+ * directive not equal to {@link ResourceConstants#EFFECTIVE_RESOLVE
+ * resolve} are not returned.
+ *
+ * <p>
+ * A capability may not be required by any wiring and thus there may be no
+ * {@link #getProvidedResourceWires(String) wires} for the capability.
+ *
+ * <p>
+ * A wiring for a non-fragment resource provides a subset of the declared
+ * capabilities from the resource and all attached fragment
+ * resources<sup>†</sup>. Not all declared capabilities may be
+ * provided since some may be discarded. For example, if a package is
+ * declared to be both exported and imported, only one is selected and the
+ * other is discarded.
+ * <p>
+ * A wiring for a fragment resource with a symbolic name must provide
+ * exactly one {@link ResourceConstants#IDENTITY_NAMESPACE identity}
+ * capability.
+ * <p>
+ * † The {@link ResourceConstants#IDENTITY_NAMESPACE identity}
+ * capability provided by attached fragment resource must not be included in
+ * the capabilities of the host wiring.
+ *
+ * @param namespace The name space of the capabilities to return or
+ * {@code null} to return the capabilities from all name spaces.
+ * @return A list containing a snapshot of the {@link Capability}s, or an
+ * empty list if this wiring provides no capabilities in the
+ * specified name space. For a given name space, the list contains
+ * the wires in the order the capabilities were specified in the
+ * manifests of the {@link #getResource() resource} and the attached
+ * fragment resources<sup>†</sup> of this wiring. There is no
+ * ordering defined between capabilities in different name spaces.
+ */
+ List<Capability> getResourceCapabilities(String namespace);
+
+ /**
+ * Returns the requirements of this wiring.
+ *
+ * <p>
+ * Only requirements considered by the resolver are returned. For example,
+ * requirements with
+ * {@link ResourceConstants#REQUIREMENT_EFFECTIVE_DIRECTIVE effective}
+ * directive not equal to {@link ResourceConstants#EFFECTIVE_RESOLVE
+ * resolve} are not returned.
+ *
+ * <p>
+ * A wiring for a non-fragment resource has a subset of the declared
+ * requirements from the resource and all attached fragment resources. Not
+ * all declared requirements may be present since some may be discarded. For
+ * example, if a package is declared to be optionally imported and is not
+ * actually imported, the requirement must be discarded.
+ *
+ * @param namespace The name space of the requirements to return or
+ * {@code null} to return the requirements from all name spaces.
+ * @return A list containing a snapshot of the {@link Requirement}s, or an
+ * empty list if this wiring uses no requirements in the specified
+ * name space. For a given name space, the list contains the wires
+ * in the order the requirements were specified in the manifests of
+ * the {@link #getResource() resource} and the attached fragment
+ * resources of this wiring. There is no ordering defined between
+ * requirements in different name spaces.
+ */
+ List<Requirement> getResourceRequirements(String namespace);
+
+ /**
+ * Returns the {@link Wire}s to the provided {@link Capability capabilities}
+ * of this wiring.
+ *
+ * @param namespace The name space of the capabilities for which to return
+ * wires or {@code null} to return the wires for the capabilities in
+ * all name spaces.
+ * @return A list containing a snapshot of the {@link Wire}s for the
+ * {@link Capability capabilities} of this wiring, or an empty list
+ * if this wiring has no capabilities in the specified name space.
+ * For a given name space, the list contains the wires in the order
+ * the capabilities were specified in the manifests of the
+ * {@link #getResource() resource} and the attached fragment
+ * resources of this wiring. There is no ordering defined between
+ * capabilities in different name spaces.
+ */
+ List<Wire> getProvidedResourceWires(String namespace);
+
+ /**
+ * Returns the {@link Wire}s to the {@link Requirement requirements} in use
+ * by this wiring.
+ *
+ * @param namespace The name space of the requirements for which to return
+ * wires or {@code null} to return the wires for the requirements in
+ * all name spaces.
+ * @return A list containing a snapshot of the {@link Wire}s for the
+ * {@link Requirement requirements} of this wiring, or an empty list
+ * if this wiring has no requirements in the specified name space.
+ * For a given name space, the list contains the wires in the order
+ * the requirements were specified in the manifests of the
+ * {@link #getResource() resource} and the attached fragment
+ * resources of this wiring. There is no ordering defined between
+ * requirements in different name spaces.
+ */
+ List<Wire> getRequiredResourceWires(String namespace);
+
+ /**
+ * Returns the resource associated with this wiring.
+ *
+ * @return The resource associated with this wiring.
+ */
+ Resource getResource();
+}
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/package-info.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/package-info.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/package-info.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/package-info.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.
+ */
+
+/**
+ * Framework Resource 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. For example:
+ *
+ * <pre>
+ * Import-Package: org.osgi.framework.resource; version="[1.0,2.0)"
+ * </pre>
+ *
+ * @version $Id: 3f1e95368b88d2ecbee46b1b9bc0b32754fe74bc $
+ */
+package org.osgi.framework.resource;
+
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/packageinfo
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/packageinfo?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/packageinfo (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/framework/resource/packageinfo Thu Oct 20 20:54:18 2011
@@ -0,0 +1 @@
+version 1.0
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/Environment.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/Environment.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/Environment.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/Environment.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.Map;
+import java.util.SortedSet;
+import org.osgi.framework.resource.Capability;
+import org.osgi.framework.resource.Requirement;
+import org.osgi.framework.resource.Resource;
+import org.osgi.framework.resource.Wire;
+import org.osgi.framework.resource.Wiring;
+
+/**
+ * An environment provides options and constraints to the potential solution of
+ * a {@link Resolver#resolve(Environment, Collection, Collection)} operation.
+ *
+ * <p>
+ * Environments:
+ * <ul>
+ * <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 #getWiring()} method. A wiring
+ * consists of a map of existing {@link Resource resources} to {@link Wire
+ * wires}.
+ *
+ * <li>Filter transitive requirements that are brought in as part of a resolve
+ * operation via the {@link #isEffective(Requirement)}.
+ * </ul>
+ *
+ * <p>
+ * An environment may be used to provide capabilities via local {@link Resource
+ * resources} and/or remote {@link org.osgi.service.repository.Repository repositories}.
+ *
+ * <p>
+ * A resolver may call the {@link #findProviders(Requirement)},
+ * {@link #isEffective(Requirement)} and {@link #getWiring()} method any number of
+ * times during a resolve using any thread. Environments may also be shared
+ * between several resolvers. As such implementors should ensure that this class
+ * is properly synchronized.
+ *
+ * @ThreadSafe
+ */
+public interface Environment {
+ /**
+ * Find any capabilities that {@link Requirement#matches(Capability) match}
+ * the supplied requirement.
+ *
+ * <p>
+ * A resolver should use the iteration order or the returned capability
+ * collection to infer preference in the case where multiple capabilities
+ * match a requirement. Capabilities at the start of the iteration are implied
+ * to be preferred over capabilities at the end.
+ *
+ * @param requirement
+ * the requirement that a resolver is attempting to satisfy
+ *
+ * @return an collection of capabilities that match the supplied
+ * requirement
+ *
+ * @throws NullPointerException if the requirement is null
+ */
+ SortedSet<Capability> findProviders(Requirement requirement);
+
+ /**
+ * Test if a given requirement should be wired in a given resolve
+ * operation. If this method returns false then the resolver should ignore
+ * this requirement during this resolve operation.
+ *
+ * <p>
+ * The primary use case for this is to test the <code>effective</code> directive
+ * on the requirement, though implementations are free to use this for any other
+ * purposes.
+ *
+ * @param requirement the Requirement to test
+ *
+ * @return true if the requirement should be considered as part of this resolve operation
+ *
+ * @throws NullPointerException if requirement is null
+ */
+ boolean isEffective(Requirement requirement);
+
+ /**
+ * An immutable map of wires between revisions. Multiple calls to this method
+ * for the same environment object must result in the same set of wires.
+ *
+ * @return the wires already defined in this environment
+ */
+ Map<Resource, Wiring> getWirings();
+}
\ No newline at end of file
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/ResolutionException.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/ResolutionException.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/ResolutionException.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/ResolutionException.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). 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.framework.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 subclass this class to provide extra state
+ * information about the reason for the resolution failure.
+ *
+ * @ThreadSafe
+ * @Immutable
+ */
+public class ResolutionException extends RuntimeException {
+
+ private static final long serialVersionUID = 1L;
+
+ // NOTE used requirement[] not collection to avoid accidental serialization
+ // issues
+ private Requirement[] unresolvedRequirements;
+
+ /**
+ * Creates an exception of type {@code ResolutionException}.
+ *
+ * <p>
+ * This method creates an {@code ResolutionException} object with the
+ * specified message, cause and unresolvedRequirements.
+ *
+ * @param message
+ * The message.
+ * @param cause
+ * The cause of this exception.
+ * @param unresolvedRequirements
+ * the requirements that are unresolved or null if no unresolved requirements
+ * information is provided.
+ */
+ public ResolutionException(String message, Throwable cause,
+ Collection<Requirement> unresolvedRequirements) {
+ super(message, cause);
+ if (unresolvedRequirements != null) {
+ // copy array both fixes serialization issues and
+ // ensures exception is immutable
+ this.unresolvedRequirements = unresolvedRequirements
+ .toArray(new Requirement[unresolvedRequirements.size()]);
+ }
+ }
+
+ /**
+ * Creates an exception of type {@code ResolutionException}.
+ *
+ * <p>
+ * This method creates an {@code ResolutionException} object with the
+ * specified message.
+ *
+ * @param message
+ * The message.
+ */
+ public ResolutionException(String message) {
+ super(message);
+ }
+
+ /**
+ * Creates an exception of type {@code ResolutionException}.
+ *
+ * <p>
+ * This method creates an {@code ResolutionException} object with the
+ * specified cause.
+ *
+ * @param cause
+ * The cause of this exception.
+ */
+ public ResolutionException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * May contain one or more unresolved mandatory requirements from mandatory
+ * resources.
+ *
+ * <p>
+ * This exception is provided for informational purposes and the specific set
+ * of requirements that are returned after a resolve failure is not defined.
+ *
+ * @return a collection of requirements that are unsatisfied
+ */
+ public Collection<Requirement> getUnresolvedRequirements() {
+ // creating at each call ensures internal data is immutable
+ // TODO could use a transient field to reduce CPU cost at expense of RAM -
+ // both trivial compared to code complexity
+ if (unresolvedRequirements == null) {
+ return Collections.EMPTY_LIST;
+ } else {
+ ArrayList<Requirement> requirements = new ArrayList<Requirement>(
+ unresolvedRequirements.length);
+ for (Requirement r : unresolvedRequirements) {
+ requirements.add(r);
+ }
+ return requirements;
+ }
+ }
+}
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/Resolver.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/Resolver.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/Resolver.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/Resolver.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) OSGi Alliance (2006, 2010). 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.Collection;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.felix.resolver.FelixEnvironment;
+import org.osgi.framework.resource.Resource;
+import org.osgi.framework.resource.Wire;
+
+/**
+ * A resolver is a service interface that can be used to find resolutions for
+ * specified {@link Resource resources} based on a supplied {@link Environment}.
+ *
+ * @ThreadSafe
+ * @version $Id: 5735a30be6494040afe5a05cadf353cf0ce943a0 $
+ */
+public interface Resolver {
+ /**
+ * Attempt to resolve the resources based on the specified environment 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 mandatory group must be resolved, a
+ * failure to satisfy any mandatory requirement for these resources will
+ * result in a {@link ResolutionException}</li>
+ * <li>Optional - any resource in the 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 this resource.</li>
+ * </ul>
+ *
+ * <h3>Delta</h3>
+ * <p>
+ * The resolve method returns the delta between the start state defined by
+ * {@link Environment#getWiring()} and the end resolved state, i.e. only new
+ * resources and wires are included. To get the complete resolution the caller
+ * can merge the start state and the delta using something like the following:
+ *
+ * <pre>
+ * Map<Resource, List<Wire>> delta = resolver.resolve(env, resources, null);
+ * Map<Resource, List<Wire>> wiring = env.getWiring();
+ *
+ * for (Map.Entry<Resource, List<Wire>> e : delta.entrySet()) {
+ * Resource res = e.getKey();
+ * List<Wire> newWires = e.getValue();
+ *
+ * List<Wire> currentWires = wiring.get(res);
+ * if (currentWires != null) {
+ * newWires.addAll(currentWires);
+ * }
+ *
+ * wiring.put(res, newWires);
+ * }
+ * </pre>
+ *
+ * <h3>Consistency</h3>
+ * <p>
+ * For a given resolve operation the parameters to the resolve method should be
+ * considered immutable. This means that resources should have constant
+ * capabilities and requirements and an environment should return a consistent
+ * set of capabilities, wires and effective requirements.
+ *
+ * <p>
+ * The behavior of the resolver is not defined if resources or the environment
+ * supply inconsistent information.
+ *
+ * @param environment
+ * the environment into which to resolve the requirements
+ * @param mandatoryResources
+ * The resources that must be resolved during this resolution step or
+ * null if no resources must be resolved
+ * @param optionalResources
+ * Any resources which the resolver should attempt to resolve but
+ * that will not cause an exception if resolution is impossible or
+ * null if no resources are optional.
+ *
+ * @return the new resources and wires required to satisfy the requirements
+ *
+ * @throws ResolutionException
+ * if the resolution cannot be satisfied for any reason
+ * @throws NullPointerException
+ * if environment is null
+ */
+ Map<Resource, List<Wire>> resolve(FelixEnvironment environment,
+ Collection<? extends Resource> mandatoryResources,
+ Collection<? extends Resource> optionalResources)
+ throws ResolutionException;
+}
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/package-info.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/package-info.java?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/package-info.java (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/package-info.java Thu Oct 20 20:54:18 2011
@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). 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 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: ffe26e5b960ebceb84699fd1cb8f211d9a386bf4 $
+ */
+
+package org.osgi.service.resolver;
\ No newline at end of file
Added: felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/packageinfo
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/packageinfo?rev=1187045&view=auto
==============================================================================
--- felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/packageinfo (added)
+++ felix/sandbox/rickhall/obr-resolver/src/main/java/org/osgi/service/resolver/packageinfo Thu Oct 20 20:54:18 2011
@@ -0,0 +1 @@
+version 1.0