/* * Copyright (c) OSGi Alliance (2010, 2012). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.osgi.framework.wiring; import java.util.List; import org.osgi.framework.Bundle; import org.osgi.framework.BundleReference; import org.osgi.framework.Constants; import org.osgi.framework.Version; import org.osgi.framework.namespace.BundleNamespace; import org.osgi.framework.namespace.HostNamespace; import org.osgi.framework.namespace.PackageNamespace; import org.osgi.resource.Capability; import org.osgi.resource.Requirement; import org.osgi.resource.Resource; /** * Bundle Revision. When a bundle is installed and each time a bundle is * updated, a new bundle revision of the bundle is created. Since a bundle * update can change the entries in a bundle, different bundle wirings for the * same bundle can be associated with different bundle revisions. * *

* For a bundle that has not been uninstalled, the most recent bundle revision * is defined to be the current bundle revision. A bundle in the UNINSTALLED * state does not have a current revision. The current bundle revision for a * bundle can be obtained by calling {@link Bundle#adapt(Class) bundle.adapt} * (BundleRevision.class). Since a bundle in the UNINSTALLED state does not have * a current revision, adapting such a bundle returns {@code null}. * *

* The framework defines namespaces for {@link PackageNamespace package}, * {@link BundleNamespace bundle} and {@link HostNamespace host} capabilities * and requirements. These namespaces are defined only to express wiring * information by the framework. They must not be used in * {@link Constants#PROVIDE_CAPABILITY Provide-Capability} and * {@link Constants#REQUIRE_CAPABILITY Require-Capability} manifest headers. * * @ThreadSafe * @noimplement * @version $Id: e68e01a670f0ae9d6eb736414f875c8b216ed1bc $ */ public interface BundleRevision extends BundleReference, Resource { /** * Returns the symbolic name for this bundle revision. * * @return The symbolic name for this bundle revision. * @see Bundle#getSymbolicName() */ String getSymbolicName(); /** * Returns the version for this bundle revision. * * @return The version for this bundle revision, or * {@link Version#emptyVersion} if this bundle revision has no * version information. * @see Bundle#getVersion() */ Version getVersion(); /** * Returns the capabilities declared by this bundle revision. * * @param namespace The namespace of the declared capabilities to return or * {@code null} to return the declared capabilities from all * namespaces. * @return An unmodifiable list containing the declared * {@link BundleCapability}s from the specified namespace. The * returned list will be empty if this bundle revision declares no * capabilities in the specified namespace. The list contains the * declared capabilities in the order they are specified in the * manifest. */ List getDeclaredCapabilities(String namespace); /** * Returns the requirements declared by this bundle revision. * * @param namespace The namespace of the declared requirements to return or * {@code null} to return the declared requirements from all * namespaces. * @return An unmodifiable list containing the declared * {@link BundleRequirement}s from the specified namespace. The * returned list will be empty if this bundle revision declares no * requirements in the specified namespace. The list contains the * declared requirements in the order they are specified in the * manifest. */ List getDeclaredRequirements(String namespace); /** * Namespace for package capabilities and requirements. * *

* The name of the package is stored in the capability attribute of the same * name as this namespace (osgi.wiring.package). The other directives and * attributes of the package, from the {@link Constants#EXPORT_PACKAGE * Export-Package} manifest header, can be found in the cabability's * {@link BundleCapability#getDirectives() directives} and * {@link BundleCapability#getAttributes() attributes}. The * {@link Constants#VERSION_ATTRIBUTE version} capability attribute must * contain the {@link Version} of the package if one is specified or * {@link Version#emptyVersion} if not specified. The * {@link Constants#BUNDLE_SYMBOLICNAME_ATTRIBUTE bundle-symbolic-name} * capability attribute must contain the * {@link BundleRevision#getSymbolicName() symbolic name} of the provider if * one is specified. The {@link Constants#BUNDLE_VERSION_ATTRIBUTE * bundle-version} capability attribute must contain the * {@link BundleRevision#getVersion() version} of the provider if one is * specified or {@link Version#emptyVersion} if not specified. * *

* The package capabilities provided by the system bundle, that is the * bundle with id zero, must include the package specified by the * {@link Constants#FRAMEWORK_SYSTEMPACKAGES} and * {@link Constants#FRAMEWORK_SYSTEMPACKAGES_EXTRA} framework properties as * well as any other package exported by the framework implementation. * *

* A bundle revision {@link BundleRevision#getDeclaredCapabilities(String) * declares} zero or more package capabilities (this is, exported packages) * and {@link BundleRevision#getDeclaredRequirements(String) declares} zero * or more package requirements. *

* A bundle wiring {@link BundleWiring#getCapabilities(String) provides} * zero or more resolved package capabilities (that is, exported packages) * and {@link BundleWiring#getRequiredWires(String) requires} zero or more * resolved package requirements (that is, imported packages). The number of * package wires required by a bundle wiring may change as the bundle wiring * may dynamically import additional packages. * * @see PackageNamespace */ String PACKAGE_NAMESPACE = PackageNamespace.PACKAGE_NAMESPACE; /** * Namespace for bundle capabilities and requirements. * *

* The bundle symbolic name of the bundle is stored in the capability * attribute of the same name as this namespace (osgi.wiring.bundle). The * other directives and attributes of the bundle, from the * {@link Constants#BUNDLE_SYMBOLICNAME Bundle-SymbolicName} manifest * header, can be found in the cabability's * {@link BundleCapability#getDirectives() directives} and * {@link BundleCapability#getAttributes() attributes}. The * {@link Constants#BUNDLE_VERSION_ATTRIBUTE bundle-version} capability * attribute must contain the {@link Version} of the bundle from the * {@link Constants#BUNDLE_VERSION Bundle-Version} manifest header if one is * specified or {@link Version#emptyVersion} if not specified. * *

* A non-fragment revision * {@link BundleRevision#getDeclaredCapabilities(String) declares} exactly * one† bundle capability (that is, the bundle can be * required by another bundle). A fragment revision must not declare a * bundle capability. * *

* A bundle wiring for a non-fragment revision * {@link BundleWiring#getCapabilities(String) provides} exactly * one† bundle capability (that is, the bundle can be * required by another bundle) and * {@link BundleWiring#getRequiredWires(String) requires} zero or more * bundle capabilities (that is, requires other bundles). * *

* † A bundle with no bundle symbolic name (that is, a bundle with * {@link Constants#BUNDLE_MANIFESTVERSION Bundle-ManifestVersion} * {@literal <} 2) must not provide a bundle capability. * * @see BundleNamespace */ String BUNDLE_NAMESPACE = BundleNamespace.BUNDLE_NAMESPACE; /** * Namespace for host capabilities and requirements. * *

* The bundle symbolic name of the bundle is stored in the capability * attribute of the same name as this namespace (osgi.wiring.host). The * other directives and attributes of the bundle, from the * {@link Constants#BUNDLE_SYMBOLICNAME Bundle-SymbolicName} manifest * header, can be found in the cabability's * {@link BundleCapability#getDirectives() directives} and * {@link BundleCapability#getAttributes() attributes}. The * {@link Constants#BUNDLE_VERSION_ATTRIBUTE bundle-version} capability * attribute must contain the {@link Version} of the bundle from the * {@link Constants#BUNDLE_VERSION Bundle-Version} manifest header if one is * specified or {@link Version#emptyVersion} if not specified. * *

* A non-fragment revision * {@link BundleRevision#getDeclaredCapabilities(String) declares} zero or * one† host capability if the bundle * {@link Constants#FRAGMENT_ATTACHMENT_DIRECTIVE allows fragments to be * attached}. A fragment revision must * {@link BundleRevision#getDeclaredRequirements(String) declare} exactly * one host requirement. * *

* A bundle wiring for a non-fragment revision * {@link BundleWiring#getCapabilities(String) provides} zero or * one† host capability if the bundle * {@link Constants#FRAGMENT_ATTACHMENT_DIRECTIVE allows fragments to be * attached}. A bundle wiring for a fragment revision * {@link BundleWiring#getRequiredWires(String) requires} a host capability * for each host to which it is attached. * *

* † A bundle with no bundle symbolic name (that is, a bundle with * {@link Constants#BUNDLE_MANIFESTVERSION Bundle-ManifestVersion} * {@literal <} 2) must not provide a host capability. * * @see HostNamespace */ String HOST_NAMESPACE = HostNamespace.HOST_NAMESPACE; /** * Returns the special types of this bundle revision. The bundle revision * type values are: *

* * A bundle revision may be more than one type at a time. A type code is * used to identify the bundle revision type for future extendability. * *

* If this bundle revision is not one or more of the defined types then 0 is * returned. * * @return The special types of this bundle revision. The type values are * ORed together. */ int getTypes(); /** * Bundle revision type indicating the bundle revision is a fragment. * * @see #getTypes() */ int TYPE_FRAGMENT = 0x00000001; /** * Returns the bundle wiring which is using this bundle revision. * * @return The bundle wiring which is using this bundle revision or * {@code null} if no bundle wiring is using this bundle revision. * @see BundleWiring#getRevision() */ BundleWiring getWiring(); /** * Returns the capabilities declared by this resource. * *

* This method returns the same value as * {@link #getDeclaredCapabilities(String)}. * * @param namespace The namespace of the declared capabilities to return or * {@code null} to return the declared capabilities from all * namespaces. * @return An unmodifiable list containing the declared {@link Capability}s * from the specified namespace. The returned list will be empty if * this resource declares no capabilities in the specified * namespace. * @since 1.1 */ List getCapabilities(String namespace); /** * Returns the requirements declared by this bundle resource. * *

* This method returns the same value as * {@link #getDeclaredRequirements(String)}. * * @param namespace The namespace of the declared requirements to return or * {@code null} to return the declared requirements from all * namespaces. * @return An unmodifiable list containing the declared {@link Requirement} * s from the specified namespace. The returned list will be empty * if this resource declares no requirements in the specified * namespace. * @since 1.1 */ List getRequirements(String namespace); }