A bundle is a Python module installed using the Pelix
Framework instance or a
Each bundle is associated to an ID, an integer that is unique for a framework instance, and to a symbolic name, i.e. its module name. The framework itself is seen as the bundle which ID is always 0.
Because installing a bundle is in fact importing a module, no code should be written to be executed at module-level (except the definition of constants, the import of dependencies, …). Initialization must be done in the bundle activator (see below).
Unlike a module, a bundle has a life-cycle and can be in one of the following states:
|INSTALLED||The Python module has been correctly imported, the bundle goes to the RESOLVED state|
|RESOLVED||The bundle has not been started yet or has been stopped|
|ACTIVE||The bundle activator has been called and didn’t raise any error|
|UNINSTALLED||The bundle has been removed from the framework (only visible by remaining references to the bundle)|
The update process of a bundle is simple:
- if it was active, the bundle is stopped: other bundles are notified of this transition, and its services are unregistered
- the module is updated, using the importlib.reload() method (or imp.reload() when not available)
- if the update fails, the previous version of the module is kept, but the bundle is not restarted.
- if the update succeeds and the bundle was active, the bundle its restarted
The framework is locked during transitions in bundles states, which means
during the calls to
Therefore, it is heavily recommended to return fast from those methods.
For example, it may be necessary to use threads to complete the initialization
before registering services when the bundle starts.
On the other hand, it is recommended to wait for all resources to be released
before exiting the
stop() , e.g. to
wait for all threads started by the bundle to terminate.
This decorator must be applied to the class that will be notified of the life-cycle events concerning the bundle. A bundle can only have one activator, which must implement the following methods:
This method is called when the bundle is in STARTING state. If this method doesn’t raise an exception, the bundle goes immediately into the ACTIVE state. If an exception is raised, the bundle is stopped.
During the call of this method, the framework is locked. It is therefore necessary that this method returns as soon as possible: all time-consuming tasks should be executed in a new thread.
This method is called when the bundle is in STOPPING state. After this method returns or raises an exception, the bundle goes into the RESOLVED state.
All resources consumed by the bundle should be released before this method returns.
A class is defined as the bundle activator if it is decorated with
@BundleActivator, as shown in the following snippet:
import pelix.constants @pelix.constants.BundleActivator class Activator(object): """ Bundle activator template """ def start(self, context): """ Bundle is starting """ print("Start") def stop(self, context): """ Bundle is stopping """ print("Stop")
The previous declaration of the activator, i.e. declaring module member
activator, is deprecated and its support will be removed in
A context is associated to each bundle, and allows it to interact with the
It is unique for a bundle and can be used until the latter is removed from
It is not recommended to keep references to
BundleContext objects as they
can imply a stall reference to the bundle they describe.
A bundle must use its context to register and to look up services, to request
framework information, etc..
All the available methods are described in the API chapter. Here are the most used ones concerning the handling of bundles: