Audacity  3.0.3
Public Member Functions | Private Member Functions | Private Attributes | List of all members
XMLFileWriter Class Referencefinal

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)
wxString XMLEsc (const wxString &s)

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 81 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 294 of file XMLWriter.cpp.

296  : mOutputPath{ outputPath }
297  , mCaption{ caption }
298  , mKeepBackup{ keepBackup }
299 // may throw
300 {
301  auto tempPath = wxFileName::CreateTempFileName( outputPath );
302  if (!wxFFile::Open(tempPath, wxT("wb")) || !IsOpened())
303  ThrowException( outputPath, mCaption );
305  if (mKeepBackup) {
306  int index = 0;
307  wxString backupName;
309  do {
310  wxFileName outputFn{ mOutputPath };
311  index++;
312  mBackupName =
313  outputFn.GetPath() + wxFILE_SEP_PATH +
314  outputFn.GetName() + wxT("_bak") +
315  wxString::Format(wxT("%d"), index) + wxT(".") +
316  outputFn.GetExt();
317  } while( ::wxFileExists( mBackupName ) );
319  // Open the backup file to be sure we can write it and reserve it
320  // until committing
321  if (! mBackupFile.Open( mBackupName, "wb" ) || ! mBackupFile.IsOpened() )
323  }
324 }

◆ ~XMLFileWriter()

XMLFileWriter::~XMLFileWriter ( )

Definition at line 327 of file XMLWriter.cpp.

328 {
329  // Don't let a destructor throw!
330  GuardedCall( [&] {
331  if (!mCommitted) {
332  auto fileName = GetName();
333  if ( IsOpened() )
335  ::wxRemoveFile( fileName );
336  }
337  } );
338 }

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

Here is the call graph for this function:

Member Function Documentation

◆ CloseWithoutEndingTags()

void XMLFileWriter::CloseWithoutEndingTags ( )

Close file without automatically ending tags. Might throw.

Definition at line 384 of file XMLWriter.cpp.

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

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 340 of file XMLWriter.cpp.

342 {
343  PreCommit();
344  PostCommit();
345 }

References PostCommit(), and PreCommit().

Here is the call graph for this function:

◆ GetBackupName()

FilePath XMLFileWriter::GetBackupName ( ) const

Definition at line 109 of file XMLWriter.h.

109 { 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 357 of file XMLWriter.cpp.

359 {
360  FilePath tempPath = GetName();
361  if (mKeepBackup) {
362  if (! mBackupFile.Close() ||
363  ! wxRenameFile( mOutputPath, mBackupName ) )
365  }
366  else {
367  if ( wxFileName::FileExists( mOutputPath ) &&
368  ! wxRemoveFile( mOutputPath ) )
370  }
372  // Now we have vacated the file at the output path and are committed.
373  // But not completely finished with steps of the commit operation.
374  // If this step fails, we haven't lost the successfully written data,
375  // but just failed to put it in the right place.
376  if (! wxRenameFile( tempPath, mOutputPath ) )
377  throw FileException{
379  };
381  mCommitted = true;
382 }

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 347 of file XMLWriter.cpp.

349 {
350  while (mTagstack.size()) {
351  EndTag(mTagstack[0]);
352  }
355 }

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 

Definition at line 113 of file XMLWriter.h.

115  {
116  throw FileException{ FileException::Cause::Write, fileName, caption };
117  }

References FileException::Write.

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

Here is the caller graph for this function:

◆ Write()

void XMLFileWriter::Write ( const wxString &  data)

Write to file. Might throw.

Implements XMLWriter.

Definition at line 400 of file XMLWriter.cpp.

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

References mCaption, and ThrowException().

Here is the call graph for this function:

Member Data Documentation

◆ mBackupFile

wxFFile XMLFileWriter::mBackupFile

Definition at line 128 of file XMLWriter.h.

Referenced by PostCommit().

◆ mBackupName

FilePath XMLFileWriter::mBackupName

Definition at line 125 of file XMLWriter.h.

Referenced by PostCommit().

◆ mCaption

const TranslatableString XMLFileWriter::mCaption

Definition at line 124 of file XMLWriter.h.

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

◆ mCommitted

bool XMLFileWriter::mCommitted { false }

Definition at line 130 of file XMLWriter.h.

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

◆ mKeepBackup

const bool XMLFileWriter::mKeepBackup

Definition at line 126 of file XMLWriter.h.

Referenced by PostCommit().

◆ mOutputPath

const FilePath XMLFileWriter::mOutputPath

Definition at line 123 of file XMLWriter.h.

Referenced by PostCommit().

The documentation for this class was generated from the following files:
virtual void EndTag(const wxString &name)
Definition: XMLWriter.cpp:99
void ThrowException(const wxFileName &fileName, const TranslatableString &caption)
Definition: XMLWriter.h:113
R GuardedCall(const F1 &body, const F2 &handler=F2::Default(), std::function< void(AudacityException *)> delayedHandler=DefaultDelayedHandlerAction{})
Execute some code on any thread; catch any AudacityException; enqueue error report on the main thread...
Definition: AudacityException.h:202
wxFFile mBackupFile
Definition: XMLWriter.h:128
@ Rename
involves two filenames
@ Write
most important to detect when storage space is exhausted
const TranslatableString mCaption
Definition: XMLWriter.h:124
Thrown for failure of file or database operations in deeply nested places.
Definition: FileException.h:19
void PreCommit()
Does the part of Commit that might fail because of exhaustion of space.
Definition: XMLWriter.cpp:347
bool mCommitted
Definition: XMLWriter.h:130
FilePath mBackupName
Definition: XMLWriter.h:125
wxArrayString mTagstack
Definition: XMLWriter.h:64
wxString FilePath
Definition: Project.h:20
void PostCommit()
Definition: XMLWriter.cpp:357
const FilePath mOutputPath
Definition: XMLWriter.h:123
@ Error
void CloseWithoutEndingTags()
Definition: XMLWriter.cpp:384
const bool mKeepBackup
Definition: XMLWriter.h:126