[xmltooling] 31/65: Some documentation / logging cleanup. Throw on invalid use of the new backup file parameter.

[Ferenc Wágner]

This is an automated email from the git hooks/post-receive script.

wferi-guest pushed a commit to branch debian/master
in repository xmltooling.

commit 36e62edd732312d8e134d8d637eac6c21a46f3aa
Author: Scott Cantor <cantor.2 at osu.edu>
Date:   Mon Jun 6 10:53:48 2016 -0400

    Some documentation / logging cleanup.
    Throw on invalid use of the new backup file parameter.
---
 xmltooling/util/ParserPool.cpp        |  2 +-
 xmltooling/util/ReloadableXMLFile.cpp |  8 ++---
 xmltooling/util/ReloadableXMLFile.h   | 64 +++++++++++++++++++++--------------
 3 files changed, 43 insertions(+), 31 deletions(-)

diff --git a/xmltooling/util/ParserPool.cpp b/xmltooling/util/ParserPool.cpp
index bd08346..55a8a65 100644
--- a/xmltooling/util/ParserPool.cpp
+++ b/xmltooling/util/ParserPool.cpp
@@ -587,7 +587,7 @@ URLInputSource::URLInputSource(const DOMElement* e, const char* systemId, string
 BinInputStream* URLInputSource::makeStream() const
 {
     BinInputStream*  stream = m_root ? new CurlURLInputStream(m_root, m_cacheTag) : new CurlURLInputStream(m_url.get(), m_cacheTag);
-    return ("" == m_backingFile) ? stream : new CloneInputStream(stream, m_backingFile);
+    return (m_backingFile.empty()) ? stream : new CloneInputStream(stream, m_backingFile);
 }
 
 #endif
diff --git a/xmltooling/util/ReloadableXMLFile.cpp b/xmltooling/util/ReloadableXMLFile.cpp
index 984f84e..1b005f6 100644
--- a/xmltooling/util/ReloadableXMLFile.cpp
+++ b/xmltooling/util/ReloadableXMLFile.cpp
@@ -397,10 +397,10 @@ pair<bool,DOMElement*> ReloadableXMLFile::load(bool backup, string backingFile)
                 m_log.debug("loading configuration from external resource...");
 
             if (!backingFile.empty() && backup)
-                m_log.error("Internal error: backing file provided to backup load");
+                throw IOException("Backing file name cannot be provided during a backup load");
 
             if (!backingFile.empty())
-                m_log.debug("writing to backing file " + backingFile);
+                m_log.debug("writing to backing file: " + backingFile);
 
             DOMDocument* doc=nullptr;
             if (m_local || backup) {
@@ -462,7 +462,7 @@ pair<bool,DOMElement*> ReloadableXMLFile::load(bool backup, string backingFile)
         auto_ptr_char msg(e.getMessage());
         m_log.errorStream() << "Xerces error while loading resource (" << (backup ? m_backing : m_source) << "): "
             << msg.get() << logging::eol;
-        //  Cleanup if we left anything in fligbt
+        //  Cleanup if we left anything in flight
         if (!backingFile.empty() && !backup)
             remove(backingFile.c_str());
 
@@ -471,7 +471,7 @@ pair<bool,DOMElement*> ReloadableXMLFile::load(bool backup, string backingFile)
     catch (exception& e) {
         m_log.errorStream() << "error while loading resource ("
             << (m_source.empty() ? "inline" : (backup ? m_backing : m_source)) << "): " << e.what() << logging::eol;
-        //  Cleanup if we left anything in fligbt
+        //  Cleanup if we left anything in flight
         if (!backingFile.empty() && !backup)
             remove(backingFile.c_str());
         throw;
diff --git a/xmltooling/util/ReloadableXMLFile.h b/xmltooling/util/ReloadableXMLFile.h
index 8f4630e..bb1b50b 100644
--- a/xmltooling/util/ReloadableXMLFile.h
+++ b/xmltooling/util/ReloadableXMLFile.h
@@ -128,35 +128,47 @@ namespace xmltooling {
         virtual std::pair<bool,xercesc::DOMElement*> load();
 
         /**
-         * Basic load/parse of configuration material.
-         *
-         * <p>The base version performs basic parsing duties and returns the result.
-         * Subclasses should override the new background_load() method and perform
-         * their own locking in conjunction with use of this method.
-         *
-         * <p>This version allows subclasses to explicitly control the use of a
-         * backup for remote resources, which allows additional validation to be
-         * performed besides just successful XML parsing.
-         *
-         * <p>Anyone calling this code needs to take ownership of the job of creating
-         * the backup (if the inpout is well formed).  As an assist, providing
-         * a unique file name as the second parameter causes the input source to be
-         * copied to this file.  Thus input cna be done without locking and the
-         * job of creating the backup consists of doign a rename (under the lock).
-         *
-         * <p> The single parameter version is deprecated and is the same as
-         * calling with an empty string at the second parameter (which means
-         * no backing file).
-         *
-         * @param backup      true iff the backup source should be loaded
-         * @param backingFile Filoe name to copy the input to.
-         * @return a pair consisting of a flag indicating whether to take ownership of
-         *      the document, and the root element of the tree to load
-         */
-        virtual std::pair<bool,xercesc::DOMElement*> load(bool backup);
+        * Basic load/parse of configuration material.
+        *
+        * <p>The base version performs basic parsing duties and returns the result.
+        * Subclasses should override the new background_load() method and perform
+        * their own locking in conjunction with use of this method.</p>
+        *
+        * <p>This version allows subclasses to explicitly control the use of a
+        * backup for remote resources, which allows additional validation to be
+        * performed besides just successful XML parsing.</p>
+        *
+        * <p>Anyone calling this code needs to take ownership of the job of creating
+        * the backup (if the input is well formed).  As an assist, providing
+        * a unique file name as the second parameter causes the input source to be
+        * copied to this file.  Thus backup can be done without locking and the
+        * job of creating the backup consists of doing a rename (under the lock).</p>
+        *
+        * <p> The single parameter version is deprecated and is the same as
+        * calling this version with an empty string at the second parameter
+        * (no backing file).</p>
+        *
+        * @param backup      true iff the backup source should be loaded
+        * @param backingFile Filename to copy the input to
+        * @return a pair consisting of a flag indicating whether to take ownership of
+        *      the document, and the root element of the tree to load
+        */
         virtual std::pair<bool, xercesc::DOMElement*> load(bool backup, std::string backingFile);
 
         /**
+        * @deprecated
+        * Basic load/parse of configuration material.
+        *
+        * <p>The deprecated version of the two-parameter load method, equivalent to
+        * calling it with an empty second parameter.</p>
+        *
+        * @param backup      true iff the backup source should be loaded
+        * @return a pair consisting of a flag indicating whether to take ownership of
+        *      the document, and the root element of the tree to load
+        */
+        virtual std::pair<bool,xercesc::DOMElement*> load(bool backup);
+
+        /**
          * Accesses a lock interface protecting use of backup file associated with the
          * object.
          *

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-shibboleth/xmltooling.git