• 1.0 Introduction
• 1.1 Installing antsensors.jar
• 2.0 Sensor Reference
• 2.1 Ant Build Sensor
• 2.2 Checkstyle Sensor
• 2.3 Emma Sensor
• 2.4 Find Bugs Sensor
• 2.5 JUnit Sensor
• 2.6 PMD Sensor
• 2.7 Subversion Sensor
• 2.8 Clover Sensor
• 2.9 JavaNCSS Sensor
• 2.10 JDepend Sensor
• 2.11 Dependency Finder Sensor
• 2.12 Perforce Sensor
• 2.13 Issue Sensor
• 3.0 Advanced Sensor Attributes
• 3.1 About tool and toolAccount attributes
• 3.2 About retryAttempts and retryWaitInterval attributes

1.0 Introduction

This page demonstrates how to use each Ant based sensor. All sensors are run using Ant tasks except for the Ant build sensor. This quick reference assumes the user is familiar with Ant.

1.1 Installing antsensors.jar

The antsensors.jar file should be installed in ~/.ant/lib.

If you are using the build system files in either hackystat-sensor-example or hackystat-developer-example, then "ant install-sensors" will download the most recently released version of antsensors.jar file and place it in that directory.

Otherwise, you can download a binary distribution of the Hackystat sensors and manually copy the antsensors.jar file to this directory.

2.0 Sensor Reference

2.1 Ant Build Sensor

The Ant Build Sensor sends a single sensor data instance of type "Build" indicating the success or failure of the current Build.

Please note that unlike the other Ant sensors, the Ant build sensor is not defined as an Ant task, but rather as an Ant "listener". Because of this, the Ant build sensor is installed by providing special values to the ANT_ARGS and ANT_OPTS environment variables.

The ANT_ARGS environmental variable must specify the listener class associated with this listener. For example:

ANT_ARGS="-listener org.hackystat.sensor.ant.antbuild.BuildSensorAntListener"

Make sure that antsensors.jar has been downloaded into ~/.ant/lib before you define this listener, otherwise Ant will fail with a class not found error.

This will add the Ant build sensor as a listener to the Ant build each time Ant is invoked. After the completion of the build, data will automatically be sent to the Hackystat server.

The Ant build sensor has a few optional properties that can be specified using the ANT_OPTS environmental variable. The following table lists the properties and their descriptions.

When using these properties the -D argument should be used in conjunction with the ANT_OPTS option. It should be similar to the following:

ANT_OPTS="-Dhackystat.ant.tool=ant -Dhackystat.ant.toolAccount=jsakuda"

2.2 Checkstyle Sensor

The Checkstyle sensor generates at least one sensor data instance of type "CodeIssue" for each of the Java files processed by Checkstyle.

Example:

<target name="checkstyle.sensor" unless="checkstyle.disabled" description="Sends CodeIssue data to Hackystat using the Checkstyle Sensor.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-checkstyle verbose="false" failOnError="true">
    <datafiles>
      <fileset file="${checkstyle.dir}/checkstyle.xml"/>
    </datafiles>
  </hacky-checkstyle>
</target>

2.3 Emma Sensor

The Emma sensor generates one sensor data instance per file containing a Java class with the type "Coverage".

Example:

<target name="emma.sensor" unless="emma.disabled" description="Sends Emma coverage data to Hackystat using the Emma sensor.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-emma verbose="false" failOnError="true">
    <datafiles>
      <fileset file="${emma.dir}/coverage.xml"/>
    </datafiles>
    <sourcefiles>
      <fileset dir="${src.dir}" includes="**/*.java" />
    </sourcefiles>
  </hacky-emma>
</target>

2.4 Find Bugs Sensor

The FindBugs sensor generates one sensor data instance of type "CodeIssue" for each of the Java files processed by FindBugs.

Example:

<target name="findbugs.sensor" unless="findbugs.disabled" description="Sends CodeIssue data to Hackystat using the Findbugs sensor.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-findbugs verbose="false" failOnError="true">
    <datafiles>
      <fileset file="${findbugs.dir}/findbugs.xml"/>
    </datafiles>
  </hacky-findbugs>
</target>

2.5 JUnit Sensor

The JUnit sensor generates one sensor data instance of type "UnitTest" for each of the Java files containing JUnit test code.

Example:

<target name="junit.sensor" unless="junit.disabled" description="Sends UnitTest data to Hackystat using the JUnit sensor.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-junit verbose="true" failOnError="true">
    <sourcefiles>
      <fileset dir="${src.dir}" includes="**/*.java"/>
    </sourcefiles>
    <datafiles>
      <fileset dir="${junit.dir}" includes="TEST-*.xml" />
    </datafiles>
  </hacky-junit>
</target>

2.6 PMD Sensor

The PMD sensor generates one sensor data instance of type "CodeIssue" for each of the Java files processed by PMD.

Example:

<target name="pmd.sensor" description="Sends CodeIssue data to Hackystat using the PMD sensor.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-pmd verbose="false">
    <datafiles>
      <fileset file="${pmd.dir}/pmd.xml" />
    </datafiles>
    <sourcefiles>
      <fileset dir="${src.dir}" includes="**/*.java" excludes="**/jaxb/**" />
    </sourcefiles>
  </hacky-pmd>
</target>  

2.7 Subversion Sensor

The Subversion sensor generates one sensor data instance of type "Commit" for each of the files committed to Subversion during the specified time interval.

Example:

<target name="subversion.sensor" description="Sends Subversion commit data to Hackystat using the Subversion sensor.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-svn  
    repositoryName="Hackystat"
    repositoryUrl="https://hackystat-sensor-xmldata.googlecode.com/svn/trunk"
    userName="testUser"
    password="testPassword"
    fromDate="2007-10-16" 
    toDate="2007-11-16"
    defaultHackystatAccount="test@gmail.com"
    defaultHackystatPassword="testing" 
    defaultHackystatSensorbase="http://localhost:9876/sensorbase"
    verbose="true" />
</target>

Note that you will typically want to set up a UserMap.xml file in order to send Commit data to the correct Hackystat account.

2.8 Clover Sensor

The Clover sensor generates one sensor data instance per file containing a Java class with the type "Coverage".

Example:

<target name="clover.sensor" unless="clover.disabled" description="Sends Clover coverage data to Hackystat using the Clover sensor.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-clover verbose="false" failOnError="true">
    <datafiles>
      <fileset file="${clover.dir}/coverage.xml"/>
    </datafiles>
    <sourcefiles>
      <fileset dir="${src.dir}" includes="**/*.java" />
    </sourcefiles>
  </hacky-clover>
</target>

2.9 JavaNCSS Sensor

The JavaNCSS sensor generates one sensor data instance per file containing a Java class with the type "FileMetric". It sends sensor data containing the TotalLines for the Java class, as well as a property called "CyclomaticComplexityList" that is a string containing a comma-separated list of integers, such as "10,3,4,2". This string represents the cyclometic complexity value obtained for each of the methods found in that class.

Example:

<target name="javancss.sensor" description="Sends JavaNCSS FileMetric data to Hackystat.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-javancss verbose="false" failOnError="true">
    <sourcefiles>
      <fileset dir="${src.dir}" includes="**/*.java" />
    </sourcefiles>
    <datafiles>
      <fileset file="${javancss.dir}/javancss.xml" />
    </datafiles>
  </hacky-javancss>
</target>

2.10 JDepend Sensor

The JDepend sensor generates one sensor data instance per Java package with the type "Coupling". It sends sensor data containing the afferent and efferent coupling for each Java package in the system.

Example:

  <target name="jdepend.sensor" unless="jdepend.disabled" description="Sends coupling data to Hackystat using the JavaNCSS sensor.">
    <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
    <hacky-jdepend verbose="${hackystat.verbose.mode}" failOnError="true">
      <sourcefiles>
        <fileset dir="${src.dir}" includes="**/*.java" />
      </sourcefiles>
      <datafiles>
        <fileset file="${jdepend.dir}/jdepend.xml" />
      </datafiles>
    </hacky-jdepend>
  </target>

2.11 Dependency Finder Sensor

The DependencyFinder sensor generates one sensor data instance per file containing a Java class with the type "Coupling". It sends sensor data containing the afferent and efferent coupling for each Java class in the system.

Example:

 <target name="dependencyfinder.sensor" unless="dependencyfinder.disabled" description="Sends coupling data to Hackystat using the DependencyFinder sensor.">
   <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
   <hacky-dependencyfinder verbose="${hackystat.verbose.mode}" failOnError="true">
       <datafiles>
         <fileset file="${dependencyfinder.dir}/class2class.xml"/>
       </datafiles>
       <sourcefiles>
         <fileset dir="${src.dir}" includes="**/*.java" />
       </sourcefiles>
     </hacky-dependencyfinder>
   </target>

2.12 Perforce Sensor

The Perforce sensor generates one sensor data instance of type "Commit" for each of the files committed to Perforce during the specified time interval.

The Perforce sensor is built on top of the Perforce Java API, which is in turn built upon the Perforce P4 Client.

To begin, you must have the Perforce P4 client installed in your environment. You will need to include the path to the p4 executable as an argument to the Ant task.

Example:

<target name="perforce.sensor" description="Sends Perforce commit data to Hackystat using the Perforce sensor.">
    <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
    <hacky-perforce depotPath="//guest/philip_johnson/..."
                    p4ExecutablePath="C:\\Program Files\Perforce\P4.EXE"
                    port="public.perforce.com:1666"
                    userName="philip_johnson"
                    password="foo"
                    fileNamePrefix="/hackystat-integration/"
                    defaultHackystatAccount="johnson@hawaii.edu"
                    defaultHackystatPassword="foo"
                    defaultHackystatSensorbase="http://dasha.ics.hawaii.edu:9876/sensorbase"
                    verbose="true"
  </target>

Note that you will typically want to set up a UserMap.xml file in order to send Commit data to the correct Hackystat account.

Sample output:

perforce.sensor:
[hacky-perforce] Processing changelists for public.perforce.com:1666 //guest/philip_johnson/... between Sun Jul 13 23:59:59 HST 2008 and Wed Jul 16 23:59:59 HST 2008. 
[hacky-perforce] Checking for user maps at: /Users/johnson/.hackystat/sensorshell/usermap/UserMap.xml
[hacky-perforce] Perforce accounts found: []
[hacky-perforce] Retrieved Perforce changelist: 6418
[hacky-perforce] Sending Perforce Commit: Timestamp: 2008-07-15T00:00:00.000-10:00 Resource: file://hackystat//guest/philip_johnson/test.txt User: johnson@hawaii.edu
[hacky-perforce] Retrieved Perforce changelist: 6417
[hacky-perforce] Sending Perforce Commit: Timestamp: 2008-07-15T00:00:00.001-10:00 Resource: file://hackystat//guest/philip_johnson/test.txt User: johnson@hawaii.edu
[hacky-perforce] Found 2 commit records.
[hacky-perforce] Sending data to johnson@hawaii.edu at http://dasha.ics.hawaii.edu:9876/sensorbase/

Implementation note: the Perforce sensor creates a new unique "Client" instance for each run of the sensor, whose name is "hackystat-sensor-{timestamp}", where {timestamp} is a long indicating the current time. Under normal circumstances, this Client instance will be deleted at the end of the run. If the run terminates abnormally, it is possible that the Client instance might not be deleted from the server. Since Client instances can use up a Perforce license, you may want to occasionally check the Perforce server to ensure that there are no "hackystat-sensor-{timestamp}" Client instances under the user account for the sensor.

2.13 Issue Sensor

The Issue sensor maintain one sensor data instance of type "Issue" for each of the issue. Update information will be put into the properties list with updated value and update timestamp. The data owner of that particular sensor data is defined in ant task attributes, which describe following. Make sure all issue sensors are configured to the same data owner if you decide to run it in multiple environments, in order to avoid duplicate data instance. It is preferred to only run the issue sensor in a single place, for example in Hudson daily build.

Example:

<target name="issue.sensor" description="Sends Issue update data to Hackystat using the Issue sensor.">
  <taskdef resource="antlib.xml" classpath="${user.home}/.ant/lib/antsensors.jar" />
  <hacky-issue  
    projectName="hackystat-sensor-ant"
    dataOwnerHackystatAccount="TestUser@hackystat.org"
    dataOwnerHackystatPassword="TestUser@hackystat.org" 
    hackystatSensorbase="http://localhost:9876/sensorbase"
    verbose="true" />
</target>

3.0 Advanced Sensor Attributes

3.1 About tool and toolAccount attributes

Some sensor tasks will refer to tool and toolAccount. This refers to the Hackystat UserMap feature that allows data to be sent to accounts other than the one specified in the user's sensorshell.properties file. For more information on UserMap please see the User Map Reference Guide.

3.2 About retryAttempts and retryWaitInterval attributes

In some cases, you may be trying to send relatively large amounts of sensor data over a network with intermittent connectivity drop-outs. In this case, you may find that the sensor fails and throws an exception due to network problems. To ameliorate this issue, the "retryAttempts" and "retryWaitInterval" attributes allow you to automatically re-attempt sensor data transmission after waiting a certain interval of time.

To illustrate this behavior, here is a run of the PMD sensor when the user password is specified incorrectly and offline storage is disabled, resulting in sensor failure. The retryAttempts attribute was set to "3" and the retryWaitInterval was set to "5":

pmd.sensor:
[hacky-pmd] Sensor failed: [Hackystat PMD Sensor] ERROR: Problem during quit() of SensorShell Server not available and offline storage disabled. Sensor Data lost.
[hacky-pmd] Retrying (3 retries remaining.)
[hacky-pmd] Pausing for: 5 seconds.
[hacky-pmd] Sensor failed: [Hackystat PMD Sensor] ERROR: Problem during quit() of SensorShell Server not available and offline storage disabled. Sensor Data lost.
[hacky-pmd] Retrying (2 retries remaining.)
[hacky-pmd] Pausing for: 5 seconds.
[hacky-pmd] Sensor failed: [Hackystat PMD Sensor] ERROR: Problem during quit() of SensorShell Server not available and offline storage disabled. Sensor Data lost.
[hacky-pmd] Retrying (1 retries remaining.)
[hacky-pmd] Pausing for: 5 seconds.

BUILD FAILED
C:\hackystat-projects\hackystat-sensor-example\pmd.build.xml:44: [Hackystat PMD Sensor] ERROR: Problem during quit() of SensorShell Server not available and offline storage disabled. Sensor Data lost.

Total time: 18 seconds

As you can see, the sensor retried to send the data three times after its initial failure before finally failing the build. The build paused for five seconds between each retry attempt.

Of course, in a real setting, the hope is that whatever network problem occurred initially would resolve itself upon a subsequent retry and the build would eventually succeed.