Anda di halaman 1dari 4

Adding Detectors to FindBugs

May 12, 2003


Updated June 6, 2003 (detector meta-information, cleanups)
===============
1. Introduction
===============
FindBugs uses a plugin-based approach to adding detectors.
This makes it easy for users to add their own detectors alongside
the ones that come built in.
Basic idea: FindBugs has some Jar files in a "plugins" directory.
At startup, each of those jar files is checked for a "findbugs.xml"
file. That XML file registers instances of Detectors, as well
as particular "bug patterns" that the detector reports.
At startup, FindBugs loads all plugin Jar files. At analysis time,
all detectors named in the findbugs.xml files from those plugins
are instantiated and applied to analyzed class files.
In order to format reported BugInstances as text for display,
a messages file is loaded from the plugin. In order to support multiple
language translations, a locale search is performed in a manner
similar to the handling of resource bundles. For example, if the
locale is "pt_BR", then the files
messages_pt_BR.xml
messages_pt.xml
messages.xml
are tried, in that order.
The "findbugs.xml" and "messages.xml" files used by the standard FindBugs
bug pattern detectors (coreplugin.jar) can be found in the "etc" directory
of the findbugs source distribution.

============================
2. Example findbugs.xml file
============================
<DetectorPlugin>
<Detector class="org.foobar.findbugs.FindUnreleasedLocks" speed="slow" />
<Detector class="org.foobar.findbugs.ExperimentalDetector" speed="fast" disabl
ed="true" />
<!-- More Detector elements would go here... -->
<BugPattern type="UBL_UNRELEASED_LOCK" abbrev="UL" category="MT_CORRECTNESS" /
>
<!-- More BugPattern elements would go here... -->
</DetectorPlugin>

======================================
3. Meaning of elements in findbugs.xml
======================================
<DetectorPlugin> a collection of <Detector> and <BugPattern> elements.
Each plugin Jar file can (and usually will) provide multiple detectors
and define multiple bug patterns.
<Detector> specifies a class which implements the edu.umd.cs.findbugs.Detector
interface and has a constructor that takes a single parameter of type
edu.umd.cs.findbugs.BugReporter. This element has three possible attributes:
1. The required "class" attribute specifies the Detector class.
2. The optional "disabled" attribute, if set to "true", means
that by default, the detector will be disabled at runtime.
This is useful for detectors that aren't quite ready for prime time.
3. The required "speed" attribute supplies a value to be shown in the
"Settings->Configure Detectors" dialog. It gives the user an idea of
how expensive the analysis will be to perform. The value of this
attribute should be one of "fast", "moderate", or "slow".
<BugPattern> specifies a kind of bug that will be reported.
It has three required attributes:
1. "type" is a unique code identifying the bug. Only one BugPattern
can have a a particular type.
2. "abbrev" is a short alphanumeric code for the bug.
Note that multiple BugPatterns can use the same abbreviation
if they are related. (See the BugCode element in messages.xml).
3. "category" can be one of categories defined in the core plugin's messages
.xml:
CORRECTNESS - code that was probably not what the developer intended
BAD_PRACTICE - violations of recommended and essential coding practice
STYLE - code that is confusing, anomalous, or written in a way that that
leads itself to errors
MT_CORRECTNESS - multithreaded correctness issues
MALICIOUS_CODE - a potential vulnerability if exposed to malicious code
PERFORMANCE - a performance issue
I18N - internationalization and locale
or you may create your own category, in which case you should define
it in a <BugCategory> element in _your_ messages.xml file.
============================
4. Example messages.xml file
============================
<MessageCollection>
<Detector class="org.foobar.findbugs.FindUnreleasedLocks" >
<Details>
<![CDATA[
<p> This detector looks for JSR-166 locks that are not released on all p
aths
out of a method. Because it performs dataflow analysis, it is fairly sl
ow.
]]>
</Details>
</Detector>
<!-- More Detector nodes would go here... -->
<BugPattern type="UBL_UNRELEASED_LOCK">
<ShortDescription>Lock not released on all paths out of method</ShortDescrip
tion>
<LongDescription>{1} does not release lock on all paths out of method</LongD
escription>
<Details>
<![CDATA[
<p> A JSR-166 lock acquired in this method is not released on all paths
out of the method. This could result in a deadlock if another thread
tries to acquire the lock. Generally, you should use a finally
block to ensure that acquired locks are always released.
]]>
</Details>
</BugPattern>
<!-- More BugPattern nodes would go here... -->
<BugCode abbrev="UL">Unreleased locks</BugCode>
<!-- More BugCode nodes would go here... -->
</MessageCollection>

======================================
5. Meaning of elements in messages.xml
======================================
<MessageCollection> is the top level element
<BugCategory> elements optionally describe any categories you
may have created for your bug patterns. You can skip these if
you are using only the categories defined by the core plugin.
The <Description> child element has a brief (a word or three)
description of the category. The <Abbreviation> child element
is typically a single capital latter. The optional <Details>
child element may describe it in more detail (but no markup).
<Detector> holds meta-information about a Detector in the plugin.
The required "class" attribute specifies the Detector class.
Detector elements much have the following child elements:
The <Details> child element has a brief HTML description of the Detector.
It should have HTML markup that would be valid in a BODY element.
It should be specified in a CDATA section so that the HTML
tags are not misinterpreted as XML.
<BugPattern> holds all of the human-readable messages for the bug pattern
identified by the "type" attribute. The type corresponds to the
type attribute of the BugPattern elements described in findbugs.xml.
BugPattern elements must have the following child elements:
<ShortDescription> this is used for when "View->Full Descriptions"
is turned off in the GUI, and it's also used as the title for
descriptions in the Details window.
<LongDescription> this is used for when "View->Full Descriptions"
is turned on in the GUI, and for output using the command line UI.
The placeholders in the long description ({0}, {1}, etc.)
refer to BugAnnotations attached to the BugInstances reported by
the detector for this bug pattern. You may also use constructs
like {1.name} or {1.returnType}.
<Details> this is the descriptive text to be used in the Details
window. It consists of HTML markup to appear in the BODY element of an HTML
document. It should be specified in a CDATA section so that the HTML
tags are not misinterpreted as XML.
<BugCode> is the text which describes the common characteristic of all
of the BugPatterns which share an abbreviation. In the example above,
the abbreviation "UL" is for bugs in which a lock is not released.
The text of a BugCode element is shown for tree nodes in the GUI
which group bug instances by "bug type".