include/EDoc/PersistenceIFace.h

Go to the documentation of this file.

/*******************************************************************************

   Copyright (C) 2007 by Brendon Costa

   This library is free software; you can redistribute it and/or modify 
   it under the terms of the "LGPL Like" License defined in the file COPYING 
   that should have been distributed along with this source.

   This library 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.  

   You should have received a copy of the "LGPL Like" License 
   along with this library; see the file COPYING. if not, it can be 
   obtained from the EDoc++ website: 
   http://edoc.sourceforge.net/license.html

*******************************************************************************/
#ifndef EDOC_PERSISTENCEIFACE_H
#define EDOC_PERSISTENCEIFACE_H

#include "EDoc/stdint.h"
#include <string>

namespace EDoc
{
   //===========================================================================
   /** \brief Defines an interface for reading/writing various types of
    * primitive data.
    *
    * This interface defines primitives for reading/writing certain integer and
    * string types to/from files. Each primitive has an associated key which
    * it is necessary for the user to provide but may not necessarily be used by
    * the underlying implementation. For example the text implementation of this
    * interface will validate the key and the data type are correct, whereas the
    * binary interface will just assume that the data it is reading is correct.
    */
   class PersistenceIFace
   {
   public:

      //------------------------------------------------------------------------
      /** \brief Constructor.
       */
      PersistenceIFace() :
         ref_count(0)
      {}

      //------------------------------------------------------------------------
      /** \brief Destructor.
       */
      virtual ~PersistenceIFace() {}


      //------------------------------------------------------------------------
      /** \brief Open the file associated with this instance preparing it for
       * reading or writing.
       */
      virtual void Open() = 0;

      //------------------------------------------------------------------------
      /** \brief Close the file associated with this instance. 
       */
      virtual void Close() = 0;

      //------------------------------------------------------------------------
      /** \brief Read a string primitive. 
       */
      virtual std::string ReadString(const char* key) = 0;

      //------------------------------------------------------------------------
      /** \brief Read a boolean primitive. 
       */
      virtual bool ReadBoolean(const char* key) = 0;

      //------------------------------------------------------------------------
      /** \brief Read a uint8_t primitive. 
       */
      virtual uint8_t ReadUInt8(const char* key) = 0;

      //------------------------------------------------------------------------
      /** \brief Read a int32_t primitive. 
       */
      virtual int32_t ReadInt32(const char* key) = 0;

      //------------------------------------------------------------------------
      /** \brief Read a uint32_t primitive. 
       */
      virtual uint32_t ReadUInt32(const char* key) = 0;

      //------------------------------------------------------------------------
      /** \brief Read a record type primitive. 
       */
      virtual uint8_t ReadRecordType() = 0;



      //------------------------------------------------------------------------
      /** \brief Write a string primitive. 
       */
      virtual void WriteString(const char* key, std::string value) = 0;

      //------------------------------------------------------------------------
      /** \brief Write a boolean primitive. 
       */
      virtual void WriteBoolean(const char* key, bool value) = 0;

      //------------------------------------------------------------------------
      /** \brief Write a uint8_t primitive. 
       */
      virtual void WriteUInt8(const char* key, uint8_t value) = 0;

      //------------------------------------------------------------------------
      /** \brief Write a int32_t primitive. 
       */
      virtual void WriteInt32(const char* key, int32_t value) = 0;

      //------------------------------------------------------------------------
      /** \brief Write a uint32_t primitive. 
       */
      virtual void WriteUInt32(const char* key, uint32_t value) = 0;

      //------------------------------------------------------------------------
      /** \brief Write a uint32_t primitive with additional debug string.
       *
       * The debug string is a small string that can be written to text files
       * to help the user understand what the uint32_t value might represent or
       * be an index for. This is entirely for debugging purposes and is not
       * accessible with the associated read interface.
       */
      virtual void WriteUInt32Debug(const char* key, uint32_t value, 
         std::string debug_text) = 0;

      //------------------------------------------------------------------------
      /** \brief Write a int32_t primitive with additional debug string.
       *
       * The debug string is a small string that can be written to text files
       * to help the user understand what the uint32_t value might represent or
       * be an index for. This is entirely for debugging purposes and is not
       * accessible with the associated read interface.
       */
      virtual void WriteInt32Debug(const char* key, int32_t value, 
         std::string debug_text) = 0;

      //------------------------------------------------------------------------
      /** \brief Writes a primitive to the file indicating the type of record
       * data that follows.
       */
      virtual void WriteRecordType(uint8_t value) = 0;


      //------------------------------------------------------------------------
      // Data used by Persistence class.
      //------------------------------------------------------------------------
      /** \brief Is a integer that can be used for reference counting.
       *
       * The Persistence class shares instances of PersistenceIFace
       * implementations. To enable this we use a small "hacked" shared pointer
       * which will allow this class to be reference counted.
       */
      int ref_count;

      //------------------------------------------------------------------------
   };
   //===========================================================================

}


#endif // EDOC_PERSISTENCEIFACE_H

---