Generating XML Formatted ClearCase Baseline Reports

The preceding chapter illustrated how to generate baseline reports using Perl and the ClearCase command line. Amending these scripts to generate XML output instead of simple text output is relatively simple. For example, you could change one of the Perl print statements to output an XML activity element:

print "<activity name=\"$act_id\", headline=\"$act_title\">\n";

However, this would require a lot of work to verify that the XML you were hard-coding into the print statements was correct and well formed. A better approach would be to use an existing library to generate valid XML. Since Java already has such a set of libraries, and because I have illustrated how to create Ant tasks in Java, it makes sense to adopt a Java-based approach and create a new Ant task. Fortunately, such tasks have already been created and are available in the clearantlib library.

Using clearantlib to Generate Label and Baseline Reports

The clearantlib library has a number of tasks for reporting on ClearCase labels and baselines. There are two tasks (<cclabelreport> and <ccblreport>) to generate a report on the content of a label or baseline, as well as two tasks (<ccdifflabelreport> and <ccdiffblreport>) to generate a report on the difference (in terms of activities or versions) between labels or baselines. For example, if you wanted to produce a report on the contents of the Base ClearCase label RATLBANKMODEL_02_INT and send the output to the file cclabelreport.xml, you could write an Ant target similar to the following:

<target name="label-report">     <ca:cclabelreport          labelselector="RATLBANKMODEL_02_INT"          outfile="cclabelreport.xml"          dtduri="file:///C:/Views/RatlBankModel_bld/JavaTools/libs/baseline.dtd"/> </target>

As you can see from this example, <ccblreport> takes three attributes. Two of them are mandatory: the name of the label to report on via the labelselector attribute, and the XML output file to create via the outfile attribute. The third attribute, the location of the DTD for validation, is optional. It is useful if you will use the XML file as an input to some other tool or process. Here's an example of the XML file that would be created by this target:

[View full width]
<?xml version="1.0" encoding="UTF-8"?> <baseline name="RATLBANKMODEL_02_INT@\RatlBankProjects"     date="20060101.153357" author="alex" status="locked"     level="BUILT">         <version           name="C:\Views\RatlBankModel_int\RatlBankSources\model\etc\standard-targetgets .xml@@ \main\RatlBankModel_Int\2"/>         <version           name="C:\Views\RatlBankModel_int\RatlBankSources\model\etc\standard-macros.xml@@  \main\RatlBankModel_Int\2"/>     ... </baseline>

You report on the content of a ClearCase baseline in a similar way. For example, if you wanted to produce a baseline report on the UCM baseline RATLBANKMODEL_02_INT and send the output to the file ccbaselinereport.xml, you could write an Ant target similar to the following:

<target name="baseline-report">     <ca:ccblreport         baselineselector="RATLBANKMODEL_02_INT@\         ÂRatlBankProjects"         outfile="ccbaselinereport.xml"         dtduri="file:///C:/Views/RatlBankModel_bld/JavaTools/         Âlibs/baseline.dtd"/> </target>

As you can see, this example is very similar to the first. However, rather than a labelselector attribute, it has a baselineselector attribute and a corresponding output file. Here's an example of the XML file that would be created by this target:

[View full width]
<?xml version="1.0" encoding="UTF-8"?> <baseline name="RATLBANKMODEL_02_INT@\RatlBankProjects"     date="20060101.153357" author="alex" status="locked"      level="BUILT">      <activity name="RBPRO00000012" date="20060109.184621"        author="alex"        headline="deliver alex_RatlBankModel_Dev on 09/01/2006 18:46:15.">         <version            name="C:\Views\RatlBankModel_int\RatlBankSources\model\src\com\ratlbank\facade \Bank.java@@ \main\RatlBankModel_Int\2"/>         <version           name="C:\Views\RatlBankModel_int\RatlBankSources\model\src\com\ratlbank\model \TransRecord.java@@\main\RatlBankModel_Int\3"/>         <contributor name="RBPRO00000007"           date="20060109.183944"           author="alex"           headline="Implement balance transfer page">            <version              name="C:\Views\RatlBankModel_int\RatlBankSources\model\src\com\ratlbank\model \TransRecord.java@@\main\RatlBankModel_Int\alex_RatlBankModel_Dev\2"/>           <version             name="C:\Views\RatlBankModel_int\RatlBankSources\model\src\com\ratlbank\model \TransRecord.java@@ \main\RatlBankModel_Int\alex_RatlBankModel_Dev\1"/>         </contributor>     </activity> </baseline>

Creating an XSLT Stylesheet

To generate an HTML file from XML, you need to create an XSLT stylesheet file. An XSLT stylesheet basically contains the instructions for the transformation you want to perform on an XML file. In this case the transformation is to HTML, but it could be to another XML file. XSLT stylesheets are built on structures called templates. A template specifies what to look for in a source tree (such as the XML input document) and what to output to the result tree (such as the HTML output document). Here's a very basic template:

<xsl:template match="baseline">     <b><xsl:value-of select="@name"/></b> </xsl:template>

This example finds the baseline element in the XML input document and outputs the value of its name attribute in bold, as shown in the following:

RATLBANKMODEL_02_INT@\RatlBankProjects

You can use a number of capabilities in XSLT stylesheets. For example, you can apply a set of formatting instructions to a complete set of child elements using <xsl:for-each> or sort elements based on an attribute field using <xsl:sort>. A complete description of the XSLT language is beyond the scope of this book, but for more information refer to Hunter [Hunter04].

Listing 9.1 shows a complete example of an XSLT stylesheet for taking an XML baseline report generated by the <ccblreport> task and transforming it into HTML.

Listing 9.1. ccblreport.xsl Stylesheet

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="html"/> <xsl:template match="/"> <html>     <head>         <style type="text/css">             .clearcase tr th { color:#000000; font:normal 68%                 verdana,arial,helvetica; font-size: 68%; font-weight:                 bold; text-align:left; background:#a6caf0; }             .clearcase tr td { color:#000000; font:normal 68%                 verdana,arial,helvetica; font-size: 68%;                 background:#eeeee0; }         </style>     </head>     <body>     <xsl:call-template name="baselines"/>     </body> </html> </xsl:template> <!-- Baseline Details --> <xsl:template name="baselines"> <table  cellpadding="5" cellspacing="2" width="100%">     <xsl:for-each select="baseline">       <th colspan="2" align="left" font="+1">Baseline Details</th>        <tr valign="top">             <td>Name:</td> <td><xsl:value-of select="@name"/></td>        </tr>        <tr valign="top">             <td>Created:</td> <td><xsl:value-of select="@date"/></td>        </tr>        <tr valign="top">             <td>Created by:</td> <td><xsl:value-of                 select="@author"/></td>        </tr>        <tr valign="top">             <td>Status:</td> <td><xsl:value-of select="@status"/></td>        </tr>        <tr valign="top">             <td>Level:</td> <td><xsl:value-of select="@level"/></td>        </tr>        <xsl:call-template name="details"/>      </xsl:for-each> </table> </xsl:template> <!-- Activity and/or Version Details --> <xsl:template name="details"> <table  cellpadding="5" cellspacing="2" width="100%">     <!-- display activity or versions header -->     <xsl:choose>         <xsl:when test="count(activity) = 0">             <tr><th align="left">Versions</th></tr>         </xsl:when>         <xsl:otherwise>             <tr>                 <th align="left">Activity Name</th>                 <th align="left">Created</th>                 <th align="left">Created by</th>                 <th align="left">Headline</th>             </tr>         </xsl:otherwise>     </xsl:choose>     <!-- match UCM activities -->     <xsl:for-each select="activity">       <xsl:sort select="@date" order="descending"/>       <tr>           <td><xsl:value-of select="@name"/></td>           <td><xsl:value-of select="@date"/></td>           <td><xsl:value-of select="@author"/></td>           <td><xsl:value-of select="@headline"/></td>       </tr>       <xsl:for-each select="contributor">         <tr>           <td style="background: #dddde0" align="right">             <xsl:value-of select="@name"/></td>           <td style="background: #dddde0">             <xsl:value-of select="@date"/></td>           <td style="background: #dddde0">             <xsl:value-of select="@author"/></td>           <td style="background: #dddde0">             <xsl:value-of select="@headline"/></td>         </tr>       </xsl:for-each>     </xsl:for-each>     <!-- match ClearCase versions - also fallback for label report -->     <xsl:for-each select="version">         <tr>             <td colspan="4"><xsl:value-of select="@name"/></td>         </tr>     </xsl:for-each> </table> </xsl:template> </xsl:stylesheet>

This example has a built-in Cascading Style Sheets (CSS) definition (between the <style> elements at the top of the file). These are used to set the default look and feel of the HTML tables that the report will use. Another point to note is that all the activities are sorted according to the date they were created via the XSLT instruction:

<xsl:sort select="@date" order="descending"/>

Finally, all the contributors to an activity are offset using a <td align="right"> instruction and are presented in a different table background color. This makes it clear that they are aligned with a particular integration activity.

To transform an XML baseline or label into HTML, you can use the Ant <style> task:

 <target name="baseline-report"> <ca:ccblreport    baselineselector="RATLBANKMODEL_02_INT@\RatlBankProjects"    outfile="ccbaselinereport.xml"    dtduri="file:///C:/Views/RatlBankModel_bld/JavaTools/libs/baseline.dtd"/> <style in="ccbaselinereport.xml"   out="ccbaselinereport.html"   style="ccblreport.xsl"/>  </target>

This example takes the XML baseline report file ccbaselinereport.xml and transforms it into the HTML file ccbaselinereport.html using the XSLT stylesheet ccblreport.xsl from Listing 9.1. Figure 9.2 shows a baseline report that this stylesheet can create.

Figure 9.2. HTML baseline report

Similarly, Figure 9.3 shows a Base ClearCase label report that this same stylesheet can create.

Figure 9.3. HTML label report

The clearantlib library comes with a similar but more complex XSLT stylesheet. In particular, this stylesheet allows you to show or hide which element versions were changed for each activity. This report was illustrated in Figure 9.1.