Skip to content

Commit

Permalink
Added a word about Service Factories in doc
Browse files Browse the repository at this point in the history
  • Loading branch information
tcalmant committed Jun 8, 2017
1 parent 3c4a17f commit e0ef9c0
Showing 1 changed file with 45 additions and 0 deletions.
45 changes: 45 additions & 0 deletions docs/refcards/services.rst
Expand Up @@ -43,6 +43,51 @@ Name Type Description
service.ranking int The rank/priority of the service. The lower the rank, the more priority
=============== ==== ===========================================================

.. _service_factory:

Service Factory
---------------

A service factory is a pseudo-service with a specific flag, which can create
individual instances of service objects for different bundles.
Sometimes a service needs to be differently configured depending on which
bundle uses the service.
For example, the log service needs to be able to print the logging bundle's id,
otherwise the log would be hard to read.

A service factory is registered in exactly the same way as a normal service,
using :meth:`~pelix.framework.BundleContext.register_service`, with the
``factory`` set to True``.
The only difference is an indirection step before the actual service object is
handed out.

The client using the service need not, and should not, care if a service is
generated by a factory or by a plain object.

A simple service factory example

.. code-block:: python
class LongFactory:
def get_service(self, bundle, registration):
"""
Called each time a new bundle requires the service
"""
return bundle.get_bundle_id()
def unget_service(self, bundle, registration):
"""
Called when a bundle has released all its references
to the service
"""
# Release connections, ...
pass
bundle_context.register_service("long", LongFactory(), {}, factory=True)
.. note:: The framework will cache generated service objects.
Thus, at most one service can be generated per client bundle.

API
---

Expand Down

0 comments on commit e0ef9c0

Please sign in to comment.