A Bundle object is the access point to define the lifecycle of an installed bundle. Each bundle installed in the CppMicroServices environment has an associated Bundle object.

A bundle has a unique identity, a long, chosen by the Framework. This identity does not change during the lifecycle of a bundle. Uninstalling and then reinstalling the bundle creates a new unique identity.

A bundle can be in one of six states:

STATE_UNINSTALLED

STATE_INSTALLED

STATE_RESOLVED

STATE_STARTING

STATE_STOPPING

STATE_ACTIVE

Values assigned to these states have no specified ordering; they represent bit values that may be ORed together to determine if a bundle is in one of the valid states.

A bundle should only have active threads of execution when its state is one of STATE_STARTING,STATE_ACTIVE, or STATE_STOPPING. A STATE_UNINSTALLED bundle can not be set to another state; it is a zombie and can only be reached because references are kept somewhere.

The framework is the only entity that is allowed to create Bundle objects, and these objects are only valid within the Framework that created them.

Bundles have a natural ordering such that if two Bundles have the same bundle id they are equal. A Bundle is less than another Bundle if it has a lower bundle id and is greater if it has a higher bundle id.

A bundle is in the STATE_INSTALLED state when it has been installed in the Framework but is not or cannot be resolved.

This state is visible if the bundle’s code dependencies are not resolved. The Framework may attempt to resolve a STATE_INSTALLED bundle’s code dependencies and move the bundle to the STATE_RESOLVED state.

The bundle start operation is transient and the persistent autostart setting of the bundle is not modified.

This bit may be set when calling Start(uint32_t) to notify the framework that the autostart setting of the bundle must not be modified. If this bit is not set, then the autostart setting of the bundle is modified.

The bundle stop is transient and the persistent autostart setting of the bundle is not modified.

This bit may be set when calling Stop(uint32_t) to notify the framework that the autostart setting of the bundle must not be modified. If this bit is not set, then the autostart setting of the bundle is modified.

path: The path name in which to look. The path is always relative to the root of this bundle and may begin with ‘/’. A path value of “/” indicates the root of this bundle.

filePattern: The resource name pattern for selecting entries in the specified path. The pattern is only matched against the last element of the resource path. Substring matching is supported using the wildcard charachter (‘*’). If filePattern is empty, this is equivalent to “*” and matches all resources.

recurse: If true, recurse into subdirectories. Otherwise only return resources from the specified path.

If this bundle’s state is STATE_UNINSTALLED then a std::logic_error is thrown.

The Framework sets this bundle’s persistent autostart setting to Started with declared activation if the START_ACTIVATION_POLICY option is set or Started with eager activation if not set.

The following steps are executed to start this bundle:

If this bundle is in the process of being activated or deactivated, then this method waits for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a std::runtime_error is thrown to indicate this bundle was unable to be started.

If this bundle’s state is STATE_ACTIVE, then this method returns immediately.

If the START_TRANSIENT option is not set, then set this bundle’s autostart setting to Started with declared activation if the START_ACTIVATION_POLICY option is set or Started with eager activation if not set. When the Framework is restarted and this bundle’s autostart setting is not Stopped, this bundle must be automatically started.

If this bundle’s state is not STATE_RESOLVED, an attempt is made to resolve this bundle. If the Framework cannot resolve this bundle, a std::runtime_error is thrown.

If this bundle’s state is STATE_UNINSTALLED then a std::logic_error is thrown.

If this bundle is in the process of being activated or deactivated then this method waits for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a std::runtime_error is thrown to indicate this bundle was unable to be stopped.

If the STOP_TRANSIENT option is not set then set this bundle’s persistent autostart setting to Stopped. When the Framework is restarted and this bundle’s autostart setting is Stopped, this bundle will not be automatically started.

If this bundle’s state is not STATE_STARTING or STATE_ACTIVE then this method returns immediately.

If this bundle’s state was STATE_ACTIVE prior to setting the state to STATE_STOPPING, the BundleActivator#Stop(BundleContext) method of this bundle’s BundleActivator, if one is specified, is called. If that method throws an exception, this method continues to stop this bundle and a std::runtime_error is thrown after completion of the remaining steps.

Any services registered by this bundle are unregistered.

Any services used by this bundle are released.

Any listeners registered by this bundle are removed.

If this bundle’s state is STATE_UNINSTALLED, because this bundle was uninstalled while the BundleActivator::Stop method was running, a std::runtime_error is thrown.

This method causes the Framework to notify other bundles that this bundle is being uninstalled, and then puts this bundle into the STATE_UNINSTALLED state. The Framework removes any resources related to this bundle that it is able to remove.

The following steps are executed to uninstall a bundle:

If this bundle’s state is STATE_UNINSTALLED, then a std::logic_error is thrown.