source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Detector/persistency.xml @ 905

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Changed by: Katsuya Amako,  4-Aug-1998                -->
<!--    Changed by: Dennis Wright, 27-Nov-2001                -->
<!--    Proof read by: Joe Chuma,  30-Jun-1999                -->
<!--                                                          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.ObjPers">
<title>
Object Persistency
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ObjPers.PersG4">
<title>
Persistency in Geant4
</title>

<para>
Object persistency is provided by Geant4 as an optional category,
so that the user may run Geant4 with or without an object database
management system (ODBMS).
</para>

<para>
When a usual (transient) object is created in C++, the object is
placed onto the application heap and it ceases to exist when the
application terminates. Persistent objects, on the other hand, live
beyond the termination of the application process and may then be
accessed by other processes (in some cases, by processes on other
machines).

<figure id="fig.ObjPers_1">
<title>
Persistent object.
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/Detector/persistency.src/pobject.gif" 
               format="JPG" contentwidth="7.0cm" align="center" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/Detector/persistency.src/pobject.gif" 
               format="JPG" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
C++ does not have, as an intrinsic part of the language, the
ability to store and retrieve persistent objects. Geant4 provides
an abstract framework for persistency of hits, digits and
events.
</para>

<para>
Two examples demonstrating an implementation of object
persistency using one of the tools accessible through the available
interface, is provided in
<literal>examples/extended/persistency</literal>.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ObjPers.Reflex">
<title>
Using Reflex for persistency of Geant4 objects
</title>

<para>
Object persistency of Geant4 objects is also possible by the
mean of the <ulink url="http://cern.ch/seal-reflex/">
Reflex library</ulink>. 
Reflex provides, in a non-intrusive way, reflection capabilities to C++
classes by generating "dictionary information" for them. Those
dictionaries can then be loaded in memory allowing direct
persistency of the given objects without any instrumentation of the
code. The Reflex library is also part of 
<ulink url="http://root.cern.ch/">
ROOT</ulink> (since release <literal>v5.08</literal>).
</para>

<para>
The basic steps that one needs to do in order to use Reflex with
ROOT I/O for arbitrary C++ classes is:

<orderedlist spacing="compact">
  <listitem><para>
    Generate the dictionary for the given classes using the
    <literal>genreflex</literal> tool from ROOT (this usually is done by adding
    the appropriate command to the makefile)
  </para></listitem>
  <listitem><para>
    Add initialization of ROOT I/O and loading of the generated
    dictionary for the given classes in the appropriate part of the
    code
  </para></listitem>
  <listitem><para>
    Whenever the objects to be persistified are available, call the
    <literal>WriteObject</literal> method of <literal>TFile</literal> with 
    the pointer to the appropriate object as argument (usually it is some sort 
    of container, like <literal>std::vector</literal> containing the collection 
    of objects to be persistified)
  </para></listitem>
</orderedlist>
</para>

<para>
The two examples (<literal>P01</literal> and <literal>P02</literal>) provided
in <literal>examples/extended/persistency</literal>
demonstrate how to perform object persistency using the
Reflex mechanism in ROOT I/O for storing hits and geometry description.
</para>


</sect2>
</sect1>