Customising which tools are run.

The "sanity4j.toolsToRun" property controls which tools will be run by Sanity4J. Multiple tools can be listed here, in a comma-separated list. The Available tools are listed in the table below.

The default value for this parameter is:

sanity4j.toolsToRun=checkstyle,jacoco-merge,jacoco,spotbugs,pmd,pmd-cpd

Customising tool configuration.

The command line used to run each tool is specified by parameters of the form: sanity4j.tool.tool.version.command.

The default command line used by each tool may not be appropriate to your project, so the tool command lines can be modified as necessary. i.e. you may wish to modify the JDK used, JVM performance options, or the command line options passed to the actual tools themselves. As the most common "configuration" changes are expected to be made to the configuration files passed to the tools themselves (i.e. the set of Checkstyle rules to apply, the set of SpotBugs plugins used, or the set of PMD rulesets used.) special parameters of the below form can be used.

sanity4j.tool.tool.version.config

This can be placed at any point within the command line, and these parameters can then be set from within the Sanity4J invocation shells (ant, maven, eclipse and the GUI.) via more convenient means.

Variable substitution is available for tool locations and command lines. For example, ${java} will be replaced by the path to the JRE executable. The Variables available are detailed in the table below.

Here is an example of configuring Checkstyle 4.4 to only use the Sun Code Conventions:

sanity4j.tool.checkstyle.4.4.config=${toolHome}${File.separatorChar}sun_checks.xml
sanity4j.tool.checkstyle.4.4.command="${java}" ${javaArgs} com.puppycrawl.tools.checkstyle.Main -c "${sanity4j.tool.checkstyle.4.4.config}" -f xml -o "${outputFile}" -r ${source} 

sanity4j.tool.checkstyle.4.4.config=sun_checks.xml
sanity4j.tool.checkstyle.4.4.command="${java}" ${javaArgs} com.puppycrawl.tools.checkstyle.Main -c "${sanity4j.tool.checkstyle.4.4.config}" -f xml -o "${outputFile}" -r ${source} 

sanity4j.tool.checkstyle.4.4.config=custom_checks.xml
sanity4j.tool.checkstyle.4.4.classpath=../custom/custom-plugins.jar

sanity4j.tool.pmd.4.2.5.config         =custom_pmd_rules.xml
sanity4j.tool.pmd.4.2.5.classpath      =../custom/custom-plugins-1.0.2.jar

sanity4j.tool.spotbugs.3.1.6.config    =-pluginList custom-plugins.jar -exclude sanity4j_filter_exclude.xml
sanity4j.tool.spotbugs.3.1.6.classpath =../custom/custom-plugins-1.0.2.jar

sanity4j.tool.checkstyle.4.4.config    =custom_checks.xml
sanity4j.tool.checkstyle.4.4.classpath =../custom/custom-plugins-1.0.2.jar

Customising issue categories and severities.

Issue weightings and exclusions can be adjusted in settings files for each individual tool (where supported) or centrally in the external Sanity4J property file. The names for each parameter are of the form <source>.<ruleName>.<option> .

The "source" corresponds to the tool which generates the issue. Possible values are "SpotBugs", "PMD" and "Checkstyle".

The "ruleName" is the tool-specific name of the rule which generates the issue (e.g. NP_LOAD_OF_KNOWN_NULL_VALUE).

The "option" must be one of the following:

• The "category" option is used to set category paths. A category path is a text string, with path elements delimited by '/'. Multiple paths may be supplied, delimited by commas. For example, the value "Style,Maintenance/Code Size" would place issues under the categories "Style" and "Maintenance" --> "Code Size"
• The "severity" option is used to set the issue severity. The parameter's value must be 0-4 (0=info, 1=low, 2=moderate, 3=significant, 4=high).
• The "includes" option controls which Java class names should have the rule applied to them. All files are included by default. The parameter value should be a comma-delimited list of class names to include, using java regular expressions.
• The "excludes" option controls which Java class names should be excluded from this rule. A class is excluded if it is matched by at least one exclude. The default exclude is nothing. The parameter's value should be a comma-delimited list of class names to exclude.

The following example shows parameters to exclude jUnit 3.x tests from CheckStyle's magic-number check, and set the severity for this issue in other classes to low.

Checkstyle.MagicNumberCheck.severity=1
Checkstyle.MagicNumberCheck.excludes=Test[A-Z].*,.*Test

Customising report output.

The weighting for the quality metric can be modified if necessary. The default weighting is shown below.

sanity4j.report.metric.quality.expression=1.0 - ((#highCount * 100.0 + #significantCount * 20.0 +
#moderateCount * 5.0 + #lowCount * 2.0 + #infoCount * 0.0) / #linesOfCode)

Customising the static content used by tools in the report.

Custom rules can be written for each of the tools used by Sanity4J. When a custom rule is written, it usually is accompanied by a page in the report specific for that custom rule.

Sanity4J uses the properties file "ExtractStaticContent.properties" to incorporate the page in the report.

This properties file can be placed in the working directory, or on the classpath. Therefore, if you write your own custom rule, and package the compiled class in a plugin jar for the tool, then you could additionally place the "ExtractStaticContent.properties" into that same jar as your custom rule.

The format of the file consists of a mapping of the name of the resource to be extracted, to a location of the file for the report.

SQL_TIMESTAMP_COMPARISON.html=rules/spotbugs/SQL_TIMESTAMP_COMPARISON.html

The above is an example for a custom "spotbugs" rule used to check that java.util.Date objects are not being used in comparison operations with java.sql.Timestamp objects.

The above named html file would be a page that describes incorrect and correct code, and is linked to by the report.

As the html file would be placed in the same jar as your plugin class, it needs to be extracted to a location where the report can reference it, thus the mapping in the properties file.