XMLFileWriter Class Reference

Wrapper to output XML data to files. More...

#include <XMLWriter.h>

Inheritance diagram for XMLFileWriter:

Collaboration diagram for XMLFileWriter:

Public Member Functions
	XMLFileWriter (const FilePath &outputPath, const TranslatableString &caption, bool keepBackup=false)
virtual	~XMLFileWriter ()
void	Commit ()
void	PreCommit ()
	Does the part of Commit that might fail because of exhaustion of space. More...
void	PostCommit ()
void	Write (const wxString &data) override
	Write to file. Might throw. More...
FilePath	GetBackupName () const
Public Member Functions inherited from XMLWriter
	XMLWriter ()
virtual	~XMLWriter ()
virtual void	StartTag (const wxString &name)
virtual void	EndTag (const wxString &name)
void	WriteAttr (const wxString &name, const Identifier &value)
virtual void	WriteAttr (const wxString &name, const wxString &value)
virtual void	WriteAttr (const wxString &name, const wxChar *value)
virtual void	WriteAttr (const wxString &name, int value)
virtual void	WriteAttr (const wxString &name, bool value)
virtual void	WriteAttr (const wxString &name, long value)
virtual void	WriteAttr (const wxString &name, long long value)
virtual void	WriteAttr (const wxString &name, size_t value)
virtual void	WriteAttr (const wxString &name, float value, int digits=-1)
virtual void	WriteAttr (const wxString &name, double value, int digits=-1)
virtual void	WriteData (const wxString &value)
virtual void	WriteSubTree (const wxString &value)
virtual void	Write (const wxString &data)=0

Private Member Functions
void	ThrowException (const wxFileName &fileName, const TranslatableString &caption)
void	CloseWithoutEndingTags ()

Private Attributes
const FilePath	mOutputPath
const TranslatableString	mCaption
FilePath	mBackupName
const bool	mKeepBackup
wxFFile	mBackupFile
bool	mCommitted { false }

Additional Inherited Members
Protected Attributes inherited from XMLWriter
bool	mInTag
int	mDepth
wxArrayString	mTagstack
std::vector< int >	mHasKids

Detailed Description

Wrapper to output XML data to files.

XMLFileWriter This writes to a provisional file, and replaces the previously existing contents by a file rename in Commit() only after all writes succeed. The original contents may also be retained at a backup path name, as directed by the optional constructor argument. If it is destroyed before Commit(), then the provisional file is removed. If the construction and all operations are inside a GuardedCall or event handler, then the default delayed handler action in case of exceptions will notify the user of problems.

Definition at line 84 of file XMLWriter.h.

Constructor & Destructor Documentation

XMLFileWriter()

XMLFileWriter::XMLFileWriter	(	const FilePath &	outputPath,
		const TranslatableString &	caption,
		bool	keepBackup = false
	)

The caption is for message boxes to show in case of errors. Might throw.

XMLFileWriter class

Definition at line 297 of file XMLWriter.cpp.

   : mOutputPath{ outputPath }
   , mCaption{ caption }
   , mKeepBackup{ keepBackup }
// may throw
{
   auto tempPath = wxFileName::CreateTempFileName( outputPath );
   if (!wxFFile::Open(tempPath, wxT("wb")) || !IsOpened())
      ThrowException( outputPath, mCaption );
 
   if (mKeepBackup) {
      int index = 0;
      wxString backupName;
 
      do {
         wxFileName outputFn{ mOutputPath };
         index++;
         mBackupName =
         outputFn.GetPath() + wxFILE_SEP_PATH +
         outputFn.GetName() + wxT("_bak") +
         wxString::Format(wxT("%d"), index) + wxT(".") +
         outputFn.GetExt();
      } while( ::wxFileExists( mBackupName ) );
 
      // Open the backup file to be sure we can write it and reserve it
      // until committing
      if (! mBackupFile.Open( mBackupName, "wb" ) || ! mBackupFile.IsOpened() )
         ThrowException( mBackupName, mCaption );
   }
}

References mBackupFile, mBackupName, mCaption, mKeepBackup, mOutputPath, ThrowException(), and wxT().

Here is the call graph for this function:

~XMLFileWriter()

XMLFileWriter::~XMLFileWriter ( )

virtual

Definition at line 330 of file XMLWriter.cpp.

{
   // Don't let a destructor throw!
   GuardedCall( [&] {
      if (!mCommitted) {
         auto fileName = GetName();
         if ( IsOpened() )
            CloseWithoutEndingTags();
         ::wxRemoveFile( fileName );
      }
   } );
}

References CloseWithoutEndingTags(), GuardedCall(), and mCommitted.

Here is the call graph for this function:

Member Function Documentation

CloseWithoutEndingTags()

void XMLFileWriter::CloseWithoutEndingTags ( )

private

Close file without automatically ending tags. Might throw.

Definition at line 387 of file XMLWriter.cpp.

{
   // Before closing, we first flush it, because if Flush() fails because of a
   // "disk full" condition, we can still at least try to close the file.
   if (!wxFFile::Flush())
   {
      wxFFile::Close();
      ThrowException( GetName(), mCaption );
   }
 
   // Note that this should never fail if flushing worked.
   if (!wxFFile::Close())
      ThrowException( GetName(), mCaption );
}

References mCaption, and ThrowException().

Referenced by PreCommit(), and ~XMLFileWriter().

Here is the call graph for this function:

Here is the caller graph for this function:

Commit()

void XMLFileWriter::Commit

(

)

Close all tags and then close the file. Might throw. If not, then create or modify the file at the output path. Composed of two steps, PreCommit() and PostCommit()

Definition at line 343 of file XMLWriter.cpp.

{
   PreCommit();
   PostCommit();
}

References PostCommit(), and PreCommit().

Here is the call graph for this function:

GetBackupName()

FilePath XMLFileWriter::GetBackupName ( ) const

inline

Definition at line 112 of file XMLWriter.h.

{ return mBackupName; }

PostCommit()

void XMLFileWriter::PostCommit

(

)

Does other parts of Commit that are not likely to fail for exhaustion of space, but might for other reasons

Definition at line 360 of file XMLWriter.cpp.

{
   FilePath tempPath = GetName();
   if (mKeepBackup) {
      if (! mBackupFile.Close() ||
          ! wxRenameFile( mOutputPath, mBackupName ) )
         ThrowException( mBackupName, mCaption );
   }
   else {
      if ( wxFileName::FileExists( mOutputPath ) &&
           ! wxRemoveFile( mOutputPath ) )
         ThrowException( mOutputPath, mCaption );
   }
 
   // Now we have vacated the file at the output path and are committed.
   // But not completely finished with steps of the commit operation.
   // If this step fails, we haven't lost the successfully written data,
   // but just failed to put it in the right place.
   if (! wxRenameFile( tempPath, mOutputPath ) )
      throw FileException{
         FileException::Cause::Rename, tempPath, mCaption, mOutputPath
      };
 
   mCommitted = true;
}

References mBackupFile, mBackupName, mCaption, mCommitted, mKeepBackup, mOutputPath, FileException::Rename, and ThrowException().

Referenced by Commit().

Here is the call graph for this function:

Here is the caller graph for this function:

PreCommit()

void XMLFileWriter::PreCommit

(

)

Does the part of Commit that might fail because of exhaustion of space.

Definition at line 350 of file XMLWriter.cpp.

{
   while (mTagstack.size()) {
      EndTag(mTagstack[0]);
   }
 
   CloseWithoutEndingTags();
}

References CloseWithoutEndingTags(), XMLWriter::EndTag(), and XMLWriter::mTagstack.

Referenced by Commit().

Here is the call graph for this function:

Here is the caller graph for this function:

ThrowException()

void XMLFileWriter::ThrowException ( const wxFileName &  fileName, const TranslatableString &  caption  )

inlineprivate

Definition at line 116 of file XMLWriter.h.

   {
      throw FileException{ FileException::Cause::Write, fileName, caption };
   }

References FileException::Write.

Referenced by CloseWithoutEndingTags(), PostCommit(), Write(), and XMLFileWriter().

Here is the caller graph for this function:

Write()

void XMLFileWriter::Write ( const wxString &  data )

overridevirtual

Write to file. Might throw.

Implements XMLWriter.

Definition at line 403 of file XMLWriter.cpp.

{
   if (!wxFFile::Write(data, wxConvUTF8) || Error())
   {
      // When writing fails, we try to close the file before throwing the
      // exception, so it can at least be deleted.
      wxFFile::Close();
      ThrowException( GetName(), mCaption );
   }
}

References Error, mCaption, and ThrowException().

Here is the call graph for this function:

Member Data Documentation

mBackupFile

wxFFile XMLFileWriter::mBackupFile

private

Definition at line 131 of file XMLWriter.h.

Referenced by PostCommit(), and XMLFileWriter().

mBackupName

FilePath XMLFileWriter::mBackupName

private

Definition at line 128 of file XMLWriter.h.

Referenced by PostCommit(), and XMLFileWriter().

mCaption

const TranslatableString XMLFileWriter::mCaption

private

Definition at line 127 of file XMLWriter.h.

Referenced by CloseWithoutEndingTags(), PostCommit(), Write(), and XMLFileWriter().

mCommitted

bool XMLFileWriter::mCommitted { false }

private

Definition at line 133 of file XMLWriter.h.

Referenced by PostCommit(), and ~XMLFileWriter().

mKeepBackup

const bool XMLFileWriter::mKeepBackup

private

Definition at line 129 of file XMLWriter.h.

Referenced by PostCommit(), and XMLFileWriter().

mOutputPath

const FilePath XMLFileWriter::mOutputPath

private

Definition at line 126 of file XMLWriter.h.

Referenced by PostCommit(), and XMLFileWriter().

---

The documentation for this class was generated from the following files:

• XMLWriter.h
• XMLWriter.cpp