XMLBase.hh

/* This file is part of the BIAS library (Basic ImageAlgorithmS).
   
   Copyright (C) 2003-2009    (see file CONTACT for details)
   Multimediale Systeme der Informationsverarbeitung
   Institut fuer Informatik
   Christian-Albrechts-Universitaet Kiel
   
   
   BIAS is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License as published by
   the Free Software Foundation; either version 2.1 of the License, or
   (at your option) any later version.
   
   BIAS is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU Lesser General Public License for more details.
   
   You should have received a copy of the GNU Lesser General Public License
   along with BIAS; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
#ifndef __BIAS_XMLBASE_hh__
#define __BIAS_XMLBASE_hh__

#include "bias_config.h"

#ifndef BIAS_HAVE_XML2
#  error BIAS_HAVE_XML2 required to use XMLIO.hh. Please recompile BIAS with USE_XML2.
#endif

#ifdef BIAS_HAVE_XML2

#include <Base/Common/XMLIO.hh>

namespace BIAS {
  
  /** @class XMLBase
      @ingroup g_utils
      @brief Base class with interface for xml output
      
      All classes with xml i/o support should be derived from this class.
      You can then call XMLWrite to write the object to an XML file or
      XMLAdd(n) to attach the object to a node n of a given xml structure.
      For this to work you must:
      - Override XMLGetTopLevelName such that it returns something identifying
      the class, e.g. "FeaturePoint". XMLAdd and XMLWrite use this function
      to generate the toplevel node of you object.
      - Override XMLFill, such that it fills the XML code of (*this) into a 
      tree, where the top level node is already created
      Given a valid xml file, you can call XMLRead to read the xml file into
      the current object, this calls your specialization of XMLReadObject

      This class is empty if no XML2 support is available.

      @author koeser 08/2004 */
  class BIASCommon_EXPORT XMLBase {

  public:
    virtual ~XMLBase() {}

    /** @brief call this to add the class to a node of a given xml tree 
        @attention interface changed 3/2008: return value now nodeptr of 
                   added node!*/
    xmlNodePtr XMLAdd(const xmlNodePtr Node, XMLIO& XMLObject) const;

    /** @brief call this to add the class to a new xml tree and write it
        to the file Filename. Calls function XMLOut of derived class
        @param CompressionLevel 0..9 (0=off, 9=highest compression) */
    int XMLWrite(const std::string& Filename,
                 int CompressionLevel = 0,
                 bool AutoAddCompressionSuffix = true,
                 std::string encoding="UTF-8") const;

    /** serialize xml tree to string
        @author evers*/
    int XMLWriteToString(std::string &str,
                         std::string encoding="UTF-8") const;

    /** @brief reconstruct xml tree from string
        @author evers*/
    int XMLReadFromString(const std::string& str);
   
    /** @brief derived classes must implement this, so that it returns the name
        of the class for the top level tag in the XML file */
    virtual int XMLGetClassName(std::string& TopLevelTag,
                                double& Version) const = 0;

    /** @brief derived classes must implement this to write the code of (*this)
        into the XML tree. Called by XMLRead of XMLBase.
        @param node always points to a node with a name given by the function
        XMLGetTopLevelName  */
    virtual int XMLOut(const xmlNodePtr Node, XMLIO& XMLObject) const = 0;

    /** @brief derived classes must implement this to read everything in Node
        into (*this). Called by XMLRead of XMLBase.
        @return 0 on success, <0 on error */
    virtual int XMLIn(const xmlNodePtr Node, XMLIO& XMLObject) = 0; 
    
    /** @brief derived classes must implement the function XMLIn which is called by 
     *    this function XMLRead to read everything with name Filename into (*this).
     *  @return 0 on success, <0 on error 
     *  */
    int XMLRead(const std::string& Filename);

  };
 
} // namespace

#endif // BIAS_HAVE_XML2   
#endif // __BIAS_XMLBASE_hh__