include/EDoc/Persistence.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_PERSISTENCE_H
#define EDOC_PERSISTENCE_H

#include "EDoc/PersistenceIFace.h"
#include "EDoc/ManagedFile.h"

#include <vector>
#include <list>
#include <string>

namespace EDoc
{
   class ArchiveIFace;
   
   //===========================================================================
   /** \brief Manages automatic switching between TextPersistence and
    * BinaryPersistence as necessary.
    *
    * EDocPersistence is a class that derives from persistence IFace that
    * constructs appropiate text/binary persistence layer and also manages the
    * lifetime of temporary files as necessary.
    *
    * When compiled with GPL lisensing enabled this will also extract a number
    * of temporary files from a BFD file object if there are multiple .edc files
    * embedded into it.
    */
   class Persistence : public PersistenceIFace
   {
   public:

      //------------------------------------------------------------------------
      /** \brief Type representing what format (Text/Binary) the .edc file is
       * encoded in.
       */
      enum EncodingType
      {
         UNKNOWN = 0,
         TEXT,
         BINARY
      };
      
      //------------------------------------------------------------------------
      /** \brief List of all currently open temporary files.
       *
       * This static list is used for claning up temporary files at program exit
       * regardless of exiting due to signal interruption or for normal exit.
       */
      static std::list<std::string> temp_files;

      //------------------------------------------------------------------------
      /** \brief Adds a new temporary file to the temp_files list.
       */
      static void AddTempFile(std::string filename);

      //------------------------------------------------------------------------
      /** \brief Adds a temporary file from the temp_files list after it has
       * been deleted.
       *
       * For atomicity you should only call this AFTER the temp file has been
       * unlinked.
       */
      static void RemoveTempFile(std::string filename);





      //------------------------------------------------------------------------
      /** \brief Adds new archive format that can be used for reading/writing.
       */
      static void AddArchiveFactory(ArchiveIFace* factory);



      //------------------------------------------------------------------------
      /** \brief Will extract a list of managed files from a given file if it 
       * is a known archive type.
       *
       * If it is not a known archive type then will return an empty list.
       */
      static std::list<ManagedFile> ReadExtract(ManagedFile filename);

      //------------------------------------------------------------------------
      /** \brief Opens the given file for reading from.
       *
       * If filename is an archive file, then this may extract more than one
       * .edc file from it. This will automatically determine if the file 
       * being read is an archive, and when opening the .edc files will
       * automatically determine if it is opening a binary or text edc file.
       */
      static std::list<Persistence> ReadOpen(std::string filename);

      //------------------------------------------------------------------------
      /** \brief Opens the given file for writing to.
       *
       * If filename references a file that already exists this will first check
       * to see  if it is a known archive type, in which case it will insert a
       * new edc file into that archive. Otherwise if the file exists but is not
       * a valid known archive type, then this will overwrite the existing file.
       *
       * \param filename The name of the file or archive to write to.
       *
       * \param format The .edc file format type to use for writing the edc
       * file. One of TEXT or BINARY.
       *
       * \param item_name If filename is an archive this can optionally be a
       * name to give the .edc file within that archive. By default EDoc will
       * use the name default.edc
       *
       * Note: Some archive formats will not ADD the edc file to the archive but
       * effectivly overwrite all existing .edc files in the archive with this
       * new .edc file. This si what the BFd implementation currently does.
       */
      static Persistence WriteOpen(std::string filename,
         EncodingType format = TEXT, std::string item_name="default.edc");

      //------------------------------------------------------------------------
      /** \brief Returns a representation of the name of the file being used.
       *
       * This is a string to will indicate the source AND work files if they
       * differ.
       */
      std::string GetFilenameRep() const;

      //------------------------------------------------------------------------
      /** \brief Destructor.
       *
       * Will delete any open temporary files.
       */
      virtual ~Persistence();

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::Open()
       */
      virtual void Open()
      {return impl->Open();}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::Close()
       */
      virtual void Close()
      {return impl->Close();}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadString()
       */
      virtual std::string ReadString(const char* key) 
      {return impl->ReadString(key);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadBoolean()
       */
      virtual bool ReadBoolean(const char* key)  
      {return impl->ReadBoolean(key);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadUInt8()
       */
      virtual uint8_t ReadUInt8(const char* key)  
      {return impl->ReadUInt8(key);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadInt32()
       */
      virtual int32_t ReadInt32(const char* key)  
      {return impl->ReadInt32(key);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadUInt32()
       */
      virtual uint32_t ReadUInt32(const char* key)  
      {return impl->ReadUInt32(key);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::ReadRecordType()
       */
      virtual uint8_t ReadRecordType()  
      {return impl->ReadRecordType();}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteString()
       */
      virtual void WriteString(const char* key, std::string value)  
      {return impl->WriteString(key, value);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteBoolean()
       */
      virtual void WriteBoolean(const char* key, bool value)  
      {return impl->WriteBoolean(key, value);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteUInt8()
       */
      virtual void WriteUInt8(const char* key, uint8_t value)  
      {return impl->WriteUInt8(key, value);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteInt32()
       */
      virtual void WriteInt32(const char* key, int32_t value)  
      {return impl->WriteInt32(key, value);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteUInt32()
       */
      virtual void WriteUInt32(const char* key, uint32_t value)  
      {return impl->WriteUInt32(key, value);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteUInt32Debug()
       */
      virtual void WriteUInt32Debug(const char* key, uint32_t value, 
         std::string debug_text)  
      {return impl->WriteUInt32Debug(key, value, debug_text);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteInt32Debug()
       */
      virtual void WriteInt32Debug(const char* key, int32_t value, 
         std::string debug_text) 
      {return impl->WriteInt32Debug(key, value, debug_text);}

      //------------------------------------------------------------------------
      /** \brief See PersistenceIFace::WriteRecordType()
       */
      virtual void WriteRecordType(uint8_t value)  
      {return impl->WriteRecordType(value);}


      //------------------------------------------------------------------------
      /** \brief Copy constructor.
       */
      Persistence(const Persistence& right);

      //------------------------------------------------------------------------
      /** \brief Assignment operator.
       */
      Persistence& operator=(const Persistence& right);

      //------------------------------------------------------------------------

   private:

      //------------------------------------------------------------------------
      /** \brief Private constructor.
       *
       * Users interface with the Open() and OpenSingle() calls which call this.
       */
      Persistence(bool read, 
         ManagedFile file_in,
         EncodingType format_in);
      
      //------------------------------------------------------------------------
      /** \brief Increases the reference count of impl.
       */
      void IncRef();

      //------------------------------------------------------------------------
      /** \brief Decreases the reference count of impl andwill delete it if
       * reference count reaches 0.
       */
      void DecRef();
      
      //------------------------------------------------------------------------
      /** \brief A reference to the managed file that is the source for this
       * persistence.
       *
       * This may represent a file inside an archive or a standard file. 
       */
      ManagedFile file;

      //------------------------------------------------------------------------
      /** \brief The format declared to use for encoding/decoding the file.
       *
       * This is one of text or binary.
       */
      EncodingType format;
      
      //------------------------------------------------------------------------
      /** \brief A pointer to the particular persistence layer to use.
       *
       * This is eithre an instance of TextPersistence or BinaryPersistence
       * depending on wether the .edc file is a text or binary format edc file.
       */
      PersistenceIFace* impl;

      //------------------------------------------------------------------------
      /** \brief A list of "factories" for all archive formats that can be
       * understood.
       */
      static std::list<ArchiveIFace*> archive_formats;

      //------------------------------------------------------------------------

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

}

#endif // EDOC_PERSISTENCE_H

---