XMLResultAggregator (Apache Ant API)
Date: 2016-04-09

org.apache.tools.ant.taskdefs.optional.junit

## Class XMLResultAggregator

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.taskdefs.optional.junit.XMLResultAggregator

- All Implemented Interfaces:
    java.lang.Cloneable, XMLConstants

      public class XMLResultAggregator
      extends Task
      implements XMLConstants

  Aggregates all <junit> XML formatter testsuite data under a specific directory and transforms the results via XSLT. It is not particularly clean but should be helpful while I am thinking about another technique.

  The main problem is due to the fact that a JVM can be forked for a testcase thus making it impossible to aggregate all testcases since the listener is (obviously) in the forked JVM. A solution could be to write a TestListener that will receive events from the TestRunner via sockets. This is IMHO the simplest way to do it to avoid this file hacking thing.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT_DIR` The default directory: `.`.
    `static java.lang.String` | `DEFAULT_FILENAME` the default file name: `TESTS-TestSuites.xml`
    `protected java.util.Vector` | `filesets` the list of all filesets, that should contains the xml to aggregate
    `protected int` | `generatedId` the current generated id
    `protected java.io.File` | `toDir` the directory to write the file to
    `protected java.lang.String` | `toFile` the name of the result file
    `protected java.util.Vector` | `transformers`

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

    - ### Fields inherited from interface org.apache.tools.ant.taskdefs.optional.junit.XMLConstants

      `ATTR_CLASSNAME, ATTR_ERRORS, ATTR_FAILURES, ATTR_ID, ATTR_MESSAGE, ATTR_NAME, ATTR_PACKAGE, ATTR_SKIPPED, ATTR_TESTS, ATTR_TIME, ATTR_TYPE, ATTR_VALUE, ERROR, FAILURE, HOSTNAME, PROPERTIES, PROPERTY, SYSTEM_ERR, SYSTEM_OUT, TESTCASE, TESTSUITE, TESTSUITES, TIMESTAMP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XMLResultAggregator()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addFileSet(FileSet fs)` Add a new fileset containing the XML results to aggregate
    `protected void` | `addTestSuite(org.w3c.dom.Element root, org.w3c.dom.Element testsuite)` Add a new testsuite node to the document.
    `protected org.w3c.dom.Element` | `createDocument()` Create a DOM tree.
    `AggregateTransformer` | `createReport()` Generate a report based on the document created by the merge.
    `void` | `execute()` Aggregate all testsuites into a single document and write it to the specified directory and file.
    `java.io.File` | `getDestinationFile()` Get the full destination file where to write the result.
    `protected java.io.File[]` | `getFiles()` Get all `.xml` files in the fileset.
    `void` | `setTodir(java.io.File value)` Set the destination directory where the results should be written.
    `void` | `setTofile(java.lang.String value)` Set the name of the aggregegated results file.
    `protected void` | `writeDOMTree(org.w3c.dom.Document doc, java.io.File file)` Write the DOM tree to a file.

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### filesets

          protected java.util.Vector filesets

      the list of all filesets, that should contains the xml to aggregate

    - #### toFile

          protected java.lang.String toFile

      the name of the result file

    - #### toDir

          protected java.io.File toDir

      the directory to write the file to

    - #### transformers

          protected java.util.Vector transformers

    - #### DEFAULT_DIR

          public static final java.lang.String DEFAULT_DIR

      The default directory: `.`. It is resolved from the project directory
      See Also:
        Constant Field Values

    - #### DEFAULT_FILENAME

          public static final java.lang.String DEFAULT_FILENAME

      the default file name: `TESTS-TestSuites.xml`
      See Also:
        Constant Field Values

    - #### generatedId

          protected int generatedId

      the current generated id

  - ### Constructor Detail

    - #### XMLResultAggregator

          public XMLResultAggregator()

  - ### Method Detail

    - #### createReport

          public AggregateTransformer createReport()

      Generate a report based on the document created by the merge.
      Returns:
        the report

    - #### setTofile

          public void setTofile(java.lang.String value)

      Set the name of the aggregegated results file. It must be relative from the `todir` attribute. If not set it will use `DEFAULT_FILENAME`
      Parameters:
        `value` - the name of the file.
      See Also:
        `setTodir(File)`

    - #### setTodir

          public void setTodir(java.io.File value)

      Set the destination directory where the results should be written. If not set if will use `DEFAULT_DIR`. When given a relative directory it will resolve it from the project directory.
      Parameters:
        `value` - the directory where to write the results, absolute or relative.

    - #### addFileSet

          public void addFileSet(FileSet fs)

      Add a new fileset containing the XML results to aggregate
      Parameters:
        `fs` - the new fileset of xml results.

    - #### execute

          public void execute()
                       throws BuildException

      Aggregate all testsuites into a single document and write it to the specified directory and file.
      Overrides:
        `execute` in class `Task`
      Throws:
        `BuildException` - thrown if there is a serious error while writing the document.

    - #### getDestinationFile

          public java.io.File getDestinationFile()

      Get the full destination file where to write the result. It is made of the `todir` and `tofile` attributes.
      Returns:
        the destination file where should be written the result file.

    - #### getFiles

          protected java.io.File[] getFiles()

      Get all `.xml` files in the fileset.
      Returns:
        all files in the fileset that end with a '.xml'.

    - #### writeDOMTree

          protected void writeDOMTree(org.w3c.dom.Document doc,
                          java.io.File file)
                               throws java.io.IOException

      Write the DOM tree to a file.
      Parameters:
        `doc` - the XML document to dump to disk.
        `file` - the filename to write the document to. Should obviously be a .xml file.
      Throws:
        `java.io.IOException` - thrown if there is an error while writing the content.

    - #### createDocument

          protected org.w3c.dom.Element createDocument()

      Create a DOM tree. Has 'testsuites' as firstchild and aggregates all testsuite results that exists in the base directory.

      Returns:
        the root element of DOM tree that aggregates all testsuites.

    - #### addTestSuite

          protected void addTestSuite(org.w3c.dom.Element root,
                          org.w3c.dom.Element testsuite)

      Add a new testsuite node to the document. The main difference is that it split the previous fully qualified name into a package and a name.

      For example: `org.apache.Whatever` will be split into `org.apache` and `Whatever`.

      Parameters:
        `root` - the root element to which the `testsuite` node should be appended.
        `testsuite` - the element to append to the given root. It will slightly modify the original node to change the name attribute and add a package one.