The LOCC Sensor is an Ant task that sends structural metrics produced by LOCC to the Hackystat server. The LOCC sensor represents this metric data using the FileMetric sensor data type, documented in Section 25.11, “FileMetric”
LOCC is a tool for generating structural metrics through source code analysis. LOCC currently provides support for Java, C/C++, and C/C++ with the MPI library. The actual structural metrics sent depends upon the language being analyzed. For all languages, the required FileMetric SDT fields of "fileName", "fileType", and "totalLines" are provided. Table 26.10, “LOCC Optional Metrics” lists the additional structural metrics gathered by the LOCC sensor and the languages for which they are collected.
Table 26.10. LOCC Optional Metrics
| fileType(s) | Metric | Description |
|---|---|---|
| java, cpp | sourceLines | The number of non-comment lines of source code in the file. |
| java, cpp | commentLines | The number of comment lines in the file. |
| java, cpp | size | The size in bytes of the file. |
| java, cpp | runtime | A timestamp used to associate all FileMetric data collected at the same time. |
| java, cpp | lastMod | The time at which this file was last modified. |
| java | classCount | The number of classes in this file. |
| java | functionCount | The number of methods occuring in the source code. |
| java | functionSizeList | A string containing hyphen separated integers indicating the sourceLines associated with each function. |
| java | className | A fully qualified class name associated with this file. |
| cpp | stmt | The number of statements found in this file. |
| cpp | (various) | When the LOCC MPI size counter is used, counts of the various MPI constructs are provided as properties, including: MPI_Init, MPI_Send, MPI_DOUBLE, MPI_COMM_WORLD, MPI_Status, MPI_SUCCESS, MPI_Recv, MPI_Abort, MPI_Comm_rank, MPI_Finalize, MPI_Comm_size, and MPI_Barrier. |
![[Note]](gfx/admonitions/note.gif) | Note |
|---|---|
LOCC metrics for interfaces are not sent to the Hackystat server. This is due to a parsing configuration within the LOCC tool. Specifically, the parse tree built by LOCC does not currently provide a mechanism for retrieving the number of methods within an interface. Therefore, the value of Weighted Methods per Class (WMC) metric would always be zero (incorrect for all interfaces). Rather than display incorrect data, it was decided to omit interfaces entirely, especially because they comprise a small fraction of most source code. | |
The LOCC sensor requires Java 1.5.0 or later, Ant 1.6.5 or later, and LOCC 4.3 or later.
Download LOCC from its home page and install it locally. Section 4.5, “Measurement: System size with LOCC” provides a recommended approach to LOCC 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 LOCC sensor and press "Configure Selected Sensor". Figure 26.45, “ LOCC 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 LOCC 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 LOCC sensor requires the placement of a sensor executable into Ant's lib/ directory.
Example 26.59, “Example locc.tool and locc.sensor targets” illustrates one possible definition of such these targets.
Example 26.59. Example locc.tool and locc.sensor targets
<target name="locc.tool" depends="compile" description="Compute size data on the source code using LOCC.">
<!-- Verify that LOCC is installed. -->
<available file="${env.LOCC_HOME}/build/locc-all.jar" property="locc.available"/>
<fail unless="locc.available" message="Error: LOCC_HOME not set or locc.jar not found, indicating LOCC is not installed."/>
<taskdef name="locc" classname="csdl.locc.tools.ant.LOCCTaskdef" classpath="${env.LOCC_HOME}/build/locc-all.jar" />
<!-- Generate total size data in XML format. -->
<mkdir dir="${locc.dir}" />
<locc sizetype="javaline" outformat="xml" outfile="${locc.dir}/size.xml">
<fileset dir="${src.dir}" includes="**/*.java" />
</locc>
</target>
<target name="locc.sensor" description="Sends size data to Hackystat.">
<!-- Define the LOCC sensor taskdef, failing the build if the sensor is not installed. -->
<available classname="org.hackystat.sensor.locc.LoccSensor" property="locc.sensor.available"/>
<fail unless="locc.sensor.available" message="Error: Locc Sensor not installed."/>
<taskdef name="hacky-locc" classname="org.hackystat.sensor.locc.LoccSensor" />
<!-- Run the LOCC sensor and send the size data to Hackystat -->
<hacky-locc verbose="${hackystat.verbose.mode}">
<fileset dir="${locc.dir}">
<include name="size.xml" />
</fileset>
</hacky-locc>
</target>
For more details on these targets, see Section 4.5, “Measurement: System size with LOCC”, which illustrates the installation and use of LOCC on a sample Java system called StackyHack.
To verify your LOCC sensor installation, invoke the target and check to see that data is sent to the server. Example 26.60, “Example LOCC output” shows the shell output from an example run with verbose= "on".
Example 26.60. Example LOCC output
C:\cvs413\Stack>ant locc
Buildfile: build.xml
init:
checkstyle:
compile:
locc:
[mkdir] Created dir: C:\cvs413\Stack\build\locc
[locc] Summary: {Methods=13, Classes=5, Interfaces=0, Lines=116}
[hacky-locc] Sensor enabled?: YES
[hacky-locc] Processing file: C:\cvs413\Stack\build\locc\size.xml
[hacky-locc] Hackystat data on 5 LOCC files sent to http://hackystat.ics.hawaii.edu/ (0 secs.)
BUILD SUCCESSFUL
Total time: 3 seconds
The LOCC 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 LOCC 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 LOCC tool, as illustrated in Figure 26.46, “ List Sensor Data with LOCC 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 LOCC sensor writes out a file called locc.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.61, “locc.0.log file for LOCC sensor”.
Example 26.61. locc.0.log file for LOCC sensor
Hackystat Version: 6.3.1119 (November 19 2004 15:22:57)
SensorShell started at: 12/01/2004 11:58:50
Type 'help' for a list of commands.
Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.
Defined shell command: Activity
Defined shell command: Coverage
Defined shell command: UnitTest
Defined shell command: BuffTrans
Defined shell command: Perf
Defined shell command: Build
Defined shell command: FileMetric
#> AutoSend [10]
AutoSend OK (set to 10 minutes)
AutoSend enabled every 10 minutes.
Checking for offline data to recover.
No offline data found.
#> FileMetric [setTool, LOCC]
setTool OK
#> FileMetric [addFileMetric, LOCC, C:\cvs413\Stack\src\edu\hawaii\stack\ClearStack.java, edu.hawaii.stack.ClearStack, loc=11,sloc=11,cloc=21,numClasses=1,wmc=2,methodSizes=3-3,runtime=1101938330942, 1098844917000]
FileMetric addData OK (1 total)
#> FileMetric [addFileMetric, LOCC, C:\cvs413\Stack\src\edu\hawaii\stack\EmptyStackException.java, edu.hawaii.stack.EmptyStackException, loc=6,sloc=6,cloc=10,numClasses=1,wmc=1,methodSizes=3,runtime=1101938330942, 1065835947000]
FileMetric addData OK (2 total)
#> FileMetric [addFileMetric, LOCC, C:\cvs413\Stack\src\edu\hawaii\stack\Stack.java, edu.hawaii.stack.Stack, loc=48,sloc=48,cloc=53,numClasses=1,wmc=7,methodSizes=3-10-9-4-10-3-3,runtime=1101938330942, 1097713388000]
FileMetric addData OK (3 total)
#> FileMetric [addFileMetric, LOCC, C:\cvs413\Stack\src\edu\hawaii\stack\TestClearStack.java, edu.hawaii.stack.TestClearStack, loc=23,sloc=23,cloc=14,numClasses=1,wmc=1,methodSizes=14,runtime=1101938330942, 1095791705000]
FileMetric addData OK (4 total)
#> FileMetric [addFileMetric, LOCC, C:\cvs413\Stack\src\edu\hawaii\stack\TestStack.java, edu.hawaii.stack.TestStack, loc=28,sloc=28,cloc=17,numClasses=1,wmc=2,methodSizes=12-9,runtime=1101938330942, 1098917883000]
FileMetric addData OK (5 total)
#> send
Sending sensor data (12/01 11:58:51)
Activity: Send OK (No entries to send.)
Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
Coverage: Send OK (No entries to send.)
AutoSend: AutoSend OK ('send' command ignored)
BuffTrans: Send OK (No entries to send.)
UnitTest: Send OK (No entries to send.)
Build: Send OK (No entries to send.)
Perf: Send OK (No entries to send.)
FileMetric: Send OK (5 entries)
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 locc.0.log file.
A description of the problem you are having.
You probably don't want to have to invoke "ant locc" manually each time you want metric data sent to Hackystat. It is better to have the locc data calculated and sent to Hackystat automatically as a natural course of development. One strategy is to make the locc 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.
Although using Ant is the recommended way to invoke LOCC and the LOCC sensor, it is possible to invoke both tools from the command line. Example 26.62, “Command line invocation of LOCC and the LOCC sensor” illustrates how such command line invocation might look.
Example 26.62. Command line invocation of LOCC and the LOCC sensor
C:\Code\Test>java -cp sensorshell.jar;locc.jar csdl.locc.sys.LOCTotal -sizetype javaline -infiles *.java -outdir . -outformat xml -outfile locc-all.xml C:\Code\Test>C:\Code\Test>java -cp sensorshell.jar;sensor.locc.jar org.hackystat.stdext.sensor.ant.locc.LoccCliSensor -loccOutputFile locc-all.xml Hackystat data on 1 LOCC file sent to http://hackystat.ics.hawaii.edu/ C:\Code\Test>
To disable LOCC data collection temporarily, invoke HackyInstaller, bring up the LOCC configuration window, and uncheck the "Enable LOCC sensor" property, and apply the setting. To permanently uninstall the LOCC sensor, press the "Uninstall" button and remove the Build targets from your Ant build.xml files.