The Checkstyle Sensor is an Ant task that sends violations of code standards identified by Checkstyle to the Hackystat server. The Checkstyle sensor represents this metric data using the CodeIssue sensor data type, documented in Section 25.6, “CodeIssue”
Checkstyle is a tool that automates the process of checking Java code to ensure it adheres to a coding standards and generates a list of code standard violations. Table 26.4, “Checkstyle Metrics” lists the information gathered by the Checkstyle sensor and the languages for which they are collected.
Table 26.4. Checkstyle Metrics
| Metric | Description |
|---|---|
| Source File | The fully qualified name of the source file that was analyzed by checkstyle. |
| Error | The severity, message, and type of coding standard violation. |
![[Note]](gfx/admonitions/note.gif) | Note |
|---|---|
Currently, this sensor sends information to the Hackystat server only when a source file contains coding standard violations. Thus, the Hackystat server analyses cannot distinguish between files that have no coding standard violations and files that have not had this tool invoked on them. This means that this CodeIssue data is potentially susceptible to "false negatives" during analysis. | |
The Checkstyle sensor requires Java 1.5.0 or later, Ant 1.6.5 or later, and Checkstyle 4.2 or later.
Download and install Checkstyle from its home page. Section 4.11, “Measurement: Source code quality with Checkstyle” provides a recommended approach to Checkstyle installation for use with Hackystat.
Follow the instructions in Chapter 2, Client-side configuration: Tool sensor installation to set your Hackystat host and user key.
In the HackyInstaller main window, select the Checkstyle sensor and press "Configure Selected Sensor". Figure 26.8, “ Checkstyle sensor 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 Checkstyle 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 Checkstyle sensor requires the placement of a sensor executable into Ant's lib/ directory.
Example 26.12, “Example checkstyle.tool and checkstyle.sensor targets” illustrates the definition of checkstyle.tool and checkstyle.sensor targets.
Example 26.12. Example checkstyle.tool and checkstyle.sensor targets
<target name="checkstyle.tool" description="Checks the style of the sources and reports issues.">
<!-- Check for the CHECKSTYLE_HOME environment variable, failing the build if it can't be found. -->
<available file="${env.CHECKSTYLE_HOME}/${checkstyle.jar}" property="checkstyle.available"/>
<fail unless="checkstyle.available" message="Error: CHECKSTYLE_HOME not set or ${env.CHECKSTYLE_HOME}/${checkstyle.jar} not found."/>
<taskdef resource="checkstyletask.properties" classpath="${env.CHECKSTYLE_HOME}/${checkstyle.jar}" />
<mkdir dir="${checkstyle.dir}"/>
<checkstyle config="${env.CHECKSTYLE_HOME}/sun_checks.xml">
<fileset dir="${src.dir}" includes="**/*.java" />
<formatter type="plain"/>
<formatter type="xml" tofile="${checkstyle.dir}/checkstyle.xml"/>
</checkstyle>
</target>
<target name="checkstyle.sensor" description="Sends CodeIssue data to Hackystat using the Checkstyle Sensor.">
<!-- Define the checkstyle sensor taskdef, failing the build if the sensor is not installed. -->
<available classname="org.hackystat.sensor.checkstyle.CheckstyleSensor" property="checkstyle.sensor.available"/>
<fail unless="checkstyle.sensor.available" message="Error: Checkstyle sensor not installed."/>
<taskdef name="hacky-checkstyle" classname="org.hackystat.sensor.checkstyle.CheckstyleSensor"/>
<hacky-checkstyle verbose="true" >
<fileset dir="${checkstyle.dir}">
<include name="checkstyle.xml" />
</fileset>
</hacky-checkstyle>
</target>
For more details on these targets, see Section 4.11, “Measurement: Source code quality with Checkstyle”, which illustrates the installation and use of Checkstyle on a sample Java system called StackyHack.
To verify your Checkstyle sensor installation, invoke the target and check to see that data is sent to the server. Example 26.13, “Example Checkstyle output” shows the shell output from an example run with verbose= "on".
Example 26.13. Example Checkstyle output
C:\svn-csdl\StackyHack>ant checkstyle
Buildfile: build.xml
installBuildSensor:
init:
checkstyle:
[mkdir] Created dir: C:\svn-csdl\StackyHack\build\checkstyle
[checkstyle] C:\java\svn-csdl\StackyHack\src\edu\hawaii\stack\Stack.java:44:38:'-' is not preceeded with whitespace.
[checkstyle] C:\java\svn-csdl\StackyHack\src\edu\hawaii\stack\Stack.java:44:39:'-' is not followed by whitespace.
[hacky-checkstyle] Sensor enabled?: true
[hacky-checkstyle] Processing file: C:\java\svn-csdl\StackyHack\build\checkstyle\checkstyle.xml
[hacky-checkstyle] Hackystat data on 2 Code Issues sent to http://hackystat.ics.hawaii.edu/ (0 secs.)
BUILD SUCCESSFUL
Total time: 3 seconds
C:\svn-csdl\StackyHack>
The Checkstyle sensor will output a different message if the data was not sent successfully. The data was sent in less than a second, hence the "0 secs." output value.
Once you verify that Checkstyle data is being sent from the client using verbose mode, login to your account on your Hackystat server, and use the "List Sensor Data" command on the Extras page to verify that FileMetric data for today's date was received by the server for the Checkstyle tool, as illustrated in Figure 26.9, “ List Sensor Data with Checkstyle data ”.
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 Checkstyle sensor writes out a file called checkstyle.0.log to the .hackystat/logs directory that can be useful in debugging your installation. Under normal conditions, this file should look similar to Example 26.14, “checkstyle.0.log file for Checkstyle sensor”.
Example 26.14. checkstyle.0.log file for Checkstyle sensor
Hackystat Version: 7.0.1201 (December 1 2005 14:18:13)
SensorShell started at: 12/02/2005 21:33:28
Type 'help' for a list of commands.
Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.
Defined shell command: Dependency
Defined shell command: Issue
Defined shell command: CodeIssue
Defined shell command: EvolSdt
Defined shell command: Perf
Defined shell command: FileMetric
Defined shell command: ReviewIssue
Defined shell command: Activity
Defined shell command: Cli
Defined shell command: ReviewActivity
Defined shell command: Coverage
Defined shell command: UnitTest
Defined shell command: BuffTrans
Defined shell command: Commit
Defined shell command: Build
#> AutoSend [10]
AutoSend OK (set to 10 minutes)
AutoSend enabled every 10 minutes.
Checking for offline data to recover.
No offline data found.
#> CodeIssue [set, tool=Checkstyle]
set OK
#> CodeIssue [add, runtime=1133598528992, fileName=C:\java\svn-csdl\StackyHack\src\edu\hawaii\stack\Stack.java, type=com.puppycrawl.tools.checkstyle.checks.WhitespaceAroundCheck, data=severity=error,message='-' is not preceeded with whitespace.,line=44,column=38]
CodeIssue add OK (1)
#> CodeIssue [add, runtime=1133598528992, fileName=C:\java\svn-csdl\StackyHack\src\edu\hawaii\stack\Stack.java, type=com.puppycrawl.tools.checkstyle.checks.WhitespaceAroundCheck, data=severity=error,message='-' is not followed by whitespace.,line=44,column=39]
CodeIssue add OK (2)
#> send
Sending sensor data (12/02 22:28:49)
Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
Dependency: Send OK (No entries to send.)
AutoSend: AutoSend OK ('send' command ignored)
Issue: Send OK (No entries to send.)
CodeIssue: Send OK (2 entries)
EvolSdt: Send OK (No entries to send.)
Perf: Send OK (No entries to send.)
FileMetric: Send OK (No entries to send.)
ReviewIssue: Send OK (No entries to send.)
Activity: Send OK (No entries to send.)
Cli: Send OK (No entries to send.)
ReviewActivity: Send OK (No entries to send.)
Coverage: Send OK (No entries to send.)
Commit: Send OK (No entries to send.)
BuffTrans: Send OK (No entries to send.)
UnitTest: Send OK (No entries to send.)
Build: Send OK (No entries to send.)
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 checkstyle.0.log file.
A description of the problem you are having.
You probably don't want to have to invoke "ant checkstyle" manually each time you want metric data sent to Hackystat. It is better to have the checkstyle data calculated and sent to Hackystat automatically as a natural course of development. One strategy is to make the checkstyle target a dependent target of an "install" or "distribution" target so that structural data is recorded each time significant changes occur to the system. This provides a historical record of the structural evolution that can be later used by Hackystat analyses.
To disable Checkstyle data collection temporarily, invoke HackyInstaller, bring up the Checkstyle configuration window, and uncheck the "Enable Checkstyle sensor" property, and apply the setting. To permanently uninstall the Checkstyle sensor, press the "Uninstall" button and remove the Build targets from your Ant build.xml files.