Include/cppunit/plugin/PlugInManager.

include/cppunit/plugin/PlugInManager.h:
* src/cppunit/PlugInManager.cpp: added two methods to use the plug-in
interface for Xml Outputter hooks.

* include/cppunit/plugin/TestPlugIn.h: added two methods to the plug-in
interface for Xml Outputter hooks.

* include/cppunit/plugin/TestPlugInAdapter.h:
* src/cppunit/plugin/TestPlugInAdapter.cpp: renamed TestPlugInDefaultImpl.
Added empty implementation for Xml outputter hook methods.

* include/cppunit/tools/StringTools.h:
* src/cppunit/tools/StringTools.cpp: added. Functions to manipulate string
(conversion, wrapping...)

* include/cppunit/tools/XmlElement.h:
* src/cppunit/XmlElement.cpp: renamed addNode() to addElement(). Added
methods to walk and modify XmlElement (for hook). Added documentation.
Use StringTools.

* include/cppunit/XmlOutputter.h:
* src/cppunit/XmlOutputter.cpp: added hook calls & management.

* include/cppunit/XmlOutputterHook.h:
* src/cppunit/XmlOutputterHook.cpp: added. Hook to customize XML output.

* src/DllPlugInTester/DllPlugInTester.cpp: call plug-in XmlOutputterHook
when writing XML output. Modified so that memory is freed before
unloading the test plug-in (caused crash when freeing the XmlDocument).

* examples/ReadMe.txt:
* examples/ClockerPlugIn/ReadMe.txt: added details about the plug-in
(usage, xml content...)

* examples/ClockerPlugIn/ClockerModel.h:
* examples/ClockerPlugIn/ClockerModel.cpp: extracted from ClockerListener.
Represents the test hierarchy and tracked time for each test.

* examples/ClockerPlugIn/ClockerListener.h:
* examples/ClockerPlugIn/ClockerListener.cpp: extracted test hierarchy
tracking to ClockerModel. Replaced the 'flat' view option with a 'text'
option to print the timed test tree to stdout.

* examples/ClockerPlugIn/ClockerPlugIn.cpp: updated to hook the XML
output and use the new classes.

* examples/ClockerPlugIn/ClockerXmlHook.h:
* examples/ClockerPlugIn/ClockerXmlHook.cpp: added. XmlOutputterHook to
includes the timed test hierarchy and test timing in the XML output.

* examples/cppunittest/XmlElementTest.h:
* examples/cppunittest/XmlElementTest.cpp: added new test cases.

* examples/cppunittest/XmlOutputterTest.h:
* examples/cppunittest/XmlOutputterTest.cpp: added tests for
XmlOutputterHook.

10 files changed, 244 insertions, 11 deletions

diff --git a/include/cppunit/Makefile.am b/include/cppunit/Makefile.am
index bd505ad..3c7930a 100644
--- a/include/cppunit/Makefile.am
+++ b/include/cppunit/Makefile.am
@@ -33,7 +33,8 @@ libcppunitinclude_HEADERS =  \
 	TextTestResult.h \
 	TextTestRunner.h \
 	TestListener.h \
-	XmlOutputter.h
+	XmlOutputter.h \
+	XmlOutputterHook.h
 
 dist-hook:
 	rm -f $(distdir)/config-auto.h
diff --git a/include/cppunit/XmlOutputter.h b/include/cppunit/XmlOutputter.h
index 3336405..dc16913 100644
--- a/include/cppunit/XmlOutputter.h
+++ b/include/cppunit/XmlOutputter.h
@@ -9,6 +9,7 @@
 #endif
 
 #include <cppunit/Outputter.h>
+#include <deque>
 #include <iostream>
 #include <map>
 
@@ -21,10 +22,19 @@ class TestFailure;
 class TestResultCollector;
 class XmlDocument;
 class XmlElement;
+class XmlOutputterHook;
 
 
 /*! \brief Outputs a TestResultCollector in XML format.
  * \ingroup WritingTestResult
+ *
+ * Save the test result as a XML stream. 
+ *
+ * Additional datas can be added to the XML document using XmlOutputterHook. 
+ * Hook are not owned by the XmlOutputter. They should be valid until 
+ * destruction of the XmlOutputter. They can be removed with removeHook().
+ *
+ * \see XmlDocument, XmlElement, XmlOutputterHook.
  */
 class CPPUNIT_API XmlOutputter : public Outputter
 {
@@ -41,6 +51,16 @@ public:
   /// Destructor.
   virtual ~XmlOutputter();
 
+  /*! Adds the specified hook to the outputter.
+   * \param hook Hook to add. Must not be \c NULL.
+   */
+  virtual void addHook( XmlOutputterHook *hook );
+
+  /*! Removes the specified hook from the outputter.
+   * \param hook Hook to remove.
+   */
+  virtual void removeHook( XmlOutputterHook *hook );
+
   /*! Writes the specified result as an XML document to the stream.
    *
    * Refer to examples/cppunittest/XmlOutputterTest.cpp for example
@@ -57,18 +77,48 @@ public:
 
 
   typedef std::map<Test *,TestFailure*> FailedTests;
+
+  /*! Returns the root element with its children.
+   *
+   * For all hooks, call beginDocument() just after creating the root element (it
+   * is empty at this time), and endDocument() once all the datas have been added
+   * to the root element.
+   *
+   * \return Root element.
+   */
   virtual XmlElement *makeRootNode();
   virtual void addFailedTests( FailedTests &failedTests,
                                XmlElement *rootNode );
   virtual void addSuccessfulTests( FailedTests &failedTests,
                                    XmlElement *rootNode );
+
+  /*! Adds the statics element to the root node.
+   * 
+   * Creates a new element containing statistics data and adds it to the root element.
+   * Then, for all hooks, call statisticsAdded().
+   * \param rootNode Root element.
+   */
   virtual void addStatistics( XmlElement *rootNode );
+
+  /*! Adds a failed test to the failed tests node.
+   * Creates a new element containing datas about the failed test, and adds it to 
+   * the failed tests element.
+   * Then, for all hooks, call failTestAdded().
+   */
   virtual void addFailedTest( Test *test,
                               TestFailure *failure,
                               int testNumber,
                               XmlElement *testsNode );
+
   virtual void addFailureLocation( TestFailure *failure,
                                    XmlElement *testNode );
+
+
+  /*! Adds a successful test to the successful tests node.
+   * Creates a new element containing datas about the successful test, and adds it to 
+   * the successful tests element.
+   * Then, for all hooks, call successfulTestAdded().
+   */
   virtual void addSuccessfulTest( Test *test, 
                                   int testNumber,
                                   XmlElement *testsNode );
@@ -76,11 +126,14 @@ protected:
   virtual void fillFailedTestsMap( FailedTests &failedTests );
 
 protected:
+  typedef std::deque<XmlOutputterHook *> Hooks;
+
   TestResultCollector *m_result;
   std::ostream &m_stream;
   std::string m_encoding;
   std::string m_styleSheet;
   XmlDocument *m_xml;
+  Hooks m_hooks;
 
 private:
   /// Prevents the use of the copy constructor.
diff --git a/include/cppunit/XmlOutputterHook.h b/include/cppunit/XmlOutputterHook.h
new file mode 100644
index 0000000..b67c6cf
--- /dev/null
+++ b/include/cppunit/XmlOutputterHook.h
@@ -0,0 +1,46 @@
+#ifndef CPPUNIT_XMLOUTPUTTERHOOK_H
+#define CPPUNIT_XMLOUTPUTTERHOOK_H
+
+#include <cppunit/Portability.h>
+
+
+namespace CppUnit
+{
+
+class Test;
+class TestFailure;
+class XmlDocument;
+class XmlElement;
+
+
+
+/*! \brief Hook to customize Xml output.
+ */
+class CPPUNIT_API XmlOutputterHook
+{
+public:
+  virtual void beginDocument( XmlDocument *document,
+                              XmlElement *rootNode );
+
+  virtual void endDocument( XmlDocument *document,
+                            XmlElement *rootNode );
+
+  virtual void failTestAdded( XmlDocument *document,
+                              XmlElement *testNode,
+                              Test *test,
+                              TestFailure *failure );
+
+  virtual void successfulTestAdded( XmlDocument *document,
+                                    XmlElement *testNode,
+                                    Test *test );
+
+  virtual void statisticsAdded( XmlDocument *document,
+                                XmlElement *statisticsNode );
+};
+
+
+
+} //  namespace CppUnit
+
+
+#endif  // CPPUNIT_XMLOUTPUTTERHOOK_H
diff --git a/include/cppunit/plugin/Makefile.am b/include/cppunit/plugin/Makefile.am
index 0494373..3fdff64 100644
--- a/include/cppunit/plugin/Makefile.am
+++ b/include/cppunit/plugin/Makefile.am
@@ -4,6 +4,6 @@ libcppunitinclude_HEADERS = \
 	DynamicLibraryManager.h \
 	DynamicLibraryManagerException.h \
 	TestPlugIn.h \
-	TestPlugInAdapter.h \
+	TestPlugInDefaultImpl.h \
 	PlugInManager.h \
 	Parameters.h
diff --git a/include/cppunit/plugin/PlugInManager.h b/include/cppunit/plugin/PlugInManager.h
index d3bbc5f..f349ab1 100644
--- a/include/cppunit/plugin/PlugInManager.h
+++ b/include/cppunit/plugin/PlugInManager.h
@@ -18,6 +18,7 @@ namespace CppUnit
 
 class DynamicLibraryManager;
 class TestResult;
+class XmlOutputter;
 
 
 /*! \brief Manges TestPlugIn.
@@ -62,6 +63,16 @@ public:
    */
   void removeListener( TestResult *eventManager );
 
+  /*! Provides a way for the plug-in to register some XmlOutputterHook.
+   */
+  void addXmlOutputterHooks( XmlOutputter *outputter );
+
+  /*! Called when the XmlOutputter is destroyed.
+   * 
+   * Can be used to free some resources allocated by addXmlOutputterHooks().
+   */
+  void removeXmlOutputterHooks();
+
 protected:
   struct PlugInInfo
   {
diff --git a/include/cppunit/plugin/TestPlugIn.h b/include/cppunit/plugin/TestPlugIn.h
index 0847928..0eaf960 100644
--- a/include/cppunit/plugin/TestPlugIn.h
+++ b/include/cppunit/plugin/TestPlugIn.h
@@ -12,6 +12,7 @@ namespace CppUnit
 class Test;
 class TestFactoryRegistry;
 class TestResult;
+class XmlOutputter;
 }
 
 /*! \file
@@ -67,6 +68,16 @@ struct CppUnitTestPlugIn
    */
   virtual void removeListener( CppUnit::TestResult *eventManager ) =0;
 
+  /*! Provides a way for the plug-in to register some XmlOutputterHook.
+   */
+  virtual void addXmlOutputterHooks( CppUnit::XmlOutputter *outputter ) =0;
+
+  /*! Called when the XmlOutputter is destroyed.
+   * 
+   * Can be used to free some resources allocated by addXmlOutputterHooks().
+   */
+  virtual void removeXmlOutputterHooks() = 0;
+
   /*! Called just before unloading the dynamic library.
    * 
    * Override this method to unregister test factory added in initialize().
@@ -109,7 +120,7 @@ typedef CppUnitTestPlugIn *(*TestPlugInSignature)();
 
 
 // Note: This include should remain after definition of CppUnitTestPlugIn
-#include <cppunit/plugin/TestPlugInAdapter.h>
+#include <cppunit/plugin/TestPlugInDefaultImpl.h>
 
 
 /*! \def CPPUNIT_PLUGIN_IMPLEMENT_MAIN()
@@ -170,8 +181,8 @@ typedef CppUnitTestPlugIn *(*TestPlugInSignature)();
  * \see CppUnitTestPlugIn
  * \see CPPUNIT_PLUGIN_EXPORTED_FUNCTION_IMPL(), CPPUNIT_PLUGIN_IMPLEMENT_MAIN().
  */
-#define CPPUNIT_PLUGIN_IMPLEMENT()                                      \
-  CPPUNIT_PLUGIN_EXPORTED_FUNCTION_IMPL( CppUnit::TestPlugInAdapter );  \
+#define CPPUNIT_PLUGIN_IMPLEMENT()                                          \
+  CPPUNIT_PLUGIN_EXPORTED_FUNCTION_IMPL( CppUnit::TestPlugInDefaultImpl );  \
   CPPUNIT_PLUGIN_IMPLEMENT_MAIN()
 
 
diff --git a/include/cppunit/plugin/TestPlugInAdapter.h b/include/cppunit/plugin/TestPlugInDefaultImpl.h
index 0e54e0e..90d4398 100644
--- a/include/cppunit/plugin/TestPlugInAdapter.h
+++ b/include/cppunit/plugin/TestPlugInDefaultImpl.h
@@ -23,12 +23,12 @@ class TestSuite;
  * ( TestFactoryRegistry::getRegistry() ).
  *
  */
-class CPPUNIT_API TestPlugInAdapter : public CppUnitTestPlugIn
+class CPPUNIT_API TestPlugInDefaultImpl : public CppUnitTestPlugIn
 {
 public:
-  TestPlugInAdapter();
+  TestPlugInDefaultImpl();
 
-  virtual ~TestPlugInAdapter();
+  virtual ~TestPlugInDefaultImpl();
 
   void initialize( TestFactoryRegistry *registry,
                    const Parameters &parameters );
@@ -37,6 +37,10 @@ public:
 
   void removeListener( TestResult *eventManager );
 
+  void addXmlOutputterHooks( XmlOutputter *outputter );
+
+  void removeXmlOutputterHooks();
+
   void uninitialize( TestFactoryRegistry *registry );
 };
 
diff --git a/include/cppunit/tools/Makefile.am b/include/cppunit/tools/Makefile.am
index 7035ef7..d06fdb3 100644
--- a/include/cppunit/tools/Makefile.am
+++ b/include/cppunit/tools/Makefile.am
@@ -1,5 +1,6 @@
 libcppunitincludedir = $(includedir)/cppunit/tools
 
 libcppunitinclude_HEADERS = \
+	StringTools.h \
 	XmlElement.h \
 	XmlDocument.h
\ No newline at end of file
diff --git a/include/cppunit/tools/StringTools.h b/include/cppunit/tools/StringTools.h
new file mode 100644
index 0000000..8242c9e
--- /dev/null
+++ b/include/cppunit/tools/StringTools.h
@@ -0,0 +1,27 @@
+#ifndef CPPUNIT_TOOLS_STRINGTOOLS_H
+#define CPPUNIT_TOOLS_STRINGTOOLS_H
+
+#include <cppunit/Portability.h>
+#include <string>
+
+
+namespace CppUnit
+{
+
+/*! \brief Tool functions to manipulate string.
+ */
+namespace StringTools
+{
+
+  std::string CPPUNIT_API toString( int value );
+
+  std::string CPPUNIT_API toString( double value );
+
+
+} // namespace StringTools
+
+
+} //  namespace CppUnit
+
+
+#endif  // CPPUNIT_TOOLS_STRINGTOOLS_H
diff --git a/include/cppunit/tools/XmlElement.h b/include/cppunit/tools/XmlElement.h
index 323642e..760002d 100644
--- a/include/cppunit/tools/XmlElement.h
+++ b/include/cppunit/tools/XmlElement.h
@@ -22,23 +22,103 @@ class XmlElement;
 #endif
 
 
-/*! A XML Element.
+/*! \brief A XML Element.
+ * 
+ * A XML element has:
+ * - a name, specified on construction,
+ * - a content, specified on construction (may be empty),
+ * - zero or more attributes, added with addAttribute(),
+ * - zero or more child elements, added with addElement().
  */
 class CPPUNIT_API XmlElement
 {
 public:
+  /*! \brief Constructs an element with the specified name and string content.
+   * \param elementName Name of the element. Must not be empty.
+   * \param content Content of the element.
+   */
   XmlElement( std::string elementName,
               std::string content ="" );
+
+  /*! \brief Constructs an element with the specified name and numeric content.
+   * \param elementName Name of the element. Must not be empty.
+   * \param numericContent Content of the element.
+   */
   XmlElement( std::string elementName,
               int numericContent );
+
+  /*! \brief Destructs the element and its child elements.
+   */
   virtual ~XmlElement();
 
+  /*! \brief Returns the name of the element.
+   * \return Name of the element.
+   */
+  std::string name() const;
+
+  /*! \brief Returns the content of the element.
+   * \return Content of the element.
+   */
+  std::string content() const;
+
+  /*! \brief Sets the name of the element.
+   * \param name New name for the element.
+   */
+  void setName( const std::string &name );
+
+  /*! \brief Sets the content of the element.
+   * \param content New content for the element.
+   */
+  void setContent( const std::string &content );
+
+  /*! \overload.
+   */
+  void setContent( int numericContent );
+
+  /*! \brief Adds an attribute with the specified string value.
+   * \param attributeName Name of the attribute. Must not be an empty.
+   * \param value Value of the attribute.
+   */
   void addAttribute( std::string attributeName,
                      std::string value );
+
+  /*! \brief Adds an attribute with the specified numeric value.
+   * \param attributeName Name of the attribute. Must not be empty.
+   * \param value Numeric value of the attribute.
+   */
   void addAttribute( std::string attributeName,
                      int numericValue );
-  void addNode( XmlElement *element );
 
+  /*! \brief Adds a child element to the element.
+   * \param element Child element to add. Must not be \c NULL.
+   */
+  void addElement( XmlElement *element );
+
+  /*! \brief Returns the number of child elements.
+   * \return Number of child elements (element added with addElement()).
+   */
+  int elementCount() const;
+
+  /*! \brief Returns the child element at the specified index.
+   * \param index Zero based index of the element to return.
+   * \returns Element at the specified index. Never \c NULL.
+   * \exception std::invalid_argument if \a index < 0 or index >= elementCount().
+   */
+  XmlElement *elementAt( int index ) const;
+
+  /*! \brief Returns the first child element with the specified name.
+   * \param name Name of the child element to return.
+   * \return First child element found which is named \a name.
+   * \exception std::invalid_argument if there is no child element with the specified
+   *            name.
+   */
+  XmlElement *elementFor( const std::string &name ) const;
+
+  /*! \brief Returns a XML string that represents the element.
+   * \param indent String of spaces representing the amount of 'indent'.
+   * \return XML string that represents the element, its attributes and its
+   *         child elements.
+   */
   std::string toString( const std::string &indent = "" ) const;
 
 private:
@@ -46,7 +126,6 @@ private:
 
   std::string attributesAsString() const;
   std::string escape( std::string value ) const;
-  static std::string asString( int value );
 
 private:
   std::string m_name;