834 lines
36 KiB
HTML
834 lines
36 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<title>Checkstyle Configuration</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css"/>
|
|
</head>
|
|
|
|
<body>
|
|
<!-- The header -->
|
|
<table border="0" width="100%" summary="header layout">
|
|
<tr>
|
|
<td><h1>Checkstyle Configuration</h1></td>
|
|
<td align="right"><img src="logo.png" alt="Checkstyle Logo"/></td>
|
|
</tr>
|
|
</table>
|
|
<!-- content -->
|
|
<table border="0" width="100%" cellpadding="5" summary="body layout">
|
|
<tr>
|
|
<!--Left menu-->
|
|
<td class="menu" valign="top">
|
|
<ul>
|
|
<li>
|
|
<a href="#overview">Overview</a>
|
|
</li>
|
|
<li>
|
|
<a href="#modules">Modules</a>
|
|
</li>
|
|
<li>
|
|
<a href="#properties">Properties</a>
|
|
</li>
|
|
<li>
|
|
<a href="#checker">Checker</a>
|
|
</li>
|
|
<li>
|
|
<a href="#treewalker">TreeWalker</a>
|
|
</li>
|
|
<li>
|
|
<a href="#treewalkerchecks">TreeWalker Checks</a>
|
|
</li>
|
|
<li>
|
|
<a href="#severity">Severity</a>
|
|
</li>
|
|
<li>
|
|
<a href="#filters">Filters</a>
|
|
</li>
|
|
<li>
|
|
<a href="#auditlisteners">AuditListeners</a>
|
|
</li>
|
|
<li>
|
|
<a href="#packagenames">Packages</a>
|
|
</li>
|
|
<li>
|
|
<a href="#xml">XML Details</a>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<!--Content-->
|
|
<td class="content" valign="top" align="left">
|
|
|
|
<a name="overview"></a> <h2>Overview</h2>
|
|
<p class="body">
|
|
A Checkstyle configuration specifies which <em>modules</em> to plug in and apply to Java
|
|
source files. Modules are structured in a tree whose root is the <em>Checker</em>
|
|
module. The next level of modules contains
|
|
</p>
|
|
<ul class="body">
|
|
<li><em>FileSetChecks</em>- modules that take a set of input files and fire error messages.</li>
|
|
<li><em>Filters</em>- modules that filter audit events, including error messages, for acceptance.</li>
|
|
<li><em>AuditListeners</em>- modules that report accepted events.</li>
|
|
</ul>
|
|
<p class="body">
|
|
Many checks are submodules of
|
|
the <em>TreeWalker</em> FileSetCheck module. The TreeWalker operates by
|
|
separately transforming each of the Java source files into an abstract syntax
|
|
tree and then handing the result over to each of its submodules which in turn
|
|
have a look at certain aspects of the tree.
|
|
</p>
|
|
<p class="body">
|
|
Checkstyle obtains a configuration from an XML document whose elements specify
|
|
the configuration's hierarchy of modules and their properties. You provide
|
|
a file that contains the configuration document when you invoke Checkstyle at
|
|
the <a href="cmdline.html">command line</a>, and when you run a <a href="anttask.html">Checkstyle
|
|
task</a> in ant. The documentation directory of the Checkstyle distribution contains
|
|
a sample configuration file <em>sun_checks.xml</em> which configures Checkstyle
|
|
to check for the Sun coding conventions.
|
|
</p>
|
|
<a name="modules"></a> <h2>Modules</h2>
|
|
<p class="body">
|
|
A <span class="code">module</span> element in the configuration XML document
|
|
specifies a module identified by the element's <span class="code">name</span>
|
|
attribute.
|
|
</p>
|
|
<p class="body">
|
|
Here is a fragment of a typical configuration document:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<module name="PackageHtml"/>
|
|
<module name="TreeWalker">
|
|
<module name="AvoidStarImport"/>
|
|
<module name="ConstantName"/>
|
|
<module name="EmptyBlock"/>
|
|
</module>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
In this configuration:
|
|
</p>
|
|
<ul class="body">
|
|
<li>
|
|
Root module <span class="code">Checker</span> has child FileSetChecks <span class="code">
|
|
PackageHtml</span> and <span class="code">TreeWalker</span>. (Module <a href="config_javadoc.html">
|
|
<span class="code">PackageHtml</span></a> checks that all packages have package
|
|
documentation.)
|
|
</li>
|
|
<li>
|
|
Module <span class="code">TreeWalker</span> has submodules
|
|
<span class="code">AvoidStarImport</span>,
|
|
<span class="code">ConstantName</span>, and
|
|
<span class="code">EmptyBlock</span>.
|
|
(Modules
|
|
<a href="config_import.html"><span class="code">AvoidStarImport</span></a>,
|
|
<a href="config_naming.html"><span class="code">ConstantName</span></a>, and
|
|
<a href="config_blocks.html"><span class="code">EmptyBlock</span></a>
|
|
check that a Java source file has no star imports, has
|
|
valid constant names, and has no empty blocks, respectively.)
|
|
</li>
|
|
</ul>
|
|
<p class ="body">
|
|
For each configuration module, Checkstyle loads a class identified by the
|
|
<span class="code">name</span> attribute of the <span class="code">module</span>.
|
|
There are several rules for loading a module's class:
|
|
</p>
|
|
<ol class="body">
|
|
<li>
|
|
Load a class directly according to a package-qualified <span class="code">name</span>,
|
|
such as loading class <span class="code">com.puppycrawl.tools.checkstyle.TreeWalker</span>
|
|
for element
|
|
<pre class="body">
|
|
<module name="com.puppycrawl.tools.checkstyle.TreeWalker">
|
|
</pre>
|
|
This is useful for plugging third-party modules into a configuration.
|
|
</li>
|
|
<li>
|
|
Load a class of a pre-specified package, such as loading class
|
|
<span class="code">com.puppycrawl.tools.checkstyle.checks.AvoidStarImport</span>
|
|
for element
|
|
<pre class="body">
|
|
<module name="AvoidStarImport"/>
|
|
</pre>
|
|
Checkstyle applies packages <span class="code">
|
|
com.puppycrawl.tools.checkstyle</span>, <span class="code">
|
|
com.puppycrawl.tools.checkstyle.filters</span>, and <span class="code">
|
|
com.puppycrawl.tools.checkstyle.checks</span> and its sub-packages (only
|
|
those included in the Checkstyle distribution). You can specify other
|
|
packages in a <a href="#packagenames"><em>package names XML document</em></a>
|
|
when you invoke Checkstyle at the <a href="cmdline.html">command line</a>,
|
|
and when you run a <a href="anttask.html">Checkstyle task</a> in ant.
|
|
</li>
|
|
<li>
|
|
Apply the above rules to <span class="code">name</span>
|
|
concatenated with <span class="code">"Check"</span>,
|
|
such as loading class
|
|
<span class="code">com.puppycrawl.tools.checkstyle.checks.ConstantNameCheck</span> for element
|
|
<pre class="body">
|
|
<module name="ConstantName"/>
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
<a name="properties"></a> <h2>Properties</h2>
|
|
<p class="body">
|
|
Properties of a module control how the module performs its task.
|
|
Each module property has a default value, and you are not required to define a property in the
|
|
configuration document if the default value is satisfactory.
|
|
To assign a non-default value to a module's property,
|
|
define a child <span class="code">property</span> element of the <span class="code">module</span>
|
|
element in the configuration XML document. Also provide appropriate
|
|
<span class="code">name</span> and
|
|
<span class="code">value</span> attributes for the <span class="code">property</span> element.
|
|
For example, property
|
|
<span class="code">max</span> of module <span class="code">MethodLength</span>
|
|
specifies the maximum allowable number of lines in a method or constructor, and has default
|
|
value <span class="code">150</span>.
|
|
Here is a configuration of module <span class="code">MethodLength</span> so that the check reports
|
|
methods and constructors with more than <span class="code">60</span> lines:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLength">
|
|
<property name="max" value="60"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
</p>
|
|
<p class="body">
|
|
<a href="cmdline.html">Command line</a> properties
|
|
and ant <a href="anttask.html">Checkstyle task</a> properties apply
|
|
to the root <span class="code">Checker</span>
|
|
module. Also, properties are inherited in the
|
|
module hierarchy. These features make it easy to define one property value that applies to
|
|
many modules. For example, the following configuration fragment specifies that a
|
|
<span class="code">tabWidth</span> of <span class="code">4</span> applies to
|
|
<span class="code">TreeWalker</span> and its submodules:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<module name="PackageHtml"/>
|
|
<module name="TreeWalker">
|
|
<property name="tabWidth" value="4"/>
|
|
<module name="AvoidStarImport"/>
|
|
<module name="ConstantName"/>
|
|
...
|
|
</module>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
The value of a module property can be specified through <em>property expansion</em> with the
|
|
<span class="code">${<em>property_name</em>}</span> notation,
|
|
where <span class="code"><em>property_name</em></span> is a <a href="cmdline.html">command line</a>
|
|
property or an ant <a href="anttask.html">Checkstyle task</a> property.
|
|
For example, the following configuration document element gives property
|
|
<span class="code">headerFile</span> the value
|
|
of command line property <span class="code">checkstyle.header.file</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<property name="headerFile" value="${checkstyle.header.file}"/>
|
|
</pre>
|
|
<p class="body">
|
|
You can use property expansion to re-specify a module property value
|
|
without changing the configuration document.
|
|
</p>
|
|
<p class="body">
|
|
The property element provides an optional <span class="code">default</span> attribute which is used
|
|
when a property in the value cannot be resolved. For example this configuration
|
|
snippet from a central configuration file checks that methods have javadoc, but
|
|
allows inividual projects to override the severity by specifying
|
|
their desired value in the command line property
|
|
<span class="code">checkstyle.javadoc.severity</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavaDocMethod">
|
|
<property name="severity" value="${checkstyle.javadoc.severity}" default="error"/>
|
|
</module/>
|
|
</pre>
|
|
<p class="body">
|
|
This feature is a great help when setting up a centralized configuration file
|
|
(e.g. one file for the whole company) to lower configuration maintenance costs.
|
|
Projects that are happy with the default can simply use that configuration file as is,
|
|
but individual projects with special needs have the fexibility to adjust a few
|
|
settings to fit their needs without having to copy and maintain the whole configuration.
|
|
</p>
|
|
<a name="checker"></a> <h2>Checker</h2>
|
|
<p class="body">
|
|
All configurations have root module <span class="code">Checker</span>.
|
|
<span class="code">Checker</span> contains
|
|
</p>
|
|
<ul class="body">
|
|
<li><em>FileSetCheck</em> children: modules that check sets of files.</li>
|
|
<li><em>Filter</em> children: modules that filter audit events.</li>
|
|
<li><em>AuditListener</em> children: modules that report filtered events.</li>
|
|
</ul>
|
|
<span class="code">Checker</span> also defines properties that are
|
|
inherited by all other modules of a configuration.
|
|
</p>
|
|
<h4 class="body">Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>basedir</td>
|
|
<td>base directory name; stripped off in messages about files</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><span class="default">null</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>localeCountry</td>
|
|
<td>locale country for messages</td>
|
|
<td><a href="property_types.html#string">string</a>: either the empty string or an uppercase ISO 3166 2-letter code</td>
|
|
<td>default locale country for the Java Virtual Machine</td>
|
|
</tr>
|
|
<tr>
|
|
<td>localeLanguage</td>
|
|
<td>locale language for messages</td>
|
|
<td><a href="property_types.html#string">string</a>: either the empty string or a lowercase ISO 639 code</td>
|
|
<td>default locale language for the Java Virtual Machine</td>
|
|
</tr>
|
|
</table>
|
|
<p class="body">
|
|
For example, the following configuration fragment specifies base directory
|
|
<span class="code">src/checkstyle</span> and German locale for all modules:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<property name="basedir" value="src/checkstyle"/>
|
|
<property name="localeCountry" value="DE"/>
|
|
<property name="localeLanguage" value="de"/>
|
|
<module name="PackageHtml"/>
|
|
<module name="TreeWalker">
|
|
...
|
|
</module>
|
|
</module>
|
|
</pre>
|
|
<a name="treewalker"></a> <h2>TreeWalker</h2>
|
|
<p class="body">
|
|
FileSetCheck <span class="code">TreeWalker</span> checks individual Java source files
|
|
and defines properties that are applicable to checking such files.
|
|
</p>
|
|
<h4 class="body">Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>cacheFile</td>
|
|
<td>caches information about files that have checked ok; used to avoid
|
|
repeated checks of the same files</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><span class="default">null</span> (no cache file)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tabWidth</td>
|
|
<td>number of expanded spaces for a tab character (<span class="code">'\t'</span>);
|
|
used in messages and Checks that require a tab width, such as
|
|
<a href="config_sizes.html#LineLength"><span class="code">LineLength</span></a></td>
|
|
<td><a href="property_types.html#integer">integer</a></td>
|
|
<td><span class="default">8</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>fileExtensions</td>
|
|
<td>file type extension to identify java files. Setting this property is
|
|
typically only required if your java source code is preprocessed before
|
|
compilation and the original files do not have the extension
|
|
<span class="code">.java</span></td>
|
|
<td><a href="property_types.html#stringSet">String Set</a></td>
|
|
<td><span class="default">java</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p class="body">
|
|
For example, the following configuration fragment specifies <span class="code">TreeWalker</span>
|
|
cache file <span class="code">target/cachefile</span>, and a <span class="code">tabWidth</span>
|
|
of <span class="code">4</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<module name="TreeWalker">
|
|
<property name="cacheFile" value="target/cachefile"/>
|
|
<property name="tabWidth" value="4"/>
|
|
...
|
|
</module>
|
|
</module>
|
|
</pre>
|
|
|
|
<p class="body">
|
|
<!--
|
|
thanks to Paul King for this example, see
|
|
https://sourceforge.net/tracker/?func=detail&aid=865610&group_id=29721&atid=397078
|
|
-->
|
|
To integrate Checkstyle with BEA Weblogic Workshop 8.1:
|
|
</p>
|
|
|
|
<pre class="body">
|
|
<module name="Checker">
|
|
<module name="TreeWalker">
|
|
<property name="fileExtensions" value="java,ejb,jpf"/>
|
|
...
|
|
</pre>
|
|
|
|
<a name="treewalkerchecks"></a> <h2>TreeWalker Checks</h2>
|
|
<p class="body">
|
|
The <span class="code">TreeWalker</span> module creates a syntax tree for a Java source file
|
|
and invokes its submodules, called <em>Checks</em>, during a walk, or traversal, of the nodes
|
|
of the tree.
|
|
Every node of the syntax tree has a token. A visit to a node during the traversal
|
|
triggers all Checks that are configured for its token.
|
|
For example, if Check <span class="code">MethodLength</span> has been configured as
|
|
a submodule of <span class="code">TreeWalker</span>, then a visit to a node
|
|
with a method or a constructor definition
|
|
token triggers <span class="code">MethodLength</span> to check the number of lines
|
|
of the node's code block.
|
|
</p>
|
|
<p class="body">
|
|
Some Checks, such as <span class="code">FileLength</span>
|
|
and <span class="code">LineLength</span>, apply directly to the source file and do not involve tokens
|
|
of the syntax tree.
|
|
Other Checks are associated with configurable sets of tokens that
|
|
trigger the Checks.
|
|
For example, this element configures Check <span class="code">MethodLength</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLength"/>
|
|
</pre>
|
|
<p class="body">
|
|
The default token set for <span class="code">MethodLength</span> is
|
|
<span class="code">{METHOD_DEF, CTOR_DEF}</span>, method definition and constructor definition
|
|
tokens, so <span class="code">TreeWalker</span> invokes
|
|
<span class="code">MethodLength</span> whenever it visits a node with a
|
|
<span class="code">METHOD_DEF</span> or a <span class="code">CTOR_DEF</span> token.
|
|
</p>
|
|
<p class="body">
|
|
You specify the trigger tokens for a Check with property <span class="code">tokens</span>.
|
|
The value of <span class="code">tokens</span> is a list that denotes a subset of the Check's
|
|
tokens, as in the following element that configures Check
|
|
<span class="code">MethodLength</span> to check the number of lines of methods only:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLength">
|
|
<property name="tokens" value="METHOD_DEF"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To apply particular properties to different subsets of tokens for a Check, repeat the Check.
|
|
For example, to check that the length of each method is at most 150 lines (the default value
|
|
of <span class="code">MethodLength</span> property <span class="code">max</span>) and the
|
|
length of each constructor is at most 60 lines, include the following in the
|
|
<span class="code">TreeWalker</span> configuration:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLength">
|
|
<property name="tokens" value="METHOD_DEF"/>
|
|
</module>
|
|
|
|
<module name="MethodLength">
|
|
<property name="tokens" value="CTOR_DEF"/>
|
|
<property name="max" value="60"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
Configurations of the Checks are specified in the following pages:
|
|
</p>
|
|
|
|
<ul class="body">
|
|
<li>
|
|
<a href="config_javadoc.html">Checks For Javadoc Comments</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_naming.html">Checks For Naming Conventions</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_header.html">Checks For Headers</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_import.html">Checks For Imports</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_sizes.html">Checks For Size Violations</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_whitespace.html">Checks For Whitespace</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_modifiers.html">Checks For Modifiers</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_blocks.html">Checks For Blocks</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_coding.html">Checks For Coding Problems</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_design.html">Checks For Design Problems</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_duplicates.html">Checks For Finding Duplicate Code</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_metrics.html">Checks For Metrics</a>
|
|
</li>
|
|
<li>
|
|
<a href="config_misc.html">Miscellaneous Checks</a>
|
|
</li>
|
|
<li>
|
|
<a href="optional.html">Optional Checks</a>
|
|
</li>
|
|
</ul>
|
|
<a name="severity"></a>
|
|
<h2>Severity</h2>
|
|
<p class="body">
|
|
Each check has a <a href="property_types.html#severity">severity</a> property
|
|
that a Checkstyle audit assigns to all violations of the check. The default severity level of
|
|
a check is <span class="default">error</span>.
|
|
</p>
|
|
<p class="body">
|
|
You can use the severity property to control the output of the plain formatter for the <a href="cmdline.html">command
|
|
line tool</a> and the <a href="anttask.html">ANT task</a>. The plain formatter does not report violations with severity level
|
|
<span class="default">ignore</span>, and notes violations with severity level
|
|
<span class="default">warning</span>. For example, according to the following configuration fragment,
|
|
the plain formatter outputs warnings for translation violations:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="Translation">
|
|
<property name="severity" value="warning"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
The XML formatter reports the severity level
|
|
of every violation as an attribute of the violation's <span class="default">error</span>
|
|
element.
|
|
</p>
|
|
|
|
<a name="filters"></a>
|
|
<h2>Filters</h2>
|
|
<p class="body">
|
|
A Checker module has a set of Filter submodules to filter audit events, including the error messages fired by Checks.
|
|
A Filter can accept or reject an audit event. If all Filters accept
|
|
an audit event, then the Checker reports the event.
|
|
If any Filter rejects an event, then the Checker does not report the event.</p>
|
|
<p class="body">
|
|
Filter <span class="code">SeverityMatchFilter</span> decides audit events according to the
|
|
<a href="#severity">severity level</a> of the event.
|
|
</p>
|
|
<h4 class="body">SeverityMatchFilter Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>severity</td>
|
|
<td>the severity level of this filter</td>
|
|
<td><a href="property_types.html#severity">severity</a></td>
|
|
<td><span class="default">error</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>acceptOnMatch</td>
|
|
<td>If acceptOnMatch is <span class="code">true</span>, then the filter accepts an audit event if and only if there is
|
|
a match between the event's severity level and property severity. If acceptOnMatch is <span class="code">false</span>,
|
|
then the filter accepts an audit event if and only if there is not
|
|
a match between the event's severity level and property severity.
|
|
</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">true</span></td>
|
|
</tr>
|
|
</table>
|
|
<p class="body">
|
|
For example, the following configuration fragment directs the Checker to not report audit events with severity level
|
|
<span class="code">info</span>:
|
|
</p>
|
|
|
|
<pre class="body">
|
|
<module name="SeverityMatchFilter">
|
|
<property name="severity" value="info"/>
|
|
<property name="acceptOnMatch" value="false"/>
|
|
</module>
|
|
</pre>
|
|
|
|
<p class="body">
|
|
Filter <span class="code">SuppressionFilter</span> rejects audit events for Check errors according to a
|
|
<a href="#suppressionsxml"><em>suppressions XML document</em></a> in a file. If there is no configured suppressions file, the
|
|
Filter accepts all audit events.
|
|
</p>
|
|
|
|
<h4 class="body">SuppressionFilter Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>file</td>
|
|
<td>the name of the <em>suppressions XML document</em> file</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><span class="default">none</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<p class="body">
|
|
For example, the following configuration fragment directs the Checker to use a <span class="code">SuppressionFilter</span>
|
|
with suppressions file <span class="code">docs/suppressions.xml</span>:
|
|
</p>
|
|
|
|
<pre class="body">
|
|
<module name="SuppressionFilter">
|
|
<property name="file" value="docs/suppressions.xml"/>
|
|
</module>
|
|
</pre>
|
|
|
|
<p class="body">
|
|
A <a href="#suppressionsxml"><em>suppressions XML document</em></a> contains a set of <span class="code">suppress</span> elements,
|
|
where each <span class="code">suppress</span> element
|
|
has a <span class="code">files</span> attribute, a <span class="code">checks</span> attribute,
|
|
an optional <span class="code">lines</span> attribute, and an optional
|
|
<span class="code">columns</span> attribute.
|
|
Attributes <span class="code">files</span> and <span class="code">checks</span> are
|
|
<a href="property_types.html#regexp">regular expressions</a>.
|
|
Attributes <span class="code">lines</span> and <span class="code">columns</span> are
|
|
comma-separated values, where each value is an <a href="property_types.html#integer">integer</a> or
|
|
a range of integers denoted by integer-integer.
|
|
</p>
|
|
<p class="body">
|
|
An audit event for a Check error matches a <span class="code">suppress</span> element if
|
|
the file name for the event matches the <span class="code">files</span> attribute of the element,
|
|
the name of the Check matches the <span class="code">checks</span> attribute, and
|
|
the line of the event matches the <span class="code">lines</span> attribute (provided the attribute exists) or
|
|
the column of the event matches the <span class="code">columns</span> attribute (provided the attribute exists).
|
|
When a <span class="code">SuppressionFilter</span> decides an audit event for a Check error, it rejects
|
|
the event if the event matches any one of the configured <span class="code">suppress</span> elements. In all other
|
|
cases, the Filter accepts the event.
|
|
</p>
|
|
|
|
<p class="body">
|
|
For example, the following suppressions XML document directs a <span class="code">SuppressionFilter</span>
|
|
to reject <span class="code">JavadocStyleCheck</span> errors for lines 82 and 108 to 122 of file
|
|
<span class="code">AbstractComplexityCheck.java</span>, and
|
|
<span class="code">MagicNumberCheck</span> errors for line 221 of file
|
|
<span class="code">JavadocStyleCheck.java</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<?xml version="1.0"?>
|
|
|
|
<!DOCTYPE suppressions PUBLIC
|
|
"-//Puppy Crawl//DTD Suppressions 1.0//EN"
|
|
"http://www.puppycrawl.com/dtds/suppressions_1_0.dtd">
|
|
|
|
<suppressions>
|
|
<suppress checks="JavadocStyleCheck"
|
|
files="AbstractComplexityCheck.java"
|
|
lines="82,108-122"/>
|
|
<suppress checks="MagicNumberCheck"
|
|
files="JavadocStyleCheck.java"
|
|
lines="221"/>
|
|
</suppressions>
|
|
</pre>
|
|
|
|
<a name="auditlisteners"></a>
|
|
<h2>AuditListeners</h2>
|
|
<p class="body">
|
|
In addition to an audit reporter for text or XML output, a Checker can have
|
|
<a href="writinglisteners.html">custom AuditListeners</a>
|
|
that handle audit events. In order to use a custom listener, add a Checker</span>
|
|
submodule for the listener and its properties.
|
|
For example, to configure a <span class="code">Checker</span>
|
|
so that it uses custom listener <a href="writinglisteners.html#writing">VerboseListener</a> to print audit messages
|
|
to a file named "audit.txt", include the following module in the
|
|
configuration file:
|
|
</p>
|
|
|
|
<pre class="body">
|
|
<module name="com.mycompany.listeners.VerboseListener">
|
|
<property name="file" value="audit.txt"/>
|
|
</module>
|
|
</pre>
|
|
|
|
|
|
</p>
|
|
<a name="packagenames"></a>
|
|
<h2>Packages</h2>
|
|
<p class="body">
|
|
Checkstyle loads a module class according to the <span class="code">name</span>
|
|
of a <span class="code">module</span> element, and automatically appends pre-specified
|
|
package prefixes to that <span class="code">name</span> in its search for a loadable class.
|
|
By default, Checkstyle applies packages <span class="code">
|
|
com.puppycrawl.tools.checkstyle</span>, <span class="code">
|
|
com.puppycrawl.tools.checkstyle.filters</span>, and <span class="code">
|
|
com.puppycrawl.tools.checkstyle.checks</span> as well as any sub-packages of
|
|
<span class="code">com.puppycrawl.tools.checkstyle.checks</span> that are
|
|
distributed with Checkstyle. To specify other packages to apply,
|
|
create a <em>package names XML document</em> in a file, and provide that file as a
|
|
<a href="cmdline.html">command line</a> option or as a
|
|
attribute of an <a href="anttask.html">ant Checkstyle task</a>.
|
|
This is useful for integrating other modules in your configuration.
|
|
</p>
|
|
<p class="body">
|
|
A <em>package names XML document</em> specifies a list of package names. Here is a
|
|
sample package names XML document for packages <span class="code">
|
|
com.puppycrawl.tools.checkstyle</span> and <span class="code">
|
|
com.puppycrawl.tools.checkstyle.checks</span>:
|
|
</p>
|
|
<pre class="body">
|
|
<checkstyle-packages>
|
|
<package name="com.puppycrawl.tools.checkstyle">
|
|
<package name="checks"/>
|
|
</package>
|
|
</checkstyle-packages>
|
|
</pre>
|
|
<p class="body">
|
|
Notice that the packages are specified recursively - a child
|
|
<span class="code">package</span> element is
|
|
a subpackage of its parent <span class="code">package</span> element.
|
|
</p>
|
|
<p class="body">
|
|
For example, to incorporate modules from package <span class="code">com.mycompany.checks</span>
|
|
with Checkstyle modules, create the XML file below and specify that file as a
|
|
<a href="cmdline.html">command line</a> option or as a
|
|
attribute of an <a href="anttask.html">ant Checkstyle task</a>.:
|
|
</p>
|
|
<pre class="body">
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!DOCTYPE checkstyle-packages PUBLIC
|
|
"-//Puppy Crawl//DTD Package Names 1.0//EN"
|
|
"http://www.puppycrawl.com/dtds/packages_1_0.dtd">
|
|
|
|
<checkstyle-packages>
|
|
<package name="com.mycompany.checks">
|
|
<package name="com.puppycrawl.tools.checkstyle">
|
|
<package name="checks">
|
|
<package name="blocks"/>
|
|
<package name="coding"/>
|
|
<package name="design"/>
|
|
<package name="imports"/>
|
|
<package name="indentation"/>
|
|
<package name="j2ee"/>
|
|
<package name="javadoc"/>
|
|
<package name="metrics"/>
|
|
<package name="naming"/>
|
|
<package name="sizes"/>
|
|
<package name="whitespace"/>
|
|
</package>
|
|
<package name="filters"/>
|
|
</package>
|
|
</checkstyle-packages>
|
|
</pre>
|
|
<p class="body">
|
|
Now you can configure a module of package <span class="code">com.mycompany.checks</span>,
|
|
say <span class="code">com.mycompany.checks.MethodLimitCheck</span>, with a shortened
|
|
<span class="code">module</span> element in the configuration document:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="MethodLimit"/>
|
|
</pre>
|
|
<div class="tip">
|
|
<h4 class="tip">Important</h4>
|
|
|
|
If you provide a package names XML document for your own modules and still need to use
|
|
Checkstyle modules, you must include <span class="code">package</span> elements for
|
|
Checkstyle's packages.
|
|
</div>
|
|
<a name="xml"></a>
|
|
<h2>XML Details</h2>
|
|
<h4>Configuration XML Document</h4>
|
|
<p class="body">
|
|
The following DTD for a configuration XML document specifies the hierarchy of modules
|
|
and their properties:
|
|
</p>
|
|
<pre class="body">
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!ELEMENT module (module|property)*>
|
|
<!ATTLIST module name NMTOKEN #REQUIRED>
|
|
|
|
<!ELEMENT property EMPTY>
|
|
<!ATTLIST property
|
|
name NMTOKEN #REQUIRED
|
|
value CDATA #REQUIRED
|
|
>
|
|
</pre>
|
|
<p class="body">
|
|
Checkstyle validates a configuration XML document when it loads the document.
|
|
To validate against the above configuration DTD,
|
|
include the following document type declaration in
|
|
your configuration XML document:
|
|
</p>
|
|
<pre class="body">
|
|
<!DOCTYPE module PUBLIC
|
|
"-//Puppy Crawl//DTD Check Configuration 1.2//EN"
|
|
"http://www.puppycrawl.com/dtds/configuration_1_2.dtd">
|
|
</pre>
|
|
<p class="body">
|
|
Checkstyle also strictly enforces the encoding attribute of an XML declaration.
|
|
If Checkstyle rejects your configuration document's encoding,
|
|
correct the value of the encoding attribute, or remove the encoding attribute entirely.
|
|
</p>
|
|
<p class="body">
|
|
For a complete example of a configuration XML document, examine file <span class="code">docs/sun_checks.xml</span>
|
|
that checks the Sun coding conventions.
|
|
</p>
|
|
<h4>Package Names XML Document</h4>
|
|
<p class="body">
|
|
This is a DTD for a package names XML document:
|
|
</p>
|
|
<pre class="body">
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!ELEMENT checkstyle-packages (package)*>
|
|
|
|
<!ELEMENT package (package)*>
|
|
<!ATTLIST package name NMTOKEN #REQUIRED>
|
|
</pre>
|
|
<p class="body">
|
|
Checkstyle also validates a package names XML document when it loads the document.
|
|
To validate against the above package names DTD,
|
|
include the following document type declaration in
|
|
your package names XML document:
|
|
</p>
|
|
<pre class="body">
|
|
<!DOCTYPE checkstyle-packages PUBLIC
|
|
"-//Puppy Crawl//DTD Package Names 1.0//EN"
|
|
"http://www.puppycrawl.com/dtds/packages_1_0.dtd">
|
|
</pre>
|
|
|
|
<a name="suppressionsxml"></a>
|
|
<h4>Suppressions XML Document</h4>
|
|
<p class="body">
|
|
This is a DTD for a suppressions XML document:
|
|
</p>
|
|
<pre class="body">
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!ELEMENT suppressions (suppress*)>
|
|
|
|
<!ELEMENT suppress EMPTY>
|
|
<!ATTLIST suppress files CDATA #REQUIRED
|
|
checks CDATA #REQUIRED
|
|
lines CDATA #IMPLIED
|
|
columns CDATA #IMPLIED>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr />
|
|
<div><a href="index.html">Back to the Checkstyle Home Page</a></div>
|
|
<p class="copyright">
|
|
Copyright © 2002-2004 Oliver Burn. All rights Reserved.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|