source: trunk/third/bonobo-activation/api-docs/architecture.sgml @ 18311

<chapter id="architecture">
<title>Bonobo Activation Architecture</title>

<sect1 id="oaf-daemon">
<title>The Bonobo Activation daemon</title>
<para>
Bonobo Activation is nothing but a daemon implementing a set of 
CORBA interfaces. These CORBA interfaces implement a Name service 
for the set of CORBA servers installed on your system. Basically, 
OAF knows about all the CORBA servers of your system, running or not. 
The OAF daemon will activate those servers if you ask for them.
</para>

<para>
The Bonobo Activation daemon features a powerful query langage which 
allows you to ask for certain services rather than for certain applications.
</para>

<para>
C programmers who wish to access these services do not need to make
raw CORBA calls: they can use a set of convenience functions implemented
in the liboaf library. This library acts as a wrapper on top of the CORBA
server. The API documentation for the liboaf library is available there.
(XXX: add pointer to the API ref).
</para>

</sect1>

<sect1 id="server-arch">
<title>Server architecture</title>

<para>
The OAF server is split in 2 parts: the <classname>ObjectDirectory</classname> which contains the list
of all servers on a given machine, and the <classname>ActivationContext</classname> which contains the
list of all ObjectDirectories. It contains by default the local ObjectDirectory
and you can add inside other distant ObjectDirectories.
</para>

<para>
Each server is described by its .server file which contains among others
the IDL interfaces this server implements, some specific properties and 
an <emphasis>IID</emphasis> (Implementation ID). Each IID has to be unique.
Its format is pretty simple:
<programlisting>
OAFIID:program_name:UUID
</programlisting>
The UUID is supposed to be generated by the <emphasis>uuidgen</emphasis> 
program. <emphasis>program_name</emphasis> has to be an ASCII string without
comma (','), square bracket ('[]'), or forward slash ('/') characters.
</para>

<para>
Each CORBA server on a given machine is thus identified in a unique way.
CORBA servers on different machines are uniquely identified through the 
<emphasis>AID</emphasis> (Activation ID). The AID format is also pretty
simple:
<programlisting>
OAFAID:[IID,user,host,domain]
</programlisting>
<emphasis>user</emphasis> is the user unix login.
<emphasis>host</emphasis> is a DNS domain name or stringified IP
address.
<emphasis>domain</emphasis> is is a string describing what use 
area the object has.
</para>

<para>
One important thing to understand about these AID and IID is that the 
<classname>ObjectDirectory</classname> deals exclusively with IIDs (it is stritcly local) and
the <classname>ActivationContext</classname> deals with AIDs since it can associate a set of
<emphasis>user</emphasis>, <emphasis>host</emphasis> and 
<emphasis>domain</emphasis> to each IID it gets from one of its 
<classname>ObjectDirectory</classname>.
</para>

<para>
As a result of this architecture, activation requests should go to the 
<classname>ActivationContext</classname> and
registrations to the <classname>ObjectDirectory</classname>.
        <figure>
        <title>OAF architecture</title>
        <graphic fileref="oaf.png" scale="50"></graphic>
      </figure>
The idea behind this is that when you make a request on the ActivationContext (like query),
it will:
<itemizedlist>
<listitem><para>make sure it has an up-to-date list of all the Servers with a call to 
<function>ObjectDirectory::get_servers</function> for each of its ObjectDirectory.
</para></listitem>
<listitem><para>loop through this list to try to satisfy the query with the
given requirements and sort-order.
</para></listitem>
<listitem><para>activate the corresponding object with 
<function>ObjectDirectory::activate</function> (this is not exactly what happens 
since there are optimizations to save this call but the general idea is right).
</para></listitem>
</itemizedlist>
</para>

</sect1>

<sect1 id="async-activation">
<title>Async Activation</title>

<para>
OAF also has a set of asynchronous activation interfaces so that you do not need to block
on activation calls. The CORBA level is pretty simple: the activation context has a set of 
<function>_async</function> calls: <function>OAF_ACtivationContext_activate_async</function>
and <function>OAF_ACtivationContext_activate_from_id_async</function>. Both of those calls
take an OAFActivationCallback CORBA object as parameter. This object, which is supposed to 
be implemented by client applications (it is actually implemented in liboaf) will receive
CORBA calls when the activation is finished:
<programlisting>
module OAF {
        interface ActivationCallback {
                oneway void report_activation_failed (in string reason);
                oneway void report_activation_succeeded (in ActivationResult result);
        };
};
</programlisting>
</para>

<para>
Of course, liboaf provides comvenient wrappers for those CORBA functions. Those are named
<function>bonobo_activation_activate_async</function> and 
<function>bonobo_activation_activate_from_id_async</function>.
</para>

</sect1>

</chapter>