include/EDoc/ManagedFile.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_MANAGEDFILE_H
#define EDOC_MANAGEDFILE_H

#include <string>
#include <list>

namespace EDoc
{
   class ManagedFileCleanupIFace;
   
   //===========================================================================
   /** \brief Represents a file that can have some sort of cleanup action
    * associated with it when it is no longer being used.
    *
    * This implements an internal reference counting pattern where when no more
    * copies of this managed file exist it will perform a cleanup action. This
    * cleanup action is done on calling the virtual destructor of:
    * ManagedFileCleanupIFace::~ManagedFileCleanupIFace() a derived class for
    * ManagedFileCleanupIFace will implement various actions that need to be
    * performed in order to cleanup the file correctly. This may include: Do
    * nothing. Delete temporary file, Write temporary file into archive before
    * delete.
    */
   class ManagedFile
   {
   public:
   
      //------------------------------------------------------------------------
      /** \brief Create a new managed file that is identified by the given 
       * list of archives.
       *
       * If the list contains just a single member then that is a direct 
       * filename, otheriwse the list contains the identifiers for recursive 
       * archives. For example if this was managing a file called Blah.edc 
       * inside a zipfile call foo.zip which itself was part of another zip
       * file bar.zip you would pass the following:
       *    -# bar.zip
       *    -# foo.zip
       *    -# Blah.edc
       */
      explicit ManagedFile(std::list<std::string> identifier_in);

      //------------------------------------------------------------------------
      /** \brief Create a new managed file for the given filename.
       *
       * This is just a wrapper around the above constructor.
       */
      explicit ManagedFile(std::string identifier_in);

      //------------------------------------------------------------------------
      /** \brief Create a new managed file that is operating on a given 
       * temporary file and has a given cleanup callback that needs to be 
       * called when we are finsihed using it.
       */
      ManagedFile(std::list<std::string> identifier_in,
         std::string work_file_name_in, 
         ManagedFileCleanupIFace* cleanup_in);

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

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

      //------------------------------------------------------------------------
      /** \brief Destructor.
       *
       * If this is the last reference to the particular file being managed 
       * then it will perform any cleanup operations that may have been 
       * associated with the file. For example this could include adding it
       * to a zip archive or deleteing a temporary file etc.
       */
      virtual ~ManagedFile();

      //------------------------------------------------------------------------
      /** \brief Retruns the name of the file that is to be used for 
       * reading/writing operations.
       *
       * This will often be a temporary file which will later be merged 
       * into an archive.
       */
      const std::string& GetWorkFileName() const
      {
         if (work_file_name.size())
         {
            return work_file_name;
         }
         else
         {
            return identifier.back();
         }
      }
      
      //------------------------------------------------------------------------
      /** \brief Returns the identifier for this file.
       */
      const std::list<std::string>& GetIdentifier() const
      {
         return identifier;
      }

      //------------------------------------------------------------------------
      /** \brief Returns the name of the final file this represents without 
       * any archive context.
       */
      const std::string& GetName() const
      {
         return identifier.back();
      }

      //------------------------------------------------------------------------
      /** \brief Returns a string that represents the name of the file 
       * including its archive context. This is used for displaying data ot a 
       * user.
       */
      std::string GetFileNameRep() const;

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

   private:

      //------------------------------------------------------------------------
      /** \brief Increment the reference count to the cleanup instance.
       */
      void IncRef();

      //------------------------------------------------------------------------
      /** \brief Decrement the reference count to the cleanup instance and 
       * perform any cleanup operations if necessary when the reference 
       * count reaches 0
       */
      void DecRef();

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



      //------------------------------------------------------------------------
      //------------------------------------------------------------------------
      /** \brief Reference to object that implementes operations to perform to
       * close/cleanup the file.
       */
      ManagedFileCleanupIFace* cleanup;

      //------------------------------------------------------------------------
      /** \brief Reference to a temporary file that all work is to be 
       * performed on.
       */
      std::string work_file_name;

      //------------------------------------------------------------------------
      /** \brief List of identifiers used to identify this file within an 
       * abrbitrary list of archives.
       */
      std::list<std::string> identifier;
   };
   //===========================================================================
   typedef std::list<ManagedFile> MngdFileList;
}

#endif // EDOC_MANAGEDFILE_H

---