Audacity 3.2.0
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)
 
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 85 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 298 of file XMLWriter.cpp.

300 : mOutputPath{ outputPath }
301 , mCaption{ caption }
302 , mKeepBackup{ keepBackup }
303// may throw
304{
305 auto tempPath = wxFileName::CreateTempFileName( outputPath );
306 if (!wxFFile::Open(tempPath, wxT("wb")) || !IsOpened())
307 ThrowException( outputPath, mCaption );
308
309 if (mKeepBackup) {
310 int index = 0;
311 wxString backupName;
312
313 do {
314 wxFileName outputFn{ mOutputPath };
315 index++;
317 outputFn.GetPath() + wxFILE_SEP_PATH +
318 outputFn.GetName() + wxT("_bak") +
319 wxString::Format(wxT("%d"), index) + wxT(".") +
320 outputFn.GetExt();
321 } while( ::wxFileExists( mBackupName ) );
322
323 // Open the backup file to be sure we can write it and reserve it
324 // until committing
325 if (! mBackupFile.Open( mBackupName, "wb" ) || ! mBackupFile.IsOpened() )
327 }
328}
wxT("CloseDown"))
wxFFile mBackupFile
Definition: XMLWriter.h:132
FilePath mBackupName
Definition: XMLWriter.h:129
const TranslatableString mCaption
Definition: XMLWriter.h:128
const bool mKeepBackup
Definition: XMLWriter.h:130
void ThrowException(const wxFileName &fileName, const TranslatableString &caption)
Definition: XMLWriter.h:117
const FilePath mOutputPath
Definition: XMLWriter.h:127

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

Here is the call graph for this function:

◆ ~XMLFileWriter()

XMLFileWriter::~XMLFileWriter ( )
virtual

Definition at line 331 of file XMLWriter.cpp.

332{
333 // Don't let a destructor throw!
334 GuardedCall( [&] {
335 if (!mCommitted) {
336 auto fileName = GetName();
337 if ( IsOpened() )
339 ::wxRemoveFile( fileName );
340 }
341 } );
342}
R GuardedCall(const F1 &body, const F2 &handler=F2::Default(), F3 delayedHandler=DefaultDelayedHandlerAction) noexcept(noexcept(handler(std::declval< AudacityException * >())) &&noexcept(handler(nullptr)) &&noexcept(std::function< void(AudacityException *)>{std::move(delayedHandler)}))
Execute some code on any thread; catch any AudacityException; enqueue error report on the main thread...
bool mCommitted
Definition: XMLWriter.h:134
void CloseWithoutEndingTags()
Definition: XMLWriter.cpp:388

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

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

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

346{
347 PreCommit();
348 PostCommit();
349}
void PostCommit()
Definition: XMLWriter.cpp:361
void PreCommit()
Does the part of Commit that might fail because of exhaustion of space.
Definition: XMLWriter.cpp:351

References PostCommit(), and PreCommit().

Here is the call graph for this function:

◆ GetBackupName()

FilePath XMLFileWriter::GetBackupName ( ) const
inline

Definition at line 113 of file XMLWriter.h.

113{ 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 361 of file XMLWriter.cpp.

363{
364 FilePath tempPath = GetName();
365 if (mKeepBackup) {
366 if (! mBackupFile.Close() ||
367 ! wxRenameFile( mOutputPath, mBackupName ) )
369 }
370 else {
371 if ( wxFileName::FileExists( mOutputPath ) &&
372 ! wxRemoveFile( mOutputPath ) )
374 }
375
376 // Now we have vacated the file at the output path and are committed.
377 // But not completely finished with steps of the commit operation.
378 // If this step fails, we haven't lost the successfully written data,
379 // but just failed to put it in the right place.
380 if (! wxRenameFile( tempPath, mOutputPath ) )
381 throw FileException{
383 };
384
385 mCommitted = true;
386}
wxString FilePath
Definition: Project.h:20
Thrown for failure of file or database operations in deeply nested places.
Definition: FileException.h:19
@ Rename
involves two filenames

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

353{
354 while (mTagstack.size()) {
355 EndTag(mTagstack[0]);
356 }
357
359}
virtual void EndTag(const wxString &name)
Definition: XMLWriter.cpp:103
wxArrayString mTagstack
Definition: XMLWriter.h:68

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 117 of file XMLWriter.h.

119 {
120 throw FileException{ FileException::Cause::Write, fileName, caption };
121 }
@ Write
most important to detect when storage space is exhausted

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

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

References mCaption, and ThrowException().

Here is the call graph for this function:

Member Data Documentation

◆ mBackupFile

wxFFile XMLFileWriter::mBackupFile
private

Definition at line 132 of file XMLWriter.h.

Referenced by PostCommit(), and XMLFileWriter().

◆ mBackupName

FilePath XMLFileWriter::mBackupName
private

Definition at line 129 of file XMLWriter.h.

Referenced by PostCommit(), and XMLFileWriter().

◆ mCaption

const TranslatableString XMLFileWriter::mCaption
private

Definition at line 128 of file XMLWriter.h.

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

◆ mCommitted

bool XMLFileWriter::mCommitted { false }
private

Definition at line 134 of file XMLWriter.h.

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

◆ mKeepBackup

const bool XMLFileWriter::mKeepBackup
private

Definition at line 130 of file XMLWriter.h.

Referenced by PostCommit(), and XMLFileWriter().

◆ mOutputPath

const FilePath XMLFileWriter::mOutputPath
private

Definition at line 127 of file XMLWriter.h.

Referenced by PostCommit(), and XMLFileWriter().


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