API

This part of the documentation covers all the core classes and services of iPOPO.

BundleContext Object

The bundle context is the link between a bundle and the framework. It’s by the context that you can register services, install other bundles.

class pelix.framework.BundleContext(framework, bundle)

The bundle context is the link between a bundle and the framework. It is unique for a bundle and is created by the framework once the bundle is installed.

Parameters:
  • framework – Hosting framework
  • bundle – The associated bundle
add_bundle_listener(listener)

Registers a bundle listener, which will be notified each time a bundle is installed, started, stopped or updated.

The listener must be a callable accepting a single parameter:
  • event – The description of the event (a BundleEvent object).
Parameters:listener – The bundle listener to register
Returns:True if the listener has been registered, False if it already was
add_framework_stop_listener(listener)

Registers a listener that will be called back right before the framework stops

The framework listener must have a method with the following prototype:

def framework_stopping(self):
    '''
    No parameter given
    '''
    # ...
Parameters:listener – The framework stop listener
Returns:True if the listener has been registered
add_service_listener(listener, ldap_filter=None, specification=None)

Registers a service listener

The service listener must have a method with the following prototype:

def service_changed(self, event):
    '''
    Called by Pelix when some service properties changes

    event: A ServiceEvent object
    '''
    # ...
Parameters:
  • listener – The listener to register
  • ldap_filter – Filter that must match the service properties (optional, None to accept all services)
  • specification – The specification that must provide the service (optional, None to accept all services)
Returns:

True if the listener has been successfully registered

get_all_service_references(clazz, ldap_filter=None)

Returns an array of ServiceReference objects. The returned array of ServiceReference objects contains services that were registered under the specified class and match the specified filter expression.

Parameters:
  • clazz – Class implemented by the service
  • ldap_filter – Service filter
Returns:

The sorted list of all matching service references, or None

get_bundle(bundle_id=None)

Retrieves the Bundle object for the bundle matching the given ID (int). If no ID is given (None), the bundle associated to this context is returned.

Parameters:bundle_id – A bundle ID (optional)
Returns:The requested Bundle object
Raises:BundleException – The given ID doesn’t exist or is invalid
get_bundles()

Returns the list of all installed bundles

Returns:A list of Bundle objects
get_property(name)

Returns the value of a property of the framework, else returns the OS environment value.

Parameters:name – A property name
get_service(reference)

Returns the service described with the given reference

Parameters:reference – A ServiceReference object
Returns:The service object itself
get_service_reference(clazz, ldap_filter=None)

Returns a ServiceReference object for a service that implements and was registered under the specified class

Parameters:
  • clazz – The class name with which the service was registered.
  • ldap_filter – A filter on service properties
Returns:

A service reference, None if not found

get_service_references(clazz, ldap_filter=None)

Returns the service references for services that were registered under the specified class by this bundle and matching the given filter

Parameters:
  • clazz – The class name with which the service was registered.
  • ldap_filter – A filter on service properties
Returns:

The list of references to the services registered by the calling bundle and matching the filters.

install_bundle(name, path=None)

Installs the bundle (module) with the given name.

If a path is given, it is inserted in first place in the Python loading path (sys.path). All modules loaded alongside this bundle, i.e. by this bundle or its dependencies, will be looked after in this path in priority.

Note

Before Pelix 0.5.0, this method returned the ID of the installed bundle, instead of the Bundle object.

Warning

The behavior of the loading process is subject to changes, as it does not allow to safely run multiple frameworks in the same Python interpreter, as they might share global module values.

Parameters:
  • name – The name of the bundle to install
  • path – Preferred path to load the module (optional)
Returns:

The Bundle object of the installed bundle

Raises:

BundleException – Error importing the module or one of its dependencies

install_package(path, recursive=False)

Installs all the modules found in the given package (directory). It is a utility method working like install_visiting(), with a visitor accepting every module found.

Parameters:
  • path – Path of the package (folder)
  • recursive – If True, installs the modules found in sub-directories
Returns:

A 2-tuple, with the list of installed bundles (Bundle) and the list of the names of the modules which import failed.

Raises:

ValueError – The given path is invalid

install_visiting(path, visitor)

Looks for modules in the given path and installs those accepted by the given visitor.

The visitor must be a callable accepting 3 parameters:
  • fullname – The full name of the module
  • is_package – If True, the module is a package
  • module_path – The path to the module file
Parameters:
  • path – Root search path (folder)
  • visitor – The visiting callable
Returns:

A 2-tuple, with the list of installed bundles (Bundle) and the list of the names of the modules which import failed.

Raises:

ValueError – Invalid path or visitor

register_service(clazz, service, properties, send_event=True)

Registers a service

Parameters:
  • clazz – Class or Classes (list) implemented by this service
  • service – The service instance
  • properties – The services properties (dictionary)
  • send_event – If not, doesn’t trigger a service registered event
Returns:

A ServiceRegistration object

Raises:

BundleException – An error occurred while registering the service

remove_bundle_listener(listener)

Unregisters the given bundle listener

Parameters:listener – The bundle listener to remove
Returns:True if the listener has been unregistered, False if it wasn’t registered
remove_framework_stop_listener(listener)

Unregisters a framework stop listener

Parameters:listener – The framework stop listener
Returns:True if the listener has been unregistered
remove_service_listener(listener)

Unregisters a service listener

Parameters:listener – The service listener
Returns:True if the listener has been unregistered
unget_service(reference)

Disables a reference to the service

Returns:True if the bundle was using this reference, else False

Framework Object

The Framework object is a singleton and can be accessed using get_bundle(0). This class inherits the methods from pelix.framework.Bundle.

class pelix.framework.Framework(properties=None)

The Pelix framework (main) class. It must be instantiated using FrameworkFactory

Sets up the framework.

Parameters:properties – The framework properties
add_property(name, value)

Adds a property to the framework if it is not yet set.

If the property already exists (same name), then nothing is done. Properties can’t be updated.

Parameters:
  • name – The property name
  • value – The value to set
Returns:

True if the property was stored, else False

find_service_references(clazz=None, ldap_filter=None, only_one=False)

Finds all services references matching the given filter.

Parameters:
  • clazz – Class implemented by the service
  • ldap_filter – Service filter
  • only_one – Return the first matching service reference only
Returns:

A list of found reference, or None

Raises:

BundleException – An error occurred looking for service references

get_bundle_by_id(bundle_id)

Retrieves the bundle with the given ID

Parameters:bundle_id – ID of an installed bundle
Returns:The requested bundle
Raises:BundleException – The ID is invalid
get_bundle_by_name(bundle_name)

Retrieves the bundle with the given name

Parameters:bundle_name – Name of the bundle to look for
Returns:The requested bundle, None if not found
get_bundles()

Returns the list of all installed bundles

Returns:the list of all installed bundles
get_properties()

Retrieves a copy of the stored framework properties.

get_property(name)

Retrieves a framework or system property. As framework properties don’t change while it’s running, this method don’t need to be protected.

Parameters:name – The property name
get_property_keys()

Returns an array of the keys in the properties of the service

Returns:An array of property keys.
get_service(bundle, reference)

Retrieves the service corresponding to the given reference

Parameters:
  • bundle – The bundle requiring the service
  • reference – A service reference
Returns:

The requested service

Raises:
  • BundleException – The service could not be found
  • TypeError – The argument is not a ServiceReference object
get_symbolic_name()

Retrieves the framework symbolic name

Returns:Always “pelix.framework”
install_bundle(name, path=None)

Installs the bundle with the given name

Note: Before Pelix 0.5.0, this method returned the ID of the installed bundle, instead of the Bundle object.

WARNING: The behavior of the loading process is subject to changes, as it does not allow to safely run multiple frameworks in the same Python interpreter, as they might share global module values.

Parameters:
  • name – A bundle name
  • path – Preferred path to load the module
Returns:

The installed Bundle object

Raises:

BundleException – Something happened

install_package(path, recursive=False, prefix=None)

Installs all the modules found in the given package

Parameters:
  • path – Path of the package (folder)
  • recursive – If True, install the sub-packages too
  • prefix – (internal) Prefix for all found modules
Returns:

A 2-tuple, with the list of installed bundles and the list of failed modules names

Raises:

ValueError – Invalid path

install_visiting(path, visitor, prefix=None)

Installs all the modules found in the given path if they are accepted by the visitor.

The visitor must be a callable accepting 3 parameters:

  • fullname: The full name of the module
  • is_package: If True, the module is a package
  • module_path: The path to the module file
Parameters:
  • path – Root search path
  • visitor – The visiting callable
  • prefix – (internal) Prefix for all found modules
Returns:

A 2-tuple, with the list of installed bundles and the list of failed modules names

Raises:

ValueError – Invalid path or visitor

register_service(bundle, clazz, service, properties, send_event)

Registers a service and calls the listeners

Parameters:
  • bundle – The bundle registering the service
  • clazz – Name(s) of the interface(s) implemented by service
  • properties – Service properties
  • send_event – If not, doesn’t trigger a service registered event
Returns:

A ServiceRegistration object

Raises:

BundleException – An error occurred while registering the service

start()

Starts the framework

Returns:True if the bundle has been started, False if it was already running
Raises:BundleException – A bundle failed to start
stop()

Stops the framework

Returns:True if the framework stopped, False it wasn’t running
uninstall()

A framework can’t be uninstalled

Raises:BundleException – This method must not be called
uninstall_bundle(bundle)

Ends the uninstallation of the given bundle (must be called by Bundle)

Parameters:bundle – The bundle to uninstall
Raises:BundleException – Invalid bundle
unregister_service(registration)

Unregisters the given service

Parameters:registration – A ServiceRegistration to the service to unregister
Raises:BundleException – Invalid reference
update()

Stops and starts the framework, if the framework is active.

Raises:BundleException – Something wrong occurred while stopping or starting the framework.
wait_for_stop(timeout=None)

Waits for the framework to stop. Does nothing if the framework bundle is not in ACTIVE state.

Uses a threading.Condition object

Parameters:timeout – The maximum time to wait (in seconds)
Returns:True if the framework has stopped, False if the timeout raised

Bundle Object

This object gives access to the description of an installed bundle. It is useful to check the path of the source module, the version, etc.

class pelix.framework.Bundle(framework, bundle_id, name, module)

Represents a “bundle” in Pelix

Sets up the bundle descriptor

Parameters:
  • framework – The host framework
  • bundle_id – The ID of the bundle in the host framework
  • name – The bundle symbolic name
  • module – The bundle module
get_bundle_context()

Retrieves the bundle context

Returns:The bundle context
get_bundle_id()

Retrieves the bundle ID

Returns:The bundle ID
get_location()

Retrieves the location of this module

Returns:The location of the Pelix module, or an empty string
get_module()

Retrieves the Python module corresponding to the bundle

Returns:The Python module
get_registered_services()

Returns this bundle’s ServiceReference list for all services it has registered or an empty list

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at any time.

Returns:An array of ServiceReference objects
Raises:BundleException – If the bundle has been uninstalled
get_services_in_use()

Returns this bundle’s ServiceReference list for all services it is using or an empty list. A bundle is considered to be using a service if its use count for that service is greater than zero.

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at any time.

Returns:An array of ServiceReference objects
Raises:BundleException – If the bundle has been uninstalled
get_state()

Retrieves the bundle state

Returns:The bundle state
get_symbolic_name()

Retrieves the bundle symbolic name (its Python module name)

Returns:The bundle symbolic name
get_version()

Retrieves the bundle version, using the __version__ or __version_info__ attributes of its module.

Returns:The bundle version, “0.0.0” by default
start()

Starts the bundle. Does nothing if the bundle is already starting or active.

Raises:BundleException – The framework is not yet started or the bundle activator failed.
stop()

Stops the bundle. Does nothing if the bundle is already stopped.

Raises:BundleException – The bundle activator failed.
uninstall()

Uninstalls the bundle

update()

Updates the bundle

ACTIVE = 32

The bundle is now running

INSTALLED = 2

The bundle is installed but not yet resolved

RESOLVED = 4

The bundle is resolved and is able to be started

STARTING = 8

The bundle is in the process of starting

STOPPING = 16

The bundle is in the process of stopping

UNINSTALLED = 1

The bundle is uninstalled and may not be used