javancss
Class JavancssAntTask

java.lang.Object
  extended byMatchingTask
      extended byjavancss.JavancssAntTask

public class JavancssAntTask
extends MatchingTask

Ant task to report and check basic code metrics.

This task wraps the JavaNCSS library for determining code metrics. The library determines several code metrics such as object counts, non-commented source statements (NCSS), cyclomatic complexity numbers (CCN), and javadoc statements. These counts are subtotaled per function, class, and package. This task allows you to place minimum and maximum thresholds on each of these (not all of these make sence but all are included for completeness).

The original version of this task was written by Steve Jernigan and made available on SourceForge as the JavaNCSS2Ant project. It was subsequently extended by Phillip Wells to enable access to the report generation feature of the tool whereupon it was submitted for inclusion in Ant itself.

JavaNCSS was developed by Christoph Clemens Lee and is available here.

Author:
Phillip Wells, Steve Jernigan, Clemens Lee
See Also:
Serialized Form

Field Summary
private  boolean abortOnFail
          Whether the build should halt if there is an error or a threshold is exceeded.
private  int ccnPerFuncMax
          The maximum value of the Cyclomatic Complexity Number per function.
private  int ccnPerFuncMin
          The minimum value of the Cyclomatic Complexity Number per function.
private  boolean classMetrics
          Whether class metrics should be generated.
private  Path classpath
          The classpath to be used.
private  int classPerClassMax
          The maximum number of inner classes per class.
private  int classPerClassMin
          The minimum number of inner classes per class.
private  int classPerPkgMax
          The maximum number of classes per package.
private  int classPerPkgMin
          The minimum number of classes per package.
private  CommandlineJava commandline
          The command to be executed to run to tool.
private static int FAILURE
          Indicates the failure of the JavaNCSS process.
private  java.lang.String format
          The format of the output file.
private  int funcPerClassMax
          The maximum number of functions per class.
private  int funcPerClassMin
          The minimum number of functions per class.
private  int funcPerPkgMax
          The maximum number of functions per package.
private  int funcPerPkgMin
          The minimum number of functions per package.
private  boolean functionMetrics
          Whether function metrics should be generated.
private  boolean generateReport
          Whether to generate a report.
private  Javancss javancss
          The JavaNCSS object containing details of the code whose metrics are to be checked.
private  int jvdcPerClassMax
          The maximum number of javadoc comments per class.
private  int jvdcPerClassMin
          The minimum number of javadoc comments per class.
private  int jvdcPerFuncMax
          The maximum number of javadoc comments per function.
private  int jvdcPerFuncMin
          The minimum number of javadoc comments per function.
private  int ncssPerClassMax
          The maximum number of non-commenting source statements per class.
private  int ncssPerClassMin
          The minimum number of non-commenting source statements per class.
private  int ncssPerFuncMax
          The maximum number of non-commenting source statements per function.
private  int ncssPerFuncMin
          The minimum number of non-commenting source statements per function.
private  int ncssPerPkgMax
          The maximum number of non-commenting source statements per package.
private  int ncssPerPkgMin
          The minimum number of non-commenting source statements per package.
private  java.io.File outputfile
          The location of the output file.
private  boolean packageMetrics
          Whether package metrics should be generated.
private  java.io.File srcdir
          The directory containing the source files to be scanned by the tool.
private static int SUCCESS
          Indicates the success of the JavaNCSS process.
 
Constructor Summary
JavancssAntTask()
          Creates a new instance of the task.
 
Method Summary
private  boolean classThresholdExceeded(java.util.Vector classMetrics)
          Checks thresholds for the specified class or interface.
private  boolean classThresholdsExceeded(java.util.Vector fileList)
          Checks thresholds for all classes and interfaces.
private  java.util.Vector copyFiles(java.lang.String[] filesArray)
          Converts the specified array of filenames into a vector of paths.
 Path createClasspath()
          Maybe creates a nested classpath element.
private  java.io.File createSourceListFile(java.util.Vector fileList)
          Creates a temporary file containing a list of all source files to be analysed.
 void execute()
          Executes this task.
private  java.util.Vector findFilesToAnalyse()
          Builds a list of all files to be analysed.
private  boolean functionThresholdExceeded(java.util.Vector functionMetrics)
          Checks thresholds for the specified function.
private  boolean functionThresholdsExceeded(java.util.Vector fileList)
          Checks thresholds for all functions.
private  int generateReport(java.util.Vector fileList)
          Generates a report on the specified files.
private  java.lang.String[] getCommandLineArguments(java.util.Vector fileList)
          Gets the command line arguments to be sent to JavaNCSS.
private  Javancss getJavaNcss(java.util.Vector fileList)
          Gets the JavaNCSS object containing details of the code whose metrics are to be checked.
private  boolean packageThresholdExceeded(PackageMetric packageMetrics)
          Checks thresholds for the specified package.
private  boolean packageThresholdsExceeded(java.util.Vector fileList)
          Checks package thresholds for all packages.
 void setAbortOnFail(boolean abortOnFail)
          Sets whether the build should halt if there is an error or a threshold is exceeded.
 void setCcnPerFuncMax(int ccnPerFuncMax)
          Sets the maximum value of the Cyclomatic Complexity Number per function.
 void setCcnPerFuncMin(int ccnPerFuncMin)
          Sets the minimum value of the Cyclomatic Complexity Number per function.
 void setClassMetrics(boolean classMetrics)
          Whether class/interface metrics should be generated.
 void setClasspath(Path classpath)
          Set the classpath to be used.
 void setClassPerClassMax(int classPerClassMax)
          Sets the maximum number of inner classes per class.
 void setClassPerClassMin(int classPerClassMin)
          Sets the minimum number of inner classes per class.
 void setClassPerPkgMax(int classPerPkgMax)
          Sets the maximum number of classes per package.
 void setClassPerPkgMin(int classPerPkgMin)
          Sets the minimum number of classes per package.
 void setFormat(java.lang.String format)
          Sets the format of the output file.
 void setFuncPerClassMax(int funcPerClassMax)
          Sets the maximum number of functions per class.
 void setFuncPerClassMin(int funcPerClassMin)
          Sets the minimum number of functions per class.
 void setFuncPerPkgMax(int funcPerPkgMax)
          Sets the maximum number of functions per package.
 void setFuncPerPkgMin(int funcPerPkgMin)
          Sets the minimum number of functions per package.
 void setFunctionMetrics(boolean functionMetrics)
          Whether function metrics should be generated.
 void setGenerateReport(boolean generateReport)
          Whether a report should be generated.
 void setJvdcPerClassMax(int jvdcPerClassMax)
          Sets the maximum number of javadoc comments per class.
 void setJvdcPerClassMin(int jvdcPerClassMin)
          Sets the minimum number of javadoc comments per class.
 void setJvdcPerFuncMax(int jvdcPerFuncMax)
          Sets the maximum number of javadoc comments per function.
 void setJvdcPerFuncMin(int jvdcPerFuncMin)
          Sets the minimum number of javadoc comments per function.
 void setNcssPerClassMax(int ncssPerClassMax)
          Sets the maximum number of non-commenting source statements per class.
 void setNcssPerClassMin(int ncssPerClassMin)
          Sets the minimum number of non-commenting source statements per class.
 void setNcssPerFuncMax(int ncssPerFuncMax)
          Sets the maximum number of non-commenting source statements per function.
 void setNcssPerFuncMin(int ncssPerFuncMin)
          Sets the minimum number of non-commenting source statements per function.
 void setNcssPerPkgMax(int ncssPerPkgMax)
          Sets the maximum number of non-commenting source statements per package.
 void setNcssPerPkgMin(int ncssPerPkgMin)
          Sets the minimum number of non-commenting source statements per package.
 void setOutputfile(java.io.File outputfile)
          Sets the location of the output file.
 void setPackageMetrics(boolean packageMetrics)
          Whether package metrics should be generated.
 void setSrcdir(java.io.File srcdir)
          Sets the directory to be scanned by the tool.
private  boolean thresholdsExceeded(java.util.Vector fileList)
          Checks to see if the metrics of the specified files have exceeded any of the thresholds.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

commandline

private CommandlineJava commandline
The command to be executed to run to tool.


abortOnFail

private boolean abortOnFail
Whether the build should halt if there is an error or a threshold is exceeded.


srcdir

private java.io.File srcdir
The directory containing the source files to be scanned by the tool.


classpath

private Path classpath
The classpath to be used.


outputfile

private java.io.File outputfile
The location of the output file.


format

private java.lang.String format
The format of the output file. Allowable values are 'plain' or 'xml'.


FAILURE

private static final int FAILURE
Indicates the failure of the JavaNCSS process.

See Also:
Constant Field Values

SUCCESS

private static final int SUCCESS
Indicates the success of the JavaNCSS process.

See Also:
Constant Field Values

classPerPkgMax

private int classPerPkgMax
The maximum number of classes per package.


classPerPkgMin

private int classPerPkgMin
The minimum number of classes per package.


funcPerPkgMax

private int funcPerPkgMax
The maximum number of functions per package.


funcPerPkgMin

private int funcPerPkgMin
The minimum number of functions per package.


ncssPerPkgMax

private int ncssPerPkgMax
The maximum number of non-commenting source statements per package.


ncssPerPkgMin

private int ncssPerPkgMin
The minimum number of non-commenting source statements per package.


classPerClassMax

private int classPerClassMax
The maximum number of inner classes per class.


classPerClassMin

private int classPerClassMin
The minimum number of inner classes per class.


funcPerClassMax

private int funcPerClassMax
The maximum number of functions per class.


funcPerClassMin

private int funcPerClassMin
The minimum number of functions per class.


ncssPerClassMax

private int ncssPerClassMax
The maximum number of non-commenting source statements per class.


ncssPerClassMin

private int ncssPerClassMin
The minimum number of non-commenting source statements per class.


jvdcPerClassMax

private int jvdcPerClassMax
The maximum number of javadoc comments per class.


jvdcPerClassMin

private int jvdcPerClassMin
The minimum number of javadoc comments per class.


jvdcPerFuncMax

private int jvdcPerFuncMax
The maximum number of javadoc comments per function.


jvdcPerFuncMin

private int jvdcPerFuncMin
The minimum number of javadoc comments per function.


ccnPerFuncMax

private int ccnPerFuncMax
The maximum value of the Cyclomatic Complexity Number per function.


ccnPerFuncMin

private int ccnPerFuncMin
The minimum value of the Cyclomatic Complexity Number per function.


ncssPerFuncMax

private int ncssPerFuncMax
The maximum number of non-commenting source statements per function.


ncssPerFuncMin

private int ncssPerFuncMin
The minimum number of non-commenting source statements per function.


packageMetrics

private boolean packageMetrics
Whether package metrics should be generated.


classMetrics

private boolean classMetrics
Whether class metrics should be generated.


functionMetrics

private boolean functionMetrics
Whether function metrics should be generated.


generateReport

private boolean generateReport
Whether to generate a report.


javancss

private Javancss javancss
The JavaNCSS object containing details of the code whose metrics are to be checked.

Constructor Detail

JavancssAntTask

public JavancssAntTask()
Creates a new instance of the task.

Method Detail

setFormat

public void setFormat(java.lang.String format)
Sets the format of the output file.

Parameters:
format - the format of the output file. Allowable values are 'plain' or 'xml'.

setPackageMetrics

public void setPackageMetrics(boolean packageMetrics)
Whether package metrics should be generated.

Parameters:
packageMetrics - true if they should; false otherwise.

setClassMetrics

public void setClassMetrics(boolean classMetrics)
Whether class/interface metrics should be generated.

Parameters:
classMetrics - true if they should; false otherwise.

setFunctionMetrics

public void setFunctionMetrics(boolean functionMetrics)
Whether function metrics should be generated.

Parameters:
functionMetrics - true if they should; false otherwise.

setGenerateReport

public void setGenerateReport(boolean generateReport)
Whether a report should be generated. Default is false.

Parameters:
generateReport - true if they should; false otherwise.

setSrcdir

public void setSrcdir(java.io.File srcdir)
Sets the directory to be scanned by the tool. This should be the directory containing the source files whose metrics are to be analysed.

Parameters:
srcdir - the directory to be scanned by the tool.

setOutputfile

public void setOutputfile(java.io.File outputfile)
Sets the location of the output file.

Parameters:
outputfile - the location of the output file.

setClasspath

public void setClasspath(Path classpath)
Set the classpath to be used.

Parameters:
classpath - the classpath to be used.

setAbortOnFail

public void setAbortOnFail(boolean abortOnFail)
Sets whether the build should halt if there is an error or a threshold is exceeded.

Parameters:
abortOnFail - true if it should; false otherwise.

execute

public void execute()
             throws BuildException
Executes this task.

Throws:
BuildException - if an error occurs.

generateReport

private int generateReport(java.util.Vector fileList)
Generates a report on the specified files.

Parameters:
fileList - the files to be analysed.
Returns:
SUCCESS if there were no errors; otherwise FAILURE.
Throws:
BuildException - if an error occurs whilst generating the report.

thresholdsExceeded

private boolean thresholdsExceeded(java.util.Vector fileList)
Checks to see if the metrics of the specified files have exceeded any of the thresholds.

Parameters:
fileList - the files to be analysed.
Returns:
true if any of the thresholds have been exceeded; false otherwise.

findFilesToAnalyse

private java.util.Vector findFilesToAnalyse()
Builds a list of all files to be analysed. We need to do this when testing thresholds as the Javancss object does not have a constructor that lets us make use of the -recursive option


copyFiles

private java.util.Vector copyFiles(java.lang.String[] filesArray)
Converts the specified array of filenames into a vector of paths.

Parameters:
filesArray - an array of filenames.
Returns:
a vector of paths. The path is constructed by prepending this task's source directory to each filename.

createClasspath

public Path createClasspath()
Maybe creates a nested classpath element.


getCommandLineArguments

private java.lang.String[] getCommandLineArguments(java.util.Vector fileList)
Gets the command line arguments to be sent to JavaNCSS.

Parameters:
fileList - a list of all source files to be analysed.
Returns:
the command line arguments to be sent to JavaNCSS.

createSourceListFile

private java.io.File createSourceListFile(java.util.Vector fileList)
Creates a temporary file containing a list of all source files to be analysed.

Parameters:
fileList - the source files to be analysed.
Returns:
a file containing a list of all specified source files.

getJavaNcss

private Javancss getJavaNcss(java.util.Vector fileList)
Gets the JavaNCSS object containing details of the code whose metrics are to be checked.

Parameters:
fileList - the files to be analysed.
Returns:
the JavaNCSS object containing details of the code whose metrics are to be checked.

packageThresholdsExceeded

private boolean packageThresholdsExceeded(java.util.Vector fileList)
Checks package thresholds for all packages.

Parameters:
fileList - the files to be analysed.
Returns:
true if a threshold has been exceeded; false otherwise.

packageThresholdExceeded

private boolean packageThresholdExceeded(PackageMetric packageMetrics)
Checks thresholds for the specified package.

Parameters:
packageMetrics - the metrics of the package under test.
Returns:
true if a threshold has been exceeded; false otherwise.

classThresholdsExceeded

private boolean classThresholdsExceeded(java.util.Vector fileList)
Checks thresholds for all classes and interfaces.

Parameters:
fileList - the files to be analysed.
Returns:
true if a threshold has been exceeded; false otherwise.

classThresholdExceeded

private boolean classThresholdExceeded(java.util.Vector classMetrics)
Checks thresholds for the specified class or interface.

Parameters:
classMetrics - the metrics of the class or interface under test.
Returns:
true if a threshold has been exceeded; false otherwise.

functionThresholdsExceeded

private boolean functionThresholdsExceeded(java.util.Vector fileList)
Checks thresholds for all functions.

Parameters:
fileList - the files to be analysed.
Returns:
true if a threshold has been exceeded; false otherwise.

functionThresholdExceeded

private boolean functionThresholdExceeded(java.util.Vector functionMetrics)
Checks thresholds for the specified function.

Parameters:
functionMetrics - the metrics of the function under test.
Returns:
true if a threshold has been exceeded; false otherwise.

setClassPerPkgMax

public void setClassPerPkgMax(int classPerPkgMax)
Sets the maximum number of classes per package.

Parameters:
classPerPkgMax - the maximum number of classes per package.

setClassPerPkgMin

public void setClassPerPkgMin(int classPerPkgMin)
Sets the minimum number of classes per package.

Parameters:
classPerPkgMin - the minimum number of classes per package.

setFuncPerPkgMax

public void setFuncPerPkgMax(int funcPerPkgMax)
Sets the maximum number of functions per package.

Parameters:
funcPerPkgMax - the maximum number of functions per package.

setFuncPerPkgMin

public void setFuncPerPkgMin(int funcPerPkgMin)
Sets the minimum number of functions per package.

Parameters:
funcPerPkgMin - the minimum number of functions per package.

setNcssPerPkgMax

public void setNcssPerPkgMax(int ncssPerPkgMax)
Sets the maximum number of non-commenting source statements per package.

Parameters:
ncssPerPkgMax - the maximum number of non-commenting source statements per package.

setNcssPerPkgMin

public void setNcssPerPkgMin(int ncssPerPkgMin)
Sets the minimum number of non-commenting source statements per package.

Parameters:
ncssPerPkgMin - the minimum number of non-commenting source statements per package.

setClassPerClassMax

public void setClassPerClassMax(int classPerClassMax)
Sets the maximum number of inner classes per class.

Parameters:
classPerClassMax - the maximum number of inner classes per class.

setClassPerClassMin

public void setClassPerClassMin(int classPerClassMin)
Sets the minimum number of inner classes per class.

Parameters:
classPerClassMin - the minimum number of inner classes per class.

setFuncPerClassMax

public void setFuncPerClassMax(int funcPerClassMax)
Sets the maximum number of functions per class.

Parameters:
funcPerClassMax - the maximum number of functions per class.

setFuncPerClassMin

public void setFuncPerClassMin(int funcPerClassMin)
Sets the minimum number of functions per class.

Parameters:
funcPerClassMin - the minimum number of functions per class.

setNcssPerClassMax

public void setNcssPerClassMax(int ncssPerClassMax)
Sets the maximum number of non-commenting source statements per class.

Parameters:
ncssPerClassMax - the maximum number of non-commenting source statements per class.

setNcssPerClassMin

public void setNcssPerClassMin(int ncssPerClassMin)
Sets the minimum number of non-commenting source statements per class.

Parameters:
ncssPerClassMin - the minimum number of non-commenting source statements per class.

setJvdcPerClassMax

public void setJvdcPerClassMax(int jvdcPerClassMax)
Sets the maximum number of javadoc comments per class.

Parameters:
jvdcPerClassMax - the maximum number of javadoc comments per class.

setJvdcPerClassMin

public void setJvdcPerClassMin(int jvdcPerClassMin)
Sets the minimum number of javadoc comments per class.

Parameters:
jvdcPerClassMin - the minimum number of javadoc comments per class.

setCcnPerFuncMax

public void setCcnPerFuncMax(int ccnPerFuncMax)
Sets the maximum value of the Cyclomatic Complexity Number per function.

Parameters:
ccnPerFuncMax - the maximum value of the Cyclomatic Complexity Number per function.

setCcnPerFuncMin

public void setCcnPerFuncMin(int ccnPerFuncMin)
Sets the minimum value of the Cyclomatic Complexity Number per function.

Parameters:
ccnPerFuncMin - the minimum value of the Cyclomatic Complexity Number per function.

setNcssPerFuncMax

public void setNcssPerFuncMax(int ncssPerFuncMax)
Sets the maximum number of non-commenting source statements per function.

Parameters:
ncssPerFuncMax - the maximum number of non-commenting source statements per function.

setNcssPerFuncMin

public void setNcssPerFuncMin(int ncssPerFuncMin)
Sets the minimum number of non-commenting source statements per function.

Parameters:
ncssPerFuncMin - the minimum number of non-commenting source statements per function.

setJvdcPerFuncMax

public void setJvdcPerFuncMax(int jvdcPerFuncMax)
Sets the maximum number of javadoc comments per function.

Parameters:
jvdcPerFuncMax - the maximum number of javadoc comments per function.

setJvdcPerFuncMin

public void setJvdcPerFuncMin(int jvdcPerFuncMin)
Sets the minimum number of javadoc comments per function.

Parameters:
jvdcPerFuncMin - the minimum number of javadoc comments per function.