<chapter id="tutorial">
<title>Bonobo Activation tutorial</title>

   <sect1>
   <title>What is Bonobo Activation ?</title>

   <para>
   Bonobo Activation (originally named OAF) was designed as a replacement for the limited libgnorba library used
   in older GNOME released. bonobo-activation is responsible on GNOME 2.x systems for
   the activation of CORBA objects. bonobo-activation allows you to browse the available
   CORBA servers on your system (running or not). It keeps track of the running 
   servers so that if you ask for a server which is already running, you will not
   start it again but will reuse the already running one.
   </para>

   <sect2>
   <title>The need for a replacement</title>
   <para>
      Gnorba works well in a limited number of cases and suffers of a 
      number of design issues. More specifically:

      <itemizedlist>

      <listitem>
      <para>
      It cannot handle the non-local case gracefully. ie: you cannot start 
      a remote CORBA server with bonobo-activation.
      </para>
      </listitem>

      <listitem>
      <para>
      It uses <emphasis>evil</emphasis> hacks to keep track of the system's CosNaming 
      service making it unusable on systems where an X server is not running.
      (for details, read bonobo-activation code ;-)
      </para>      
      </listitem>

      <listitem>
      <para>
      bonobo-activation allows you to only request specific servers by their name: you cannot ask
      for a server which provides a specific service. You have to ask for a server which 
      you know provides a specific service.
      </para>      
      </listitem>

      </itemizedlist>
      </para>

      <para>
      Bonobo Activation was designed to address these issues. The remote issue is completely solved
      by the Bonobo Activation daemon (see <xref linkend="architecture"/>), the evil hacks regarding X are
      part of our past and the grand <emphasis>OAF query langage</emphasis> (see 
      <xref linkend="query-langage"/>) gives you the ability to perform arbitrary queries
      on the database of CORBA servers.
      </para>

      <para>
      Basically, Bonobo Activation keeps track of all the CORBA servers installed on your machine and
      can track any other machine's CORBA servers provided you set up Bonobo Activation correctly and 
      allows you to perform queries on the properties of these servers.
      The following very simple example will make things rather clear:

      <programlisting>
CORBA_Object o = bonobo_activation_activate ("repo_ids.has ('IDL:GNOME/Graph/Layout:1.0')",
                                             NULL, 0, NULL, &amp;ev);
      </programlisting>

      This will ask for a component which supports the GNOME/Graph/Layout:1.0 interface.
      You can also do much more complicated things. Bonobo Activation will find one whcih matches the 
      query and will take all the necessary measures required to get the server running
      (if it is a shared library progam, it will load the relevant library in memory.
      If you need a Factory, it will launch the factory and request the factory to create
      the relevant object).

      </para>

      </sect2>

      <sect2>
      <title>Getting started</title>

      <para>
      Here follows a very simple-stupid example of what you can do with Bonobo Activation.
      The complete API description of bonobo activation, the Bonobo Activation query langage reference and the
      <filename>.server</filename> file format reference are included in this 
      document and are recommended readings. Reading <xref linkend="architecture"/> is
      also a good idea.
      </para>  

      </sect2>

   </sect1>

   <sect1 id="checklist">
   <title>Checklist</title>

   <para>
   If you plan to use Bonobo Activation for your own CORBA servers, you should use the following simple 
   checklist.
   <itemizedlist>

   <listitem>
   <para>
   Create a unique UUID for your CORBA server by using libuuid and uuidgen
   (both are available by anonymous ftp from tsx-11.mit.edu in 
   <filename>/pub/linux/packages/ext2fs</filename>. These are part of the 
   <filename>e2fsprogs</filename> package.
   </para>
   </listitem>

   <listitem>
   <para>
   Create a proper <filename>.server</filename> file for your server describing its
   IDL interfaces, its main properties and the way it is to be activated.
   </para>
   </listitem>

   <listitem>
   <para>
   Call <function>bonobo_activation_init</function> (make sure you do not initialize twice by calling 
   <function>bonobo_activation_is_initialized</function>). Then, call
   <function>bonobo_activation_active_server_register</function>
   to register yourself as running to the Bonobo Activation daemon.
   </para>
   </listitem>

   </itemizedlist>

   If you are a client willing to activate a few servers, it is a little simpler: you 
   just must make sure you call the <function>bonobo_activation_init</function> function and you can then
   call <function>bonobo_activation_query</function> or <function>bonobo_activation_activate</function> or 
   <function>bonobo_activation_activate_from_id</function>.
   </para>

   <para>
   Here, put a real-life example of a client and a server.
   </para>


   <sect2>
   <title>The non-local case</title>
   <para>
   Here, present how to use setup the system for the non-local case.
   If anyone is willing to write this part, mail gnome-components-list@gnome.org.
   in the meantime, you can have a look at the code in gnome-libs HEAD from cvs.
   (I never had time to go look at it)
   </para>
   </sect2>

   </sect1>

</chapter>
