Bug 373161 - [R5] update OSGi constants, API and javadoc.

9 files changed, 222 insertions, 226 deletions

diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/Constants.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/Constants.java
index 817a7c125..60892d488 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/Constants.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/Constants.java
@@ -622,20 +622,6 @@ public interface Constants {
 	String	RESOLUTION_OPTIONAL						= "optional";
 
 	/**
-	 * Bundle wiring directive value identifying an dynamic resolution type. A
-	 * dynamic resolution type is used by requirements for
-	 * {@link #DYNAMICIMPORT_PACKAGE dynamically imported packages} in the
-	 * bundle wiring API.
-	 * 
-	 * <p>
-	 * This value cannot be used for the {@value #RESOLUTION_DIRECTIVE}
-	 * directive on a manifest header.
-	 * 
-	 * @since 1.7
-	 */
-	String	RESOLUTION_DYNAMIC						= "dynamic";
-
-	/**
 	 * Manifest header directive identifying a list of packages that an exported
 	 * package or provided capability uses.
 	 * 
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/VersionRange.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/VersionRange.java
index c3657c530..9baa9cf9c 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/VersionRange.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/VersionRange.java
@@ -355,6 +355,47 @@ public class VersionRange {
 	}
 
 	/**
+	 * Returns whether this version range contains only a single version.
+	 * 
+	 * @return {@code true} if this version range contains only a single
+	 *         version; {@code false} otherwise.
+	 */
+	public boolean isExact() {
+		if (empty || (right == null)) {
+			return false;
+		}
+		if (leftClosed) {
+			if (rightClosed) {
+				// [l,r]: exact if l == r
+				return left.equals(right);
+			}
+			else {
+				// [l,r): exact if l++ >= r
+				Version adjacent1 = new Version(left.getMajor(),
+						left.getMinor(), left.getMicro(), left.getQualifier()
+								+ "-");
+				return adjacent1.compareTo(right) >= 0;
+			}
+		}
+		else {
+			if (rightClosed) {
+				// (l,r] is equivalent to [l++,r]: exact if l++ == r
+				Version adjacent1 = new Version(left.getMajor(),
+						left.getMinor(), left.getMicro(), left.getQualifier()
+								+ "-");
+				return adjacent1.equals(right);
+			}
+			else {
+				// (l,r) is equivalent to [l++,r): exact if (l++)++ >=r
+				Version adjacent2 = new Version(left.getMajor(),
+						left.getMinor(), left.getMicro(), left.getQualifier()
+								+ "--");
+				return adjacent2.compareTo(right) >= 0;
+			}
+		}
+	}
+
+	/**
 	 * Returns the string representation of this version range.
 	 *
 	 * <p>
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/BundleNamespace.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/BundleNamespace.java
index 79a5a14a9..e16d0353e 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/BundleNamespace.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/BundleNamespace.java
@@ -27,16 +27,31 @@ import org.osgi.resource.Namespace;
  * and are used as arbitrary matching attributes for the capability. The values
  * associated with the specified directive and attribute keys are of type
  * {@code String}, unless otherwise indicated.
+ * 
  * <p>
- * For compatibility with previous versions of the specification all directives
- * specified on the {@code Bundle-SymbolicName} header are available to this
- * namespace. The directives {@link #CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE
- * fragment-attachment} and {@link #REQUIREMENT_EXTENSION_DIRECTIVE extension}
- * should be looked up using the {@link HostNamespace#HOST_NAMESPACE host}
- * namespace. The directive {@link #CAPABILITY_SINGLETON_DIRECTIVE singleton}
- * should be looked up using the {@link IdentityNamespace#IDENTITY_NAMESPACE
- * identity} namespace. Also, the {@link Namespace#CAPABILITY_USES_DIRECTIVE uses}
- * directive has no meaning to this namespace.
+ * Unless otherwise noted, all directives specified on the
+ * {@code Bundle-SymbolicName} header are visible in the capability and all
+ * directives specified on the {@code Require-Bundle} header are visible in the
+ * requirement.
+ * 
+ * <ul>
+ * <li>The {@link Namespace#CAPABILITY_USES_DIRECTIVE uses} directive must be
+ * ignored. A {@code uses} directive specified on the
+ * {@code Bundle-SymbolicName} header must be ignored. A {@code uses} directive
+ * must not be present in the capability.</li>
+ * <li>The {@link Namespace#CAPABILITY_EFFECTIVE_DIRECTIVE effective}
+ * {@link Namespace#REQUIREMENT_EFFECTIVE_DIRECTIVE directives} must be ignored.
+ * This namespace is only effective at {@link Namespace#EFFECTIVE_RESOLVE
+ * resolve} time. An {@code effective} directive specified on the
+ * {@code Bundle-SymbolicName} or {@code Require-Bundle} headers must be
+ * ignored. An {@code effective} directive must not be present in a capability
+ * or requirement.</li>
+ * <li>The {@link Namespace#REQUIREMENT_CARDINALITY_DIRECTIVE cardinality}
+ * directive must be ignored. A {@code cardinality} directive specified on the
+ * {@code Require-Bundle} header must be ignored. A {@code cardinality}
+ * directive must not be present in a requirement.</li>
+ * </ul>
+ * 
  * <p>
  * A non-fragment resource with the {@link IdentityNamespace#TYPE_BUNDLE
  * osgi.bundle} type {@link IdentityNamespace#CAPABILITY_TYPE_ATTRIBUTE
@@ -66,73 +81,41 @@ public final class BundleNamespace extends AbstractWiringNamespace {
 
 	/**
 	 * The capability directive identifying if the resource is a singleton. A
-	 * {@code 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	CAPABILITY_SINGLETON_DIRECTIVE	= "singleton";
-
-	/**
-	 * The capability directive identifying if and when a fragment may attach to
-	 * a host bundle. The default value is {@link #FRAGMENT_ATTACHMENT_ALWAYS
-	 * always}.
+	 * {@code String} value of &quot;{@code true}&quot; indicates the resource
+	 * is a singleton; any other value or <code>null</code> indicates the
+	 * resource is not a singleton.
 	 * 
-	 * @see #FRAGMENT_ATTACHMENT_ALWAYS
-	 * @see #FRAGMENT_ATTACHMENT_RESOLVETIME
-	 * @see #FRAGMENT_ATTACHMENT_NEVER
-	 */
-	public static final String	CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE	= "fragment-attachment";
-
-	/**
-	 * The directive value indicating that fragments are allowed to attach to
-	 * the host bundle at any time (while the host is resolved or during the
-	 * process of resolving the host bundle).
+	 * <p>
+	 * This directive should be examined using the {@link IdentityNamespace
+	 * identity} namespace.
 	 * 
-	 * @see #CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE
+	 * @see IdentityNamespace#CAPABILITY_SINGLETON_DIRECTIVE
 	 */
-	public static final String	FRAGMENT_ATTACHMENT_ALWAYS					= "always";
+	public static final String	CAPABILITY_SINGLETON_DIRECTIVE	= "singleton";
 
 	/**
-	 * The directive value indicating that fragments are allowed to attach to
-	 * the host bundle only during the process of resolving the host bundle.
+	 * The capability directive identifying if and when a fragment may attach to
+	 * a host bundle.
 	 * 
-	 * @see #CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE
-	 */
-	public static final String	FRAGMENT_ATTACHMENT_RESOLVETIME				= "resolve-time";
-
-	/**
-	 * The directive value indicating that no fragments are allowed to attach to
-	 * the host bundle at any time.
+	 * <p>
+	 * This directive should be examined using the {@link HostNamespace host}
+	 * namespace.
 	 * 
-	 * @see #CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE
+	 * @see HostNamespace#CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE
 	 */
-	public static final String	FRAGMENT_ATTACHMENT_NEVER					= "never";
+	public static final String	CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE	= "fragment-attachment";
 
 	/**
 	 * The requirement directive used to specify the type of the extension
 	 * fragment.
 	 * 
-	 * @see #EXTENSION_FRAMEWORK
-	 * @see #EXTENSION_BOOTCLASSPATH
-	 */
-	public final static String	REQUIREMENT_EXTENSION_DIRECTIVE				= "extension";
-
-	/**
-	 * The directive value indicating that the extension fragment is to be
-	 * loaded by the framework's class loader.
-	 * 
-	 * 
-	 * @see #REQUIREMENT_EXTENSION_DIRECTIVE
-	 */
-	public final static String	EXTENSION_FRAMEWORK							= "framework";
-
-	/**
-	 * The directive value indicating that the extension fragment is to be
-	 * loaded by the boot class loader.
+	 * <p>
+	 * This directive should be examined using the {@link HostNamespace host}
+	 * namespace.
 	 * 
-	 * @see #REQUIREMENT_EXTENSION_DIRECTIVE
+	 * @see HostNamespace#REQUIREMENT_EXTENSION_DIRECTIVE
 	 */
-	public final static String	EXTENSION_BOOTCLASSPATH						= "bootclasspath";
+	public final static String	REQUIREMENT_EXTENSION_DIRECTIVE				= "extension";
 
 	/**
 	 * The requirement directive used to specify the visibility type for a
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/ContractNamespace.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/ContractNamespace.java
deleted file mode 100644
index 485f581dc..000000000
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/ContractNamespace.java
+++ /dev/null
@@ -1,54 +0,0 @@
-/*
- * Copyright (c) OSGi Alliance (2012). All Rights Reserved.
- * 
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package org.osgi.framework.namespace;
-
-import org.osgi.resource.Namespace;
-
-/**
- * Contract Capability and Requirement Namespace.
- * 
- * <p>
- * This class defines the names for the attributes and directives for this
- * namespace. All unspecified capability attributes are of type {@code String}
- * and are used as arbitrary matching attributes for the capability. The values
- * associated with the specified directive and attribute keys are of type
- * {@code String}, unless otherwise indicated.
- * 
- * @Immutable
- * @version $Id$
- */
-public final class ContractNamespace extends Namespace {
-
-	/**
-	 * Namespace name for contract capabilities and requirements.
-	 * 
-	 * <p>
-	 * Also, the capability attribute used to specify the name of the contract.
-	 */
-	public static final String	CONTRACT_NAMESPACE				= "osgi.contract";
-
-	/**
-	 * The capability attribute contains the {@code Version} of the
-	 * specification of the contract. The value of this attribute must be of
-	 * type {@code Version}.
-	 */
-	public final static String	CAPABILITY_VERSION_ATTRIBUTE	= "version";
-
-	private ContractNamespace() {
-		// empty
-	}
-}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/ExtenderNamespace.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/ExtenderNamespace.java
deleted file mode 100644
index 2434f81e9..000000000
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/ExtenderNamespace.java
+++ /dev/null
@@ -1,54 +0,0 @@
-/*
- * Copyright (c) OSGi Alliance (2012). All Rights Reserved.
- * 
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package org.osgi.framework.namespace;
-
-import org.osgi.resource.Namespace;
-
-/**
- * Extender Capability and Requirement Namespace.
- * 
- * <p>
- * This class defines the names for the attributes and directives for this
- * namespace. All unspecified capability attributes are of type {@code String}
- * and are used as arbitrary matching attributes for the capability. The values
- * associated with the specified directive and attribute keys are of type
- * {@code String}, unless otherwise indicated.
- * 
- * @Immutable
- * @version $Id$
- */
-public final class ExtenderNamespace extends Namespace {
-
-	/**
-	 * Namespace name for extender capabilities and requirements.
-	 * 
-	 * <p>
-	 * Also, the capability attribute used to specify the name of the extender.
-	 */
-	public static final String	EXTENDER_NAMESPACE				= "osgi.extender";
-
-	/**
-	 * The capability attribute contains the {@code Version} of the
-	 * specification of the extender. The value of this attribute must be of
-	 * type {@code Version}.
-	 */
-	public final static String	CAPABILITY_VERSION_ATTRIBUTE	= "version";
-
-	private ExtenderNamespace() {
-		// empty
-	}
-}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/HostNamespace.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/HostNamespace.java
index d9482705d..583d066e2 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/HostNamespace.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/HostNamespace.java
@@ -27,15 +27,32 @@ import org.osgi.resource.Namespace;
  * and are used as arbitrary matching attributes for the capability. The values
  * associated with the specified directive and attribute keys are of type
  * {@code String}, unless otherwise indicated.
+ * 
  * <p>
- * For compatibility with previous versions of the specification all directives
- * specified on the {@code Bundle-SymbolicName} header are available to this
- * namespace. The directive {@link #REQUIREMENT_VISIBILITY_DIRECTIVE visibility}
- * should be looked up using the {@link BundleNamespace#BUNDLE_NAMESPACE bundle}
- * namespace. The directive {@link #CAPABILITY_SINGLETON_DIRECTIVE singleton}
- * should be looked up using the {@link IdentityNamespace#IDENTITY_NAMESPACE
- * identity} namespace. Also, the {@link Namespace#CAPABILITY_USES_DIRECTIVE uses}
- * directive has no meaning to this namespace.
+ * Unless otherwise noted, all directives specified on the
+ * {@code Bundle-SymbolicName} header are visible in the capability and all
+ * directives specified on the {@code Fragment-Host} header are visible in the
+ * requirement.
+ * 
+ * <ul>
+ * <li>The {@link Namespace#CAPABILITY_USES_DIRECTIVE uses} directive must be
+ * ignored. A {@code uses} directive specified on the
+ * {@code Bundle-SymbolicName} header must be ignored. A {@code uses} directive
+ * must not be present in the capability.</li>
+ * <li>The {@link Namespace#CAPABILITY_EFFECTIVE_DIRECTIVE effective}
+ * {@link Namespace#REQUIREMENT_EFFECTIVE_DIRECTIVE directives} must be ignored.
+ * This namespace is only effective at {@link Namespace#EFFECTIVE_RESOLVE
+ * resolve} time. An {@code effective} directive specified on the
+ * {@code Bundle-SymbolicName} or {@code Fragment-Host} headers must be ignored.
+ * An {@code effective} directive must not be present in a capability or
+ * requirement.</li>
+ * <li>The {@link Namespace#REQUIREMENT_CARDINALITY_DIRECTIVE cardinality}
+ * directive has limited applicability to this namespace. A {@code cardinality}
+ * directive specified on the {@code Fragment-Host} header must be ignored. All
+ * requirements must have the {@code cardinality} directive set to
+ * {@link Namespace#CARDINALITY_MULTIPLE multiple}.</li>
+ * </ul>
+ * 
  * <p>
  * A non-fragment resource with the with the
  * {@link IdentityNamespace#TYPE_BUNDLE osgi.bundle} type
@@ -65,9 +82,15 @@ public final class HostNamespace extends AbstractWiringNamespace {
 
 	/**
 	 * The capability directive identifying if the resource is a singleton. A
-	 * {@code 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.
+	 * {@code String} value of &quot;{@code true}&quot; indicates the resource
+	 * is a singleton; any other value or <code>null</code> indicates the
+	 * resource is not a singleton.
+	 * 
+	 * <p>
+	 * This directive should be examined using the {@link IdentityNamespace
+	 * identity} namespace.
+	 * 
+	 * @see IdentityNamespace#CAPABILITY_SINGLETON_DIRECTIVE
 	 */
 	public static final String	CAPABILITY_SINGLETON_DIRECTIVE	= "singleton";
 
@@ -135,33 +158,15 @@ public final class HostNamespace extends AbstractWiringNamespace {
 
 	/**
 	 * The requirement directive used to specify the visibility type for a
-	 * requirement. The default value is {@link #VISIBILITY_PRIVATE private}.
-	 * 
-	 * @see #VISIBILITY_PRIVATE private
-	 * @see #VISIBILITY_REEXPORT reexport
-	 */
-	public final static String	REQUIREMENT_VISIBILITY_DIRECTIVE	= "visibility";
-
-	/**
-	 * The directive value identifying a private
-	 * {@link #REQUIREMENT_VISIBILITY_DIRECTIVE visibility} type. A private
-	 * visibility type indicates that any {@link PackageNamespace packages} that
-	 * are exported by the required bundle are not made visible on the export
-	 * signature of the requiring bundle. .
+	 * requirement.
 	 * 
-	 * @see #REQUIREMENT_VISIBILITY_DIRECTIVE
-	 */
-	public final static String	VISIBILITY_PRIVATE					= "private";
-
-	/**
-	 * The directive value identifying a reexport
-	 * {@link #REQUIREMENT_VISIBILITY_DIRECTIVE visibility} type. A reexport
-	 * visibility type indicates any {@link PackageNamespace packages} that are
-	 * exported by the required bundle are re-exported by the requiring bundle.
+	 * <p>
+	 * This directive should be examined using the {@link BundleNamespace
+	 * bundle} namespace.
 	 * 
-	 * @see #REQUIREMENT_VISIBILITY_DIRECTIVE
+	 * @see BundleNamespace#REQUIREMENT_VISIBILITY_DIRECTIVE
 	 */
-	public final static String	VISIBILITY_REEXPORT					= "reexport";
+	public final static String	REQUIREMENT_VISIBILITY_DIRECTIVE	= "visibility";
 
 	private HostNamespace() {
 		// empty
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/IdentityNamespace.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/IdentityNamespace.java
index d033e96e5..fc8adc7ae 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/IdentityNamespace.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/IdentityNamespace.java
@@ -52,7 +52,7 @@ public final class IdentityNamespace extends Namespace {
 	 * Also, the capability attribute used to specify the symbolic name of the
 	 * resource.
 	 */
-	public static final String	IDENTITY_NAMESPACE				= "osgi.identity";
+	public static final String	IDENTITY_NAMESPACE					= "osgi.identity";
 
 	/**
 	 * The capability directive identifying if the resource is a singleton. A
@@ -60,14 +60,14 @@ public final class IdentityNamespace extends Namespace {
 	 * singleton; any other value or <code>null</code> indicates the resource is
 	 * not a singleton.
 	 */
-	public static final String	CAPABILITY_SINGLETON_DIRECTIVE	= "singleton";
+	public static final String	CAPABILITY_SINGLETON_DIRECTIVE		= "singleton";
 
 	/**
 	 * The capability attribute identifying the {@code Version} of the resource
 	 * if one is specified or {@code 0.0.0} if not specified. The value of this
 	 * attribute must be of type {@code Version}.
 	 */
-	public static final String	CAPABILITY_VERSION_ATTRIBUTE	= "version";
+	public static final String	CAPABILITY_VERSION_ATTRIBUTE		= "version";
 
 	/**
 	 * The capability attribute identifying the resource type. If the resource
@@ -78,7 +78,7 @@ public final class IdentityNamespace extends Namespace {
 	 * @see #TYPE_FRAGMENT
 	 * @see #TYPE_UNKNOWN
 	 */
-	public static final String	CAPABILITY_TYPE_ATTRIBUTE		= "type";
+	public static final String	CAPABILITY_TYPE_ATTRIBUTE			= "type";
 
 	/**
 	 * The attribute value identifying the resource
@@ -86,7 +86,7 @@ public final class IdentityNamespace extends Namespace {
 	 * 
 	 * @see #CAPABILITY_TYPE_ATTRIBUTE
 	 */
-	public static final String	TYPE_BUNDLE						= "osgi.bundle";
+	public static final String	TYPE_BUNDLE							= "osgi.bundle";
 
 	/**
 	 * The attribute value identifying the resource
@@ -94,7 +94,7 @@ public final class IdentityNamespace extends Namespace {
 	 * 
 	 * @see #CAPABILITY_TYPE_ATTRIBUTE
 	 */
-	public static final String	TYPE_FRAGMENT					= "osgi.fragment";
+	public static final String	TYPE_FRAGMENT						= "osgi.fragment";
 
 	/**
 	 * The attribute value identifying the resource
@@ -102,7 +102,59 @@ public final class IdentityNamespace extends Namespace {
 	 * 
 	 * @see #CAPABILITY_TYPE_ATTRIBUTE
 	 */
-	public static final String	TYPE_UNKNOWN					= "unknown";
+	public static final String	TYPE_UNKNOWN						= "unknown";
+
+	/**
+	 * The capability attribute that contains a human readable copyright notice
+	 * for the resource. See the {@code Bundle-Copyright} manifest header.
+	 */
+	public final String			CAPABILITY_COPYRIGHT_ATTRIBUTE		= "copyright";
+
+	/**
+	 * The capability attribute that contains a human readable description for
+	 * the resource. See the {@code Bundle-Description} manifest header.
+	 */
+	public final String			CAPABILITY_DESCRIPTION_ATTRIBUTE	= "description";
+
+	/**
+	 * The capability attribute that contains the URL to documentation for the
+	 * resource. See the {@code Bundle-DocURL} manifest header.
+	 */
+	public final String			CAPABILITY_DOCUMENTATION_ATTRIBUTE	= "documentation";
+
+	/**
+	 * The capability attribute that contains the URL to the license for the
+	 * resource. See the {@name} portion of the {@code Bundle-License}
+	 * manifest header.
+	 */
+	public final String			CAPABILITY_LICENSE_ATTRIBUTE		= "license";
+
+	/**
+	 * The requirement directive that classifies the relationship with another
+	 * resource.
+	 * 
+	 * @see #CLASSIFIER_SOURCES
+	 * @see #CLASSIFIER_JAVADOC
+	 */
+	public final String			REQUIREMENT_CLASSIFIER_DIRECTIVE	= "classifier";
+
+	/**
+	 * The attribute value identifying the resource
+	 * {@link #REQUIREMENT_CLASSIFIER_DIRECTIVE classifier} as an archive
+	 * containing the source code in the same directory layout as the resource.
+	 * 
+	 * @see #REQUIREMENT_CLASSIFIER_DIRECTIVE
+	 */
+
+	public final String			CLASSIFIER_SOURCES					= "sources";
+	/**
+	 * The attribute value identifying the resource
+	 * {@link #REQUIREMENT_CLASSIFIER_DIRECTIVE classifier} as an archive
+	 * containing the javadoc in the same directory layout as the resource.
+	 * 
+	 * @see #REQUIREMENT_CLASSIFIER_DIRECTIVE
+	 */
+	public final String			CLASSIFIER_JAVADOC					= "javadoc";
 
 	private IdentityNamespace() {
 		// empty
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/PackageNamespace.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/PackageNamespace.java
index df5c7f2f6..5adc45bd1 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/PackageNamespace.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/namespace/PackageNamespace.java
@@ -16,6 +16,8 @@
 
 package org.osgi.framework.namespace;
 
+import org.osgi.resource.Namespace;
+
 /**
  * Package Capability and Requirement Namespace.
  * 
@@ -31,6 +33,31 @@ package org.osgi.framework.namespace;
  * associated with the specified directive and attribute keys are of type
  * {@code String}, unless otherwise indicated.
  * 
+ * <p>
+ * Unless otherwise noted, all directives specified on the
+ * {@code Export-Package} header are visible in the capability and all
+ * directives specified on the {@code Import-Package} and
+ * {@code DynamicImport-Package} headers are visible in the requirement.
+ * 
+ * <ul>
+ * <li>The {@link Namespace#CAPABILITY_EFFECTIVE_DIRECTIVE effective}
+ * {@link Namespace#REQUIREMENT_EFFECTIVE_DIRECTIVE directives} must be ignored.
+ * This namespace is only effective at {@link Namespace#EFFECTIVE_RESOLVE
+ * resolve} time. An {@code effective} directive specified on the
+ * {@code Export-Package}, {@code Import-Package} or
+ * {@code DynamicImport-Package} headers must be ignored. An {@code effective}
+ * directive must not be present in a capability or requirement.</li>
+ * <li>The {@link Namespace#REQUIREMENT_CARDINALITY_DIRECTIVE cardinality}
+ * directive has limited applicability to this namespace. A {@code cardinality}
+ * directive specified on the {@code Import-Package} or
+ * {@code DynamicImport-Package} headers must be ignored. Only requirements with
+ * {@link Namespace#REQUIREMENT_RESOLUTION_DIRECTIVE resolution} set to
+ * {@link #RESOLUTION_DYNAMIC dynamic} and the package name contains a wildcard
+ * must have the {@code cardinality} directive set to
+ * {@link Namespace#CARDINALITY_MULTIPLE multiple}. Otherwise, a
+ * {@code cardinality} directive must not be present in a requirement.</li>
+ * </ul>
+ * 
  * @Immutable
  * @version $Id$
  */
@@ -69,6 +96,16 @@ public final class PackageNamespace extends AbstractWiringNamespace {
 	 */
 	public final static String	CAPABILITY_BUNDLE_SYMBOLICNAME_ATTRIBUTE	= "bundle-symbolic-name";
 
+	/**
+	 * The directive value identifying a dynamic requirement resolution type. A
+	 * dynamic resolution type indicates that the requirement is resolved
+	 * dynamically at runtime (such as a dynamically imported package) and the
+	 * resource will be resolved without the requirement being resolved.
+	 * 
+	 * @see Namespace#REQUIREMENT_RESOLUTION_DIRECTIVE
+	 */
+	public final static String	RESOLUTION_DYNAMIC							= "dynamic";
+
 	private PackageNamespace() {
 		// empty
 	}
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/resource/Namespace.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/resource/Namespace.java
index 09d093ed7..43c9ff5ce 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/resource/Namespace.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/resource/Namespace.java
@@ -82,7 +82,7 @@ public abstract class Namespace {
 	/**
 	 * The directive value identifying an optional requirement resolution type.
 	 * An optional resolution type indicates that the requirement is optional
-	 * and the resource may be resolved without requirement being resolved.
+	 * and the resource may be resolved without the requirement being resolved.
 	 * 
 	 * @see #REQUIREMENT_RESOLUTION_DIRECTIVE
 	 */