felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rickh...@apache.org
Subject 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/...
Date Thu, 20 Oct 2011 20:54:20 GMT
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>&#8224;</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>&#8224;</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>&#8224;</sup> identity capability. 
+	 * <p>
+	 * &#8224; 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 &quot;true&quot; 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>&#8224;</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>
+	 * &#8224; 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>&#8224;</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>
+	 * &#8224; 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>&#8224;</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>
+	 * &#8224; 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>&#8224;</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=&quot;[1.0,2.0)&quot;
+ * </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&lt;Resource, List&lt;Wire&gt;&gt; delta = resolver.resolve(env, resources, null);
+   * Map&lt;Resource, List&lt;Wire&gt;&gt; wiring = env.getWiring();
+   *
+   * for (Map.Entry&lt;Resource, List&lt;Wire&gt;&gt; e : delta.entrySet()) {
+   *   Resource res = e.getKey();
+   *   List&lt;Wire&gt; newWires = e.getValue();
+   *
+   *   List&lt;Wire&gt; 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



Mime
View raw message