source: Sophya/trunk/SophyaProg/Examples/MyPPF/README@ 3721

Example to illustrate how to make a class persistent
using SOPHYA PPF services 
-----------------------------------------------
   (C) LAL-IN2P3/CNRS   (C) DAPNIA-SPP/CEA 
               R. Ansari , 2007 
-----------------------------------------------

0/ Content : 
   - vfs.h : Declaration of the Vfs class Vfs . This is the class 
             which we want to make persistent using SOPHYA PPF services
   - vfs.cc : the Vfs class implementation AND its PPF handler ObjFileIO<Vfs>
   - tvfs.cc : the test main program
   - makefile : compiles tvfs.cc and vfs.cc and links them to build tvfs


1/ The class should inherit from the SOPHYA::AnyDataObj class. 
   In the example here, we want to make the class Vfs persistent
class Vfs : public SOPHYA::AnyDataObj {
 ... 
}

2/ A PPF handler should be implemented . The PPF handler class 
should inherit from SOPHYA::PPersist . The pure virtual methods 
of PPersist class (DataObj() , SetDataObj() , ReadSelf(), WriteSelf()
has to be implemented. 

class PPFHandlerVfs : public SOPHYA::PPersist {
public:
  virtual SOPHYA::AnyDataObj* DataObj();
  virtual void       SetDataObj(SOPHYA::AnyDataObj &);
protected: 
  virtual void       ReadSelf(SOPHYA::PInPersist&);
  virtual void       WriteSelf(SOPHYA::POutPersist&) const;
}


It is possible to use the template class SOPHYA::ObjFileIO<T>, and 
specialize it for the tharget class (here SOPHYA::ObjFileIO<Vfs>), 
by defining the two methods :
  SOPHYA::ObjFileIO<Vfs>::ReadSelf(SOPHYA::PInPersist&)
  SOPHYA::ObjFileIO<Vfs>::WriteSelf(SOPHYA::POutPersist&) const

3/ If it is NOT possible to have the target class inherit from AnyDataObj, 
a wrapper class should be used. The same class can play the role of wrapper
AND the PPF handler. 
  (See the PPF handler / wrapper class for STL vectors :
   SOPHYA::PPFWrapperSTLVector<T> in file BaseTools/ppfwrapstlv.h )


4/ Implement the ReadSelf() and WriteSelf() methods of the PPF handler.
All the I/O services from the following classes can be used : 
  - PPFBinaryIOStrem , PPFBinaryInputStream , PInPersist
  - PPFBinaryIOStrem , PPFBinaryOutputStream , POutPersist
Writing and reading of the embeded objects for which a handler has been registered 
can simply be performed by : 
  POutPersist::PutObject()   PInPersist::GetObject()

==> The services associated with nametags (PPFBinaryOutputStream::WriteNameTag() 
    PPFBinaryInputStream::GotoNameTag() ... ) are NOT intented to be used in 
    WriteSelf() , ReadSelf()


5/ The new PPF handler, as well as the list of classes it can handle has to be
registered prior to use PPF read/write for the target classes. This must be 
performed during the initialization phase, for example at the beginning of the 
main() program. Another possibility is to use a module initializer 
(See SophyaInitiator class in file BaseTools/sophyainit.h ) 
and declare a static instance of the class (Note that this works only if 
the system loader handles correcly the call of constructor 
for the statically declared objects)

The registration can be performed using the CPP macros defined in BaseTools/ppersist.h

  // First, register the PPF handler ObjFileIO<Vfs> 
  PPRegister(ObjFileIO<Vfs>);
  // Register the list of classes which can be handled by ObjFileIO<Vfs> 
  DObjRegister(ObjFileIO<Vfs>, Vfs);