Unlike other Hackystat sensors, each of which provide specialized support for a single tool, the XmlData sensor is a "generic" sensor: it supports sensor data collection from any tool as long as the tool produces XML output in a specific format. The XmlData sensor can thus avoid the need to write a tool-specific Hackystat sensor when the tool can generate XML data. An example of such a tool is the SCLC code counting tool.
Example 26.73, “An example XML sensor data file” illustrates the kind of XML file that could be generated by a tool for processing by the XmlData sensor.
Example 26.73. An example XML sensor data file
<xmldata> <entry sdt="FileMetric" tool="MyCoolTool" fileType=".cpp" fileName="foo/foo.cpp" totalLines="9999" sourceLines="55"/> <entry sdt="DevEvent" tool="MyCoolTool" path="foo/foo.cpp" type="SizeCounting" /> </xmldata>
In this hypothetical example, the tool named "MyCoolTool" generated an XML file containing two instances of sensor data: one of type FileMetric and the other of type DevEvent. Let's see how this example satisfies the constraints imposed by the XmlData sensor.
First, each sensor data instance must be represented as a single XML tag within a single top-level tag. In the above example, the top level tag is <xmldata>, and each sensor data instance is represented by a single <entry> tag. These are convenient tag names, though any others are equally acceptable to XmlSensor.
Next, you can see that more than one kind of sensor data type can be provided within a single XML file. The value of the "sdt" attribute determines what additional attributes must be provided in the <entry> tag. For example, in the case of FileMetric data, the additional required attributes are "tool", "fileType", "fileName", and "totalLines", corresponding to the required entryattributes for this SDT. In the case of DevEvent data, the additional required attributes are "path" and "type".
All sensor data types support optional "properties" that are put onto the PropertyMap associated with each sensor data instance. The XmlData sensor assumes that any attributes that are not required by the SDT are intended for the property map. In the above example, the first sensor data instance contains a "sourceLines" attribute. This will be placed onto the property map for the associated FileMetric sensor data instance.
The XmlData sensor requires Java 1.5.0 or later and Ant 1.6.5 or later.
Follow the instructions in Chapter 2, Client-side configuration: Tool sensor installation to set your Hackystat host and user key.
The XmlDataSensor has two seperate interfaces, the Ant and command-line based sensors. The Ant based sensor allows users to send data to the Hackystat server via Ant. The command-line interface allows users to send data via the command-line.
To configure and install the Ant based sensor, in the HackyInstaller main window, select the XmlData-Ant sensor and press "Configure Selected Sensor". Figure 26.63, “ XmlData-Ant installer configuration window ” shows what the configuration window should look like after the path to Ant is set, the sensor is enabled, and the "Install" button has been pressed to install the sensor.
This sensor supports the following properties and paths:
Enable XmlData Ant Sensor: This property controls whether the sensor is active or not. If not checked, the sensor will not collect or send data even if installed.
Ant home directory: This path specifies the top-level directory for Ant. The XmlData-Ant sensor requires the placement of a sensor executable into Ant's lib/ directory if you wish to use its Ant task interface.
To configure and install the Command-Line based sensor, in the HackyInstaller main window, select the XmlData-Cli sensor and press "Configure Selected Sensor". Figure 26.64, “ XmlData-Cli installer configuration window ” shows what the configuration window should look like after home directory of the command-line sensor is set, the sensor is enabled, and the "Install" button has been pressed to install the sensor.
This sensor supports the following properties and paths:
Enable XmlData CLI Sensor: This property controls whether the sensor is active or not. If not checked, the sensor will not collect or send data even if installed.
XmlData Sensor home directory: This path specifies the installation directory for the XmlData-Cli sensor.
The XmlData sensor can be invoked either at the command line as a Java program, or as an Ant task.
Example 26.74, “Example of command-line invocation” illustrates CLI invocation of XmlData.
Example 26.74. Example of command-line invocation
C:\apache-ant-1.6.5\lib>java -jar sensor.xmldata.jar -file filemetric.xml junit.xml -sdt FileMetric Hackystat data on 2 XmlData file sent to http://hackystat.ics.hawaii.edu/ (0 secs.)
The XmlData sensor is invoked using "java -jar sensor.xmldata.jar", followed by one or more parameters and their associated arguments. XmlData then reads in the sensor.properties file to determine the hackystat host to send the data to, the user key to associate the data with, and whether it is enabled. If everything is OK, it processes the file, sends the data, and outputs a line indicating what it did.
The following table lists the parameters and arguments available for XmlData.
Table 26.15. XmlData CLI parameters
| Parameter and Arguments | Description |
|---|---|
-file <file> [<file>] ... | Specifies the name of one or more XML files to be processed by XmlData. |
-sdt <sdtName> | Specifies a "default" value for the sdt attribute if this attribute is not provided in an <entry> |
-createRunTime <runTimeAttributeName> | Some forms of sensor data are best analyzed if they contain a field with a timestamp that enables analyses to understand that a set of sensor data instances were all generated at the same time. The -createRunTime attribute tells XmlData to generate a timestamp (as a UTC long) and attach it to all sensor data instances in this invocation, using <runTimeAttributeName> as the attribute name. |
-nameMap <old-name> <new-name> | In some cases, a tool might generate an XML file in "almost" the right format, except that the names of attributes in each entry do not correspond to the entryattribute names for the associated sensor data type. To resolve this, the -nameMap attribute tells XmlData to map all occurrences of attributes with the name <old-name> to <new-name>. You can provide -nameMap multiple times. |
-argList <file> | In Windows, command lines are limited in length. If you need to create an exceptionally long invocation of XmlData, you can create a text file with the arguments separated by spaces or carriage returns and supply that to XmlData instead. Note: if you use the -argList parameter, that must be the only parameter supplied, so that the entire argument set is provided in the associated file. |
-verbose <true | false> | (Optional) If supplied with the value true, then additional information is printed. |
The xmldata.sensor.jar file includes the implementation of an Ant task that allows you to incorporate XmlData-based sending of sensor data into your build files. Example 26.75, “An XmlData ant task” illustrates a sample Ant target to run XmlData.
Example 26.75. An XmlData ant task
<target name="xmldata-sensor">
<taskdef name="hacky-xmldata" classname="org.hackystat.sensor.xmldata.XmlDataSensor"/>
<hacky-xmldata verbose="true" sdt="FileMetric" createRunTime="runtime" nameMap="fileName=fname, fileType=ftype">
<fileset dir="./src/org/hackystat/sensor/xmldata/testdataset/xmldatatestfiles/">
<include name="**/*.xml"/>
</fileset>
</hacky-xmldata>
</target>
In general, the Ant interface is equivalent to the CLI interface. Use a nested <fileset> to specify the set of XML data files instead of -file. Only one nameMap attribute can be supplied, so specify the mapping via a set of comma-delimted key-value pairs, as illustrated above. Finally, there is no need in the Ant interface for a feature corresponding to the -argList CLI parameter.
The first step in troubleshooting your sensor installation is to verify that your Hackystat host and key settings are valid and that you can contact the Hackystat server, as described in Section 2.4, “HackyInstaller GUI: Setting and verifying the Hackystat host and user key”
The XmlData writes out a file called toolName.0.log, where toolName is the name of the tool that generated data, to the .hackystat/logs directory that can be useful in debugging your installation. For example if the SCLC tool generated data, the log file would be called sclc.0.log.
If none of the above troubleshooting activities solves your problem, then you should send an email to your Hackystat Administrator to request help. Please include in your email the following information:
The output from 'java -version'.
The output from 'java -jar sensorshell.jar -verify'.
The contents of your sensor.properties file.
The contents of the toolName.0.log file.
A description of the problem you are having.
To disable XmlData sensor data collection temporarily from Ant or the command-line, invoke HackyInstaller, bring up the XmlData-Ant or XmlData-Cli configuration window, and uncheck the "Enable XmlData sensor" property, and apply the setting. To permanently uninstall the XmlData sensor, press the "Uninstall" button.