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).
- event – The description of the event
(a
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: - bundle_context – This bundle context
- 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
objectRaises: BundleException – The given ID doesn’t exist or is invalid
-
get_framework
()¶ Returns the
Framework
that created this bundle contextReturns: The Framework
object
-
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_objects
(reference)¶ Returns the ServiceObjects object for the service referenced by the specified ServiceReference object.
Parameters: reference – Reference to a prototype service factory Returns: An intermediate object to get more instances of a service
-
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 bundleRaises: 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, factory=False, prototype=False)¶ 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
- factory – If True, the given service is a service factory
- prototype – If True, the given service is a prototype service factory (the factory argument is considered True)
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
-
delete
(force=False)¶ Deletes the current framework
Parameters: force – If True, stops the framework before deleting it Returns: True if the framework has been delete, False if is couldn’t
-
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, factory=False, prototype=False)¶ Registers a service and calls the listeners
Parameters: - bundle – The bundle registering the service
- clazz – Name(s) of the interface(s) implemented by service
- service – The service to register
- properties – Service properties
- send_event – If not, doesn’t trigger a service registered event
- factory – If True, the given service is a service factory
- prototype – If True, the given service is a prototype service factory (the factory argument is considered True)
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