org.osgi.service.framework

Interface CompositeBundle

All Superinterfaces:

Bundle, Comparable<Bundle>

All Known Implementing Classes:

CompositeImpl

Deprecated.

This API proposal was rejected by the OSGi Alliance and will not be part of any OSGi specification. Please transition to the org.osgi.framework.hooks API to control resolution, bundle, and service isolation. This API will be removed from Equinox in the 3.9 release You are cautioned against relying upon this API.

public interface CompositeBundle
extends Bundle

Composite bundles are composed of other bundles. The component bundles which make up the content of a composite bundle are installed into a child framework. Like a normal bundle, a composite bundle may import packages and use services from other bundles which are installed in the same framework as the composite bundle. The packages imported and the services used by a composite bundle are shared with the components of a composite bundle through a surrogate bundle installed in the child framework. Also like a normal bundle, a composite bundle may export packages and register services which can be used by bundles installed in the same framework as the composite bundle. The packages exported and the services registered by a composite bundle are acquired from the components of a composite bundle by the surrogate bundle installed in the child framework

A framework has one composite bundle for each of its child frameworks. A framework can have zero or more composite bundles installed. A child framework must have one and only one surrogate bundle which represents the composite bundle in the parent framework. In other words, a parent framework can have many child frameworks but a child framework can have only one parent.

A composite bundle does the following as specified by the composite manifest map:

• Exports packages to the parent framework from the child framework. These packages are imported by the surrogate bundle installed in the child framework.
• Imports packages from the parent framework. These packages are exported by the surrogate bundle installed in the child framework.
• Registers services to the parent framework from the child framework. These services are acquired by the surrogate bundle installed in the child framework.
• Acquires services from the parent framework. These services are registered by the surrogate bundle installed in the child framework.

A newly created child Framework will be in the STARTING state. This child Framework can then be used to manage and control the child framework instance. The child framework instance is persistent and uses a storage area associated with the installed composite bundle. The child framework's lifecycle is tied to its composite bundle's lifecycle in the following ways:

• If the composite bundle is marked to be persistently started (see StartLevel.isBundlePersistentlyStarted(Bundle)) then the child framework instance will automatically be started when the composite bundle's start-level is met.
• The child framework instance will be stopped if the composite bundle is persistently stopped or its start level is no longer met. Performing operations which transiently stop a composite bundle do not cause the child framework to stop (e.g. stop(Bundle.STOP_TRANSIENT), update, refreshPackages etc.).
• If the composite bundle is uninstalled, the child framework's persistent storage area is also uninstalled.

The child framework may be persistently started and stopped by persistently starting and stopping the composite bundle, but it is still possible to initialize and start the child framework explicitly while the composite bundle is not persistently started. This allows for the child framework to be initialized and populated with a set of bundles before starting the composite bundle. The set of bundles installed into the child framework are the component bundles which comprise the composite bundle.

The child framework's lifecycle is also tied to the lifecycle of its parent framework. When the parent Framework enters the STOPPING state, all active child frameworks of that parent are shutdown using the Framework.stop() method. The parent framework must not enter the Bundle.RESOLVED state until all the child frameworks have completed their shutdown process. Just as with other Bundles, references to child frameworks (or the associated composite and surrogate bundles) become invalid after the parent framework has completed the shutdown process, and must not be allowed to re-initialize or re-start the child framework.

Version:

$Revision: 6860 $

See Also:

SurrogateBundle

Field Summary

Fields inherited from interface org.osgi.framework.Bundle

ACTIVE, INSTALLED, RESOLVED, SIGNERS_ALL, SIGNERS_TRUSTED, START_ACTIVATION_POLICY, START_TRANSIENT, STARTING, STOP_TRANSIENT, STOPPING, UNINSTALLED

Method Summary

Methods

Modifier and Type	Method and Description
Framework	getCompositeFramework() Deprecated. Returns the child framework associated with this composite bundle.
SurrogateBundle	getSurrogateBundle() Deprecated. Returns the surrogate bundle associated with this composite bundle.
void	uninstall() Deprecated. Uninstalls this composite bundle.
void	update() Deprecated. This operation is not supported for composite bundles.
void	update(InputStream input) Deprecated. This operation is not supported for composite bundles.
void	update(Map compositeManifest) Deprecated. Updates this composite bundle with the specified manifest.

Methods inherited from interface org.osgi.framework.Bundle

adapt, findEntries, getBundleContext, getBundleId, getDataFile, getEntry, getEntryPaths, getHeaders, getHeaders, getLastModified, getLocation, getRegisteredServices, getResource, getResources, getServicesInUse, getSignerCertificates, getState, getSymbolicName, getVersion, hasPermission, loadClass, start, start, stop, stop

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getCompositeFramework

Framework getCompositeFramework()

Deprecated.

Returns the child framework associated with this composite bundle.

Returns:

the child framework.

getSurrogateBundle

SurrogateBundle getSurrogateBundle()

Deprecated.

Returns the surrogate bundle associated with this composite bundle. The surrogate bundle is installed in the child framework.

Returns:

the surrogate bundle.

update

void update(Map compositeManifest)
            throws BundleException

Deprecated.

Updates this composite bundle with the specified manifest.

Similar to normal bundle updates, the packages exported by a composite or surrogate bundle can not change as a result of calling update: the previous package exports must be available to other consuming bundles (in either the parent or child framework) until the PackageAdmin.refreshPackages method has been called to refresh the composite, or the parent Framework is re-launched.

Parameters:

compositeManifest - the new composite manifest.

Throws:

BundleException - If the update fails.

See Also:

CompositeBundleFactory.installCompositeBundle(Map, String, Map)

update

void update()
            throws BundleException

Deprecated.

This operation is not supported for composite bundles. A BundleException of type invalid operation must be thrown.

Specified by:

update in interface Bundle

Throws:

BundleException - If this bundle could not be updated. BundleException types thrown by this method include: BundleException.READ_ERROR, BundleException.DUPLICATE_BUNDLE_ERROR, BundleException.MANIFEST_ERROR, BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.

See Also:

Bundle.update(InputStream)

update

void update(InputStream input)
            throws BundleException

Deprecated.

This operation is not supported for composite bundles. A BundleException of type invalid operation must be thrown.

Specified by:

update in interface Bundle

Parameters:

input - The InputStream from which to read the new bundle or null to indicate the Framework must create the input stream from this bundle's Bundle-UpdateLocation Manifest header, if present, or this bundle's original location. The input stream must always be closed when this method completes, even if an exception is thrown.

Throws:

BundleException - If this bundle could not be updated. BundleException types thrown by this method include: BundleException.READ_ERROR, BundleException.DUPLICATE_BUNDLE_ERROR, BundleException.MANIFEST_ERROR, BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.

See Also:

Bundle.stop(), Bundle.start()

uninstall

void uninstall()
               throws BundleException

Deprecated.

Uninstalls this composite bundle. The associated child framework is shutdown, and its persistent storage area is deleted.

Specified by:

uninstall in interface Bundle

Throws:

BundleException - If the uninstall failed. This can occur if another thread is attempting to change this bundle's state and does not complete in a timely manner. BundleException types thrown by this method include: BundleException.STATECHANGE_ERROR

See Also:

Bundle.stop()