Activation design draft

[Richard Hult]

--=-nex4seGO0aCbNk+mz+fB
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

Hi,

A draft is attached, please comment. Once we've reached consensus, the
different parts can be specified in more detail.

/Richard

-- 
Richard Hult                    richard@imendio.com
Imendio                         http://www.imendio.com

--=-nex4seGO0aCbNk+mz+fB
Content-Disposition: attachment; filename=design-draft.txt
Content-Type: text/plain; name=design-draft.txt; charset=ISO-8859-15
Content-Transfer-Encoding: 7bit

A course-grained design draft for dbus activation.

Activation 
----------

[ This part is already implemented ]

The bus handles the mapping of service names to executables and the
launching of such executables. When receiving an activation request from
a bus client, the bus checks if the service is in its registry of
already running services. 

If the service is not running, the bus checks if there is a pending
activation for the provider of that service already, and if so adds the
request to the activation. Otherwise a new pending activation is created
and a timeout is set up to cancel the activation try if it has not
succeeded after a certain amount of time. The corresponding executable
is spawned asynchronously.

When the executable has started and successfully acquired the service,
the bus replies to any clients that has requested the activation. In
case of failure, an error message is sent to those clients.


Activation context
------------------

Services are activated in the same environment as the bus itself,
meaning for example that services will run with the same locale and
DISPLAY environment variable as the bus.

For services that need to be run in a certain context, for example the
same locale as the activating client, that must be handled outside the
bus, for example with a factory service. A framework for such a service
could be designed and written once and shared between different
applications.


Implicit activation
-------------------

Implicit or automatic activation means that when sending a message to a
service, the client doesn't need to check if the service is already
running and activate it if not. The purpose of implicit activation is to
provide a more convenient API for client writers.

The functionality is implemented as a convenience interface in the
client side library. Sending a message with implicit activation
synchronously is just a matter of first activating the service and then
sending the message if the activation was successful.

For the asynchronous case, the client library needs to send a
nonblocking activation request, and when receiving the async reply, it
sends the message if the activation was successful.


Service providers and service files
-----------------------------------

A service provider is an executable that provides one or more
services. The bus needs to know if a number of services are provided by
the same executable, to avoid a race condition when activating two
services that are provided by the same executable.

The available services are listed in service provider files:

<serviceprovider name="org.mozilla.ServiceProvider">
  <exec>/usr/bin/mozilla</exec>

  <service name="org.mozilla.Browser"/>
  <service name="org.mozilla.HTMLEditor"/>
</serviceprovider>


Querying for services
---------------------

As the bus itself only handles mapping service names to executables,
higher level querying features are left to a layer on top of of the bus
core, implemented as a service.

The query service takes care of mapping properties to service
names. Properties are key/value pairs and an example query might be to
list all services that has the property "implementsInterface" set to the
value "org.freedesktop.MediaPlayer".

[ FIXME: It might be a good idea to standardize a set of such
properties, like "implementsInterface". ]

Properties that are going to be shown in user interfaces need to be made
translatable. In order to handle internationalization without having to
parse a lot of large files filled with strings translated into many
languages, a tool goes through the service files at install time, to
create cache files as follows:

Each service provider has a corresponding service provider file, listing
the services provided, and a number of key/value properties for each
services.

The files are installed, and the tool splits out providers, services and
executable names from all installed and combines them into one file.

The properties are split out according to language and put in files in
subdirectories corresponding to the language code. A service file with
properties translated to Norwegian and Swedish will end up in
<servicefiledir>/sv/ and <servicefiledir>/no/, with the untranslated
version in <servicefiledir>/C/.

When peforming a query, the client specifies the language code to use so
that the query service can return the correct values.

[ FIXME: The exact formats for service/serviceprovider/properties files
need to be specified. ]


Rereading service files
-----------------------

The bus must be able to reread its configuration on the fly, since
clients need to be able to count on the bus to never exit. An example is
the session bus, which should be tied to the session and it should not
be necessary to log out/in to install a program for instance.

Part of this involves checking for new, removed or changed service
files. This is implemented by keeping track of the modified time of the
service files. Before trying to launch an executable to activate a
service, the timestamp of the file is checked. If the file has been
changed, it needs to be reread.

Updated, added or removed property files must also be handled, by the
querying service.


--=-nex4seGO0aCbNk+mz+fB--