library: libXMLIO #include "TXMLFile.h"

# TXMLFile

class description - source file - inheritance tree (.pdf)

## class TXMLFile : public TFile, public TXMLSetup

| Inheritance Chart:
`TObject`
| <- | `TNamed`
| <- | `TDirectory`
| <- | `TFile`
`TXMLSetup`
| <- | `TXMLFile` |

        private:

          void operator=(const TXMLFile&)

        protected:

                      void InitXmlFile(Bool_t create)
               static void ProduceFileNames(const char* filename, TString& fname, TString& dtdname)
                    Bool_t ReadFromFile()
                      void ReadStreamerElement(xmlNodePointer node, TStreamerInfo* info)
                      void SaveToFile()
                      void StoreStreamerElement(xmlNodePointer node, TStreamerElement* elem)
             virtual Int_t SysClose(Int_t)
             virtual Int_t SysOpen(const char*, Int_t, UInt_t)
             virtual Int_t SysRead(Int_t, void*, Int_t)
          virtual Long64_t SysSeek(Int_t, Long64_t, Int_t)
             virtual Int_t SysStat(Int_t, Long_t*, Long64_t*, Long_t*, Long_t*)
             virtual Int_t SysSync(Int_t)
             virtual Int_t SysWrite(Int_t, const void*, Int_t)

        public:

                           TXMLFile()
                           TXMLFile(const char* filename, Option_t* option = "read", const char* title = "title", Int_t compression = 1)
                   virtual ~TXMLFile()
            static TClass* Class()
              virtual void Close(Option_t* option = "")
              virtual void DrawMap(const char* = "*", Option_t* = "")
              virtual void FillBuffer(char*&)
              virtual void Flush()
          virtual Long64_t GetEND() const
             virtual Int_t GetErrno() const
             virtual Int_t GetNbytesFree() const
             virtual Int_t GetNbytesInfo() const
             virtual Int_t GetNfree() const
          virtual Long64_t GetSeekFree() const
          virtual Long64_t GetSeekInfo() const
          virtual Long64_t GetSize() const
            virtual TList* GetStreamerInfoList()
           virtual TClass* IsA() const
            virtual Bool_t IsOpen() const
              virtual void MakeFree(Long64_t, Long64_t)
              virtual void MakeProject(const char*, const char* = "*", Option_t* = "new")
              virtual void Map()
              virtual void Paint(Option_t* = "")
              virtual void Print(Option_t* = "") const
            virtual Bool_t ReadBuffer(char*, Int_t)
              virtual void ReadFree()
              virtual void ReadStreamerInfo()
             virtual Int_t Recover()
             virtual Int_t ReOpen(Option_t* mode)
              virtual void ResetErrno() const
              virtual void Seek(Long64_t, TFile::ERelativeTo = kBeg)
              virtual void SetEND(Long64_t)
              virtual void SetStoreStreamerInfos(Bool_t iConvert = kTRUE)
              virtual void SetUsedDtd(Bool_t use = kTRUE)
              virtual void SetUseNamespaces(Bool_t iUseNamespaces = kTRUE)
              virtual void SetXmlLayout(TXMLSetup::EXMLLayout layout)
              virtual void ShowMembers(TMemberInspector& insp, char* parent)
             virtual Int_t Sizeof() const
              virtual void Streamer(TBuffer& b)
                      void StreamerNVirtual(TBuffer& b)
              virtual void UseCache(Int_t = 10, Int_t = TCache::kDfltPageSize)
             virtual Int_t Write(const char* = "0", Int_t = 0, Int_t = 0)
             virtual Int_t Write(const char* = "0", Int_t = 0, Int_t = 0) const
            virtual Bool_t WriteBuffer(const char*, Int_t)
              virtual void WriteFree()
              virtual void WriteHeader()
             virtual Int_t WriteObjectAny(const void* obj, const char* classname, const char* name, Option_t* option = "")
             virtual Int_t WriteObjectAny(const void* obj, const TClass* cl, const char* name, Option_t* option = "")
              virtual void WriteStreamerInfo()
             virtual Int_t WriteTObject(const TObject* obj, const char* name = "0", Option_t* option = "")
               TXMLEngine* XML()

### Data Members

        protected:

           xmlDocPointer fDoc               !
          xmlNodePointer fStreamerInfoNode  !  pointer of node with streamer info data
             TXMLEngine* fXML               ! object for interface with xml library

## Class Description

     The main motivation for the XML  format is to facilitate the
     communication with other non ROOT applications. Currently
     writing and reading XML files is limited to ROOT applications.
     It is our intention to develop a simple reader independent
     of the ROOT libraries that could be used as an example for
     real applications. One of possible approach with code generation
     is implemented in TXMLPlayer class.

     The XML format should be used only for small data volumes,
     typically histogram files, pictures, geometries, calibrations.
     The XML file is built in memory before being dumped to disk.

     Like for normal ROOT files, XML files use the same I/O mechanism
     exploiting the ROOT/CINT dictionary. Any class having a dictionary
     can be saved in XML format.

     This first implementation does not support subdirectories
     or Trees.

     The shared library libRXML.so may be loaded dynamically
     via gSystem->Load("libRXML"). This library is automatically
     loaded by the plugin manager as soon as a XML file is created
     via, eg
       TFile::Open("file.xml","recreate");
     TFile::Open returns a TXMLFile object. When a XML file is open in write mode,
     one can use the normal TObject::Write to write an object in the file.
     Alternatively one can use the new functions TDirectory::WriteObject and
     TDirectory::WriteObjectAny to write a TObject* or any class not deriving
     from TObject.

     example of a session saving a histogram to a XML file
     =====================================================
       TFile *f = TFile::Open("Example.xml","recreate");
       TH1F *h = new TH1F("h","test",1000,-2,2);
       h->FillRandom("gaus");
       h->Write();
       delete f;

     example of a session reading the histogram from the file
     ========================================================
       TFile *f = TFile::Open("Example.xml");
       TH1F *h = (TH1F*)f->Get("h");
       h->Draw();

     A new option in the canvas "File" menu is available to save
     a TCanvas as a XML file. One can also do
       canvas->Print("Example.xml");

     Configuring ROOT with the option "xml"
     ======================================
     The XML package is enabled by default

     documentation
     =============
     The "xml" package is currently under development. A more complete
     documentation will be provided shortly in the classes reference guide.
     See classes TXMLFile, TKeyXML, TBufferXML, TXMLEngine, TXMLSetup
     and TXMLPlayer.
     An example of XML file corresponding to the small example below
    can be found at http://root.cern.ch/root/Example.xml

    ______________________________________________________________________________

TXMLFile() : TFile(), TXMLSetup(), fDoc(0), fStreamerInfoNode(0), fXML(0)

     default TXMLFile constructor

TXMLFile(const char* filename, Option_t* option, const char* title, Int_t compression) : TFile(), TXMLSetup(), fDoc(0), fStreamerInfoNode(0)

     Open or creates local XML file with name filename.
     It is recommended to specify filename as "<file>.xml". The suffix ".xml"
     will be used by object browsers to automatically identify the file as
     a XML file. If the constructor fails in any way IsZombie() will
     return true. Use IsOpen() to check if the file is (still) open.

     If option = NEW or CREATE   create a new file and open it for writing,
                                 if the file already exists the file is
                                 not opened.
               = RECREATE        create a new file, if the file already
                                 exists it will be overwritten.
               = 2xoo            create a new file with specified xml settings
                                 for more details see TXMLSetup class
               = UPDATE          open an existing file for writing.
                                 if no file exists, it is created.
               = READ            open an existing file for reading.

     For more details see comments for TFile::TFile() constructor

     For a moment TXMLFile does not support TTree objects and subdirectories

void InitXmlFile(Bool_t create)

     initialize xml file and correspondent structures
     identical to TFile::Init() function

void Close(Option_t *option)

     Close a XML file
     For more comments see TFile::Close() function

~TXMLFile()

     destructor of TXMLFile object

Bool_t IsOpen() const

     return kTRUE if file is opened and can be accessed

Int_t ReOpen(Option_t* mode)

     Reopen a file with a different access mode, like from READ to
     See TFile::Open() for details

Int_t WriteTObject(const TObject* obj, const char* name, Option_t* option)

     write object, derived from TObject class, to file

Int_t WriteObjectAny(const void *obj, const char *classname, const char *name, Option_t *option)

     Write object of class classname in this directory
     obj may not derive from TObject
     see TDirectory::WriteObject for comments

Int_t WriteObjectAny(const void* obj, const TClass* cl, const char* name, Option_t* option)

     write object of any class with disctionary to xml file
     object is tranformed to xml structure, which then kept in TKeyXML
     Data will be stored to file only when Close() or ReOpen() or destructor is called
     For more details see TDirectory::WriteObjectAny() function

void ProduceFileNames(const char* filename, TString& fname, TString& dtdname)

     function produces pair of xml and dtd file names

void SaveToFile()

     Saves xml structures to file
     xml elements are kept in list of TKeyXML objects
     When saving, all this elements are linked to root xml node
     In the end StreamerInfo structures are added
     After xml document is saved, all nodes will be unlinked from root node
     and kept in memory.
     Only Close() or destructor relase memory, used by xml structures

Bool_t ReadFromFile()

     read document from file
     Now full content of docuument reads into the memory
     Then document decomposed to separate keys and streamer info structures
     All inrelevant data will be cleaned

void WriteStreamerInfo()

     convert all TStreamerInfo, used in file, to xml format

TList* GetStreamerInfoList()

     Read streamerinfo structures from xml format and provide them in the list
     It is user responsibility to destroy this list

void ReadStreamerInfo()

     Read the list of StreamerInfo from this file
     The corresponding TClass objects are updated.

void StoreStreamerElement(xmlNodePointer infonode, TStreamerElement* elem)

     store data of single TStreamerElement in streamer node

void ReadStreamerElement(xmlNodePointer node, TStreamerInfo* info)

     read and reconstruct single TStreamerElement from xml node

void SetXmlLayout(EXMLLayout layout)

     Change layout of objects in xml file
     Can be changed only for newly created file.

     Currently there are two supported layouts:

     TXMLSetup::kSpecialized = 2
        This is default layout of the file, when xml nodes names class names and data member
        names are used. For instance:
              <TAttLine version="1">
                <fLineColor v="1"/>
                <fLineStyle v="1"/>
                <fLineWidth v="1"/>
              </TAttLine>

     TXMLSetup::kGeneralized = 3
        For this layout all nodes name does not depend from class definitions.
        The same class looks like
              <Class name="TAttLine" version="1">
                <Member name="fLineColor" v="1"/>
                <Member name="fLineStyle" v="1"/>
                <Member name="fLineWidth" v="1"/>
              </Member>

void SetStoreStreamerInfos(Bool_t iConvert)

     If true, all correspondent to file TStreamerInfo objects will be stored in file
     this allows to apply schema avolution later for this file
     may be usefull, when file used outside ROOT and TStreamerInfo objects does not required
     Can be changed only for newly created file.

void SetUsedDtd(Bool_t use)

     Specify usage of DTD for this file.
     Currently this option not avaliable (always false).
     Can be changed only for newly created file.

void SetUseNamespaces(Bool_t iUseNamespaces)

     Specifiy usage of namespaces in xml file
     In current implementation every instrumented class in file gets its unique namespace,
     which is equal to name of class and refer to root documentation page like
     <TAttPad xmlns:TAttPad="http://root.cern.ch/root/htmldoc/TAttPad.html" version="3">
     And xml node for class member gets its name as combination of class name and member name
                <TAttPad:fLeftMargin v="0.100000"/>
                <TAttPad:fRightMargin v="0.100000"/>
                <TAttPad:fBottomMargin v="0.100000"/>
                and so on
     Usage of namespace increase size of xml file, but makes file more readable
     and allows to produce DTD in the case, when in several classes data member has same name
     Can be changed only for newly created file.

### Inline Functions

                  Int_t SysOpen(const char*, Int_t, UInt_t)
                  Int_t SysClose(Int_t)
                  Int_t SysRead(Int_t, void*, Int_t)
                  Int_t SysWrite(Int_t, const void*, Int_t)
               Long64_t SysSeek(Int_t, Long64_t, Int_t)
                  Int_t SysStat(Int_t, Long_t*, Long64_t*, Long_t*, Long_t*)
                  Int_t SysSync(Int_t)
                   void operator=(const TXMLFile&)
                   void DrawMap(const char* = "*", Option_t* = "")
                   void FillBuffer(char*&)
                   void Flush()
               Long64_t GetEND() const
                  Int_t GetErrno() const
                   void ResetErrno() const
                  Int_t GetNfree() const
                  Int_t GetNbytesInfo() const
                  Int_t GetNbytesFree() const
               Long64_t GetSeekFree() const
               Long64_t GetSeekInfo() const
               Long64_t GetSize() const
                   void MakeFree(Long64_t, Long64_t)
                   void MakeProject(const char*, const char* = "*", Option_t* = "new")
                   void Map()
                   void Paint(Option_t* = "")
                   void Print(Option_t* = "") const
                 Bool_t ReadBuffer(char*, Int_t)
                   void ReadFree()
                  Int_t Recover()
                   void Seek(Long64_t, TFile::ERelativeTo = kBeg)
                   void SetEND(Long64_t)
                  Int_t Sizeof() const
                   void UseCache(Int_t = 10, Int_t = TCache::kDfltPageSize)
                 Bool_t WriteBuffer(const char*, Int_t)
                  Int_t Write(const char* = "0", Int_t = 0, Int_t = 0)
                  Int_t Write(const char* = "0", Int_t = 0, Int_t = 0) const
                   void WriteFree()
                   void WriteHeader()
            TXMLEngine* XML()
                TClass* Class()
                TClass* IsA() const
                   void ShowMembers(TMemberInspector& insp, char* parent)
                   void Streamer(TBuffer& b)
                   void StreamerNVirtual(TBuffer& b)

Author: Sergey Linev, Rene Brun 10.05.2004
Last update: root/xml:$Name: $:$Id: TXMLFile.cxx,v 1.11 2005/05/06 14:25:34 brun Exp $
Copyright (C) 1995-2004, Rene Brun and Fons Rademakers. *