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:
[legend]
Collaboration diagram for XMLFileWriter:
[legend]

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 );
304 
305  if (mKeepBackup) {
306  int index = 0;
307  wxString backupName;
308 
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 ) );
318 
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 ( )
virtual

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 ( )
private

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  }
394 
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
inline

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  }
371 
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  };
380 
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  }
353 
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 
)
inlineprivate

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)
overridevirtual

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
private

Definition at line 128 of file XMLWriter.h.

Referenced by PostCommit().

◆ mBackupName

FilePath XMLFileWriter::mBackupName
private

Definition at line 125 of file XMLWriter.h.

Referenced by PostCommit().

◆ mCaption

const TranslatableString XMLFileWriter::mCaption
private

Definition at line 124 of file XMLWriter.h.

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

◆ mCommitted

bool XMLFileWriter::mCommitted { false }
private

Definition at line 130 of file XMLWriter.h.

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

◆ mKeepBackup

const bool XMLFileWriter::mKeepBackup
private

Definition at line 126 of file XMLWriter.h.

Referenced by PostCommit().

◆ mOutputPath

const FilePath XMLFileWriter::mOutputPath
private

Definition at line 123 of file XMLWriter.h.

Referenced by PostCommit().


The documentation for this class was generated from the following files:
XMLWriter::EndTag
virtual void EndTag(const wxString &name)
Definition: XMLWriter.cpp:99
XMLFileWriter::ThrowException
void ThrowException(const wxFileName &fileName, const TranslatableString &caption)
Definition: XMLWriter.h:113
GuardedCall
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
XMLFileWriter::mBackupFile
wxFFile mBackupFile
Definition: XMLWriter.h:128
FileException::Cause::Rename
@ Rename
involves two filenames
FileException::Cause::Write
@ Write
most important to detect when storage space is exhausted
XMLFileWriter::mCaption
const TranslatableString mCaption
Definition: XMLWriter.h:124
FileException
Thrown for failure of file or database operations in deeply nested places.
Definition: FileException.h:19
XMLFileWriter::PreCommit
void PreCommit()
Does the part of Commit that might fail because of exhaustion of space.
Definition: XMLWriter.cpp:347
XMLFileWriter::mCommitted
bool mCommitted
Definition: XMLWriter.h:130
XMLFileWriter::mBackupName
FilePath mBackupName
Definition: XMLWriter.h:125
XMLWriter::mTagstack
wxArrayString mTagstack
Definition: XMLWriter.h:64
FilePath
wxString FilePath
Definition: Project.h:20
XMLFileWriter::PostCommit
void PostCommit()
Definition: XMLWriter.cpp:357
XMLFileWriter::mOutputPath
const FilePath mOutputPath
Definition: XMLWriter.h:123
BasicUI::Icon::Error
@ Error
XMLFileWriter::CloseWithoutEndingTags
void CloseWithoutEndingTags()
Definition: XMLWriter.cpp:384
XMLFileWriter::mKeepBackup
const bool mKeepBackup
Definition: XMLWriter.h:126