1 The JFindBugs plugin

1.0.1 Description

FindBugs is an open source program which looks for bugs in Java code . It uses static analysis to identify hundreds of different potential types of error in Java programs. FindBugs operates on Java bytecode , rather than source code.

1.0.2 Vendor

FindBugs™ is free software, distributed under the terms of the Lesser GNU Public License. The name FindBugs™ and the FindBugs logo are trademarked by The University of Maryland.

The following companies, organizations and institutions provide financial support for FindBugs: SureLogic, Google, National Science Foundation, University of Maryland.

1.0.3 Version

JFindBugsPlugin 2.0.0-1

Findbugs 1.3.7

FB-contrib 3.8.0

1.0.4 Homepage

http://findbugs.sourceforge.net

1.0.5 Documentation

http://findbugs.sourceforge.net/manual/index.html

1.1 Activation

1.1.1 Suitability

Suitable for any module with available compiled Java source code (class files) or binaries (JAR files).

External libraries needed to run the code must also be available.

1.1.2 Execution point

The execution point defines during which command and which target the plugin will be executed.

COMMAND	build
TARGET	pretest

1.1.3 Profiles

The profiles must be specified in the configuration in order to activate the plugin.

The plugin profile can be used to enable specific plugins.

The bundle profiles can be used to enable a set of plugins within a specific category.

PLUGIN PROFILES	findbugs
BUNDLE PROFILES	java

1.2 Deactivation

If this plugin has been activated for a larger set of modules (at project or subsystem level), it is possible to disable it for specific modules using special properties:

NAME	nofindbugs
DESCRIPTION	To disable the FindBugs execution for the current module

NAME	notest
DESCRIPTION	To disable all the plugins registered at TEST target (PRETEST, TEST, POSTTEST) for the current module

1.3 Input

1.3.1 Required properties

The required properties must be available in order for the plugin to run.

Some of the requires properties may have default values which correctness must be check to ensure the correct execution of the plugin.

NAME	findbugs.class.location (java.class.location)
DESCRIPTION	Root of the directory structure where the compiled Java files (.class) are placed according to their package definition. java.class.location can be used instead of findbugs.class.location to have a generic property that works with all the java plugins. The available class files will be analyzed together with the JAR files available in findbugs.jar.location
DEFAULT VALUE	${src.location}/classes or if not existing ${src.location}/build/classes
EXAMPLE	Assuming the compilation output directory is ${location}/build/bin having files like ${src.location}/build/bin/org/my/package/MyClass.class, the property must be set as: ${src.location}/build/bin

NAME	findbugs.jar.location (java.jar.location)
DESCRIPTION	Directory containing the JAR files to be analized. java.jar.location can be used instead of findbugs.jar.location to have a generic property that works with all the java plugins. The available JAR files will be analyzed together with the class files available in findbugs.class.location
DEFAULT VALUE	${src.location}/jars or if not existing ${src.location}/build/jars
EXAMPLE	Assuming the ANT script generates a JAR file in ${src.location}/build/jar/MyJarFile.jar, the property must be set as: ${src.location}/build/jar

NAME	findbugs.lib.location (java.lib.location)
DESCRIPTION	Directory containing the external libraries (JAR files) required to execute the analized code. java.lib.location can be used instead of findbugs.lib.location to have a generic property that works with all the java plugins. These JAR files will NOT be analized by FindBugs.
DEFAULT VALUE	${src.location}/lib or if not existing ${src.location}/endorsed or again ${stageDir}/share/java
EXAMPLE	Assuming all the external libraries are stored in ${src.location}/libs/MyExternalDependency.jar, the property must be set as: ${src.location}/libs

NAME	findbugs.failure.threshold
DESCRIPTION	Defines whether a module must fail in case one or more bugs are found at the specified priority level: none = No module build failures due to FindBugs; high = The module build is marked as failed if one or more High priority bugs are found; medium = The module build is marked as failed if one or more High or Medium priority bugs are found; low = The module build is marked as failed if one or more bugs are found at any priority
DEFAULT VALUE	none
EXAMPLE	To force module builds to fail in case one or more High priority bugs are found, the property must be set as: high

1.3.2 Optional properties

NAME	findbugs.src.location
DESCRIPTION	Root of the directory structure containing the Java source files. If available, the Java source files are only used in the generation of reports to show the potential bugs. java.src.location can be used instead of findbugs.src.location to have a generic property that works with all the java plugins.
DEFAULT VALUE	${src.location}/src
EXAMPLE	Assuming the compilation input directory is ${src.location}/sources having files like ${src.location}/sources/org/my/package/MyClass.java, the property must be set as: ${src.location}/sources

NAME	findbugs.bug.codes
DESCRIPTION	Comma separated list of bug codes to be used in the analysis (see http://findbugs.sourceforge.net/bugDescriptions.html). The plugin will generate a FindBugsFilter file with a single Match of the specified bug code. If the property is not set or is set as an empty string, all bugs will be used for the analysis. In case findbugs.filter.location is set and valid, this property will be ignored because the used filter file will be the one specified by findbugs.filter.location
DEFAULT VALUE
EXAMPLE	To use only MS and NP bug codes, the property must be set as: MS, NP

NAME	findbugs.filter.location
DESCRIPTION	Path to a valid FindBugs filter file (see http://findbugs.sourceforge.net/manual/filter.html). In case the filter file is found, the property findbugs.bug.codes will be ignored
DEFAULT VALUE
EXAMPLE	Assuming a valid FindBugs filter file is available inside the VCS (i.e. CVS, SVN, etc) module at the following location /project/FindBugs/filter/MyFilter.xml, the property must be set as: ${src.location}/project/FindBugs/filter/MyFilter.xml

NAME	findbugs.report.level
DESCRIPTION	Priority threshold for reporting bugs: low - all bugs are reported. medium - medium and high priority bugs are reported. high - only high priority bugs are reported
DEFAULT VALUE	low
EXAMPLE	To see only high bugs in the report, the property must be set as: high

NAME	findbugs.jvmargs
DESCRIPTION	Arguments to be passed to the Java virtual machine used to run FindBugs
DEFAULT VALUE	-Xmx512M
EXAMPLE	To allocate 1 Gb or memory, the property must be set as: -Xmx1024M

NAME	findbugs.timeout
DESCRIPTION	Amount of time, in milliseconds, that FindBugs may run before assuming it to be hung and terminate the process. In case of very large programs, the default timeout may not be enough.
DEFAULT VALUE	600000 milliseconds (10 minutes)
EXAMPLE	To set the timeout to 20 minutes, the property must be set as: 1200000

1.3.3 Other requirements

NONE

1.3.4 Dependencies

NONE

1.4 Output

1.4.1 Module reports

For each module, the output is generated in ${src.location}/reports/findbugs

The plugins generate a FireBugs XML file: findbugs-${moduleName}.xml and it uses the default and summary FindBugs XSL style sheets to generate findbugs-${moduleName}.html and findbugs-${moduleName}-bugs.html

To check the XML schema and style sheet, please refer to the FindBugs orginal documentation.

1.4.2 Global reports

The final summary is generated in ${workspaceDir}/reports/findbugs/index.html

Each generated FindBugs HTML summary and bugs files are also available in the global reports directory under ${workspaceDir}/reports/findbugs/${moduleName}-${name}/index.html and ${workspaceDir}/reports/findbugs/${moduleName}-${name}/index-bugs.html

1.5 Metrics

1.5.1 Overall

The overall metrics are related to the whole build/test and provide a summary of the modules executed.

NAME	Findbugs
VALUE	Number of bugs found during the build/test
UNIT	Bugs
TYPE	Integer
CONTEXT	${findbugs.bug.codes}
LINKS	HTML: ${workspaceDir}/reports/findbugs/index.html
VALUES	The three priority categories are provided: high, medium, low

NAME	Findbugs rate
VALUE	Percentage of modules that have successfully passed the threshold defined by ${findbugs.failure.threshold}
UNIT	Modules
TYPE	percentage
CONTEXT	${findbugs.bug.codes}
LINKS	HTML: ${workspaceDir}/reports/findbugs/index.html
VALUES	success: number of successful modules, failed: number of failed modules

1.5.2 Module

The module metrics are related to a single module and provide its plugin execution details.

NAME	Findbugs
VALUE	Number of bugs found during the build/test
UNIT	Bugs
TYPE	Integer
CONTEXT	${findbugs.bug.codes}
LINKS	HTML: ${workspaceDir}/reports/findbugs/index.html ; XML: ${workspaceDir}/reports/findbugs/${moduleName}-${name}/findbugs-${moduleName}.xml
VALUES	The three priority categories are provided: high, medium, low

1.6 Advanced

1.6.1 Register

Verifies dependencies and the existence of the ANT build file.

Sets the CLASSPATH for the Findbugs tool

Registers the plugin

1.6.2 Execute

Verifies the values of user defined properties The main functionality is executed using build-findbugs.xml running 'findbugs' target.

1.6.3 Publish

Detailed HTML reports are generated and module metrics are added to build-status.xml.

Link to the generated HTML report is added to the build-status.xml

1.6.4 Finalise

Detailed HTML summary reports is generated and overall metrics are added to build-status.xml. Link to the generated HTML report is added to the build-status.xml

-- FabioCapannini - 14-Sep-2011