| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <document xmlns="http://maven.apache.org/XDOC/2.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| |
| <head> |
| <title>Configuration</title> |
| <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/> |
| <script type="text/javascript" src="js/anchors.js"/> |
| <script type="text/javascript" src="js/google-analytics.js"/> |
| <link rel="icon" href="images/favicon.png" type="image/x-icon" /> |
| <link rel="shortcut icon" href="images/favicon.ico" type="image/ico" /> |
| </head> |
| |
| <body> |
| <section name="Content"> |
| <macro name="toc"> |
| <param name="fromDepth" value="1"/> |
| <param name="toDepth" value="1"/> |
| </macro> |
| </section> |
| |
| <section name="Overview"> |
| <p> |
| 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> |
| |
| <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> |
| 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> |
| 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> |
| </section> |
| |
| <section name="Modules"> |
| <p> |
| A <code>module</code> element in the configuration |
| XML document specifies a module identified by the element's |
| <code>name</code> attribute. |
| </p> |
| |
| <p> |
| Here is a fragment of a typical configuration document: |
| </p> |
| |
| <source> |
| <module name="Checker"> |
| <module name="JavadocPackage"/> |
| <module name="TreeWalker"> |
| <module name="AvoidStarImport"/> |
| <module name="ConstantName"/> |
| <module name="EmptyBlock"/> |
| </module> |
| </module> |
| </source> |
| |
| <p> |
| In this configuration: |
| </p> |
| |
| <ul> |
| <li> |
| Root module <code>Checker</code> has child |
| FileSetChecks <code>JavadocPackage</code> and <code>TreeWalker</code>. (Module <a |
| href="config_javadoc.html"> <code>JavadocPackage</code></a> checks that all packages |
| have package documentation.) |
| </li> |
| <li> |
| Module <code>TreeWalker</code> has submodules |
| <code>AvoidStarImport</code>, <code>ConstantName</code>, and <code>EmptyBlock</code>. (Modules <a |
| href="config_imports.html"><code>AvoidStarImport</code></a>, <a |
| href="config_naming.html"><code>ConstantName</code></a>, and <a |
| href="config_blocks.html"><code>EmptyBlock</code></a> check that a Java source |
| file has no star imports, has valid constant names, and has no |
| empty blocks, respectively.) |
| </li> |
| </ul> |
| |
| <p> |
| For each configuration module, Checkstyle loads a class |
| identified by the <code>name</code> attribute of |
| the <code>module</code>. There are several rules |
| for loading a module's class: |
| </p> |
| |
| <ol> |
| <li> |
| Load a class directly according to a package-qualified <code>name</code>, such as loading class <code>com.puppycrawl.tools.checkstyle.TreeWalker</code> |
| for element: |
| |
| <source> |
| <module name="com.puppycrawl.tools.checkstyle.TreeWalker"/> |
| </source> |
| |
| 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 |
| <code>com.puppycrawl.tools.checkstyle.checks.AvoidStarImport</code> |
| for element |
| <source> |
| <module name="AvoidStarImport"/> |
| </source> |
| |
| Checkstyle applies packages <code> |
| com.puppycrawl.tools.checkstyle</code>, <code> |
| com.puppycrawl.tools.checkstyle.filters</code>, and <code> com.puppycrawl.tools.checkstyle.checks</code> |
| and its sub-packages (only those included in the Checkstyle |
| distribution). You can specify other packages in a <a |
| href="#Packages"><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 <code>name</code> |
| concatenated with <code>"Check"</code>, |
| such as loading class <code>com.puppycrawl.tools.checkstyle.checks.ConstantNameCheck</code> |
| for element |
| <source> |
| <module name="ConstantName"/> |
| </source> |
| </li> |
| </ol> |
| </section> |
| |
| <section name="Properties"> |
| <p> |
| 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 <code>property</code> element of the <code>module</code> element in the configuration XML |
| document. Also provide appropriate <code>name</code> and <code>value</code> |
| attributes for the <code>property</code> element. |
| For example, property <code>max</code> of module |
| <code>MethodLength</code> specifies the maximum |
| allowable number of lines in a method or constructor, and has |
| default value <code>150</code>. Here is a |
| configuration of module <code>MethodLength</code> |
| so that the check reports methods and constructors with more |
| than <code>60</code> lines: |
| </p> |
| |
| <source> |
| <module name="MethodLength"> |
| <property name="max" value="60"/> |
| </module> |
| </source> |
| |
| <p> |
| <a href="cmdline.html">Command line</a> properties and ant <a |
| href="anttask.html">Checkstyle task</a> properties apply to the |
| root <code>Checker</code> 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 <code>tabWidth</code> of <code>4</code> applies to <code>TreeWalker</code> and its submodules: |
| </p> |
| |
| <source> |
| <module name="Checker"> |
| <module name="JavadocPackage"/> |
| <module name="TreeWalker"> |
| <property name="tabWidth" value="4"/> |
| <module name="AvoidStarImport"/> |
| <module name="ConstantName"/> |
| ... |
| </module> |
| </module> |
| </source> |
| |
| <p> |
| The value of a module property can be specified through |
| <em>property expansion</em> with the <code>${<em>property_name</em>}</code> notation, where |
| <code><em>property_name</em></code> 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 |
| <code>headerFile</code> the value of command line |
| property <code>checkstyle.header.file</code>: |
| </p> |
| |
| <source> |
| <module name="Header"> |
| <property name="headerFile" value="${checkstyle.header.file}"/> |
| </module> |
| </source> |
| |
| <p> |
| You can use property expansion to re-specify a module property |
| value without changing the configuration document. |
| </p> |
| |
| <p> |
| The property element provides an optional <code>default</code> 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 individual projects to |
| override the severity by specifying their desired value in the |
| command line property <code>checkstyle.javadoc.severity</code>: |
| </p> |
| |
| <source> |
| <module name="JavadocMethod"> |
| <property name="severity" |
| value="${checkstyle.javadoc.severity}" |
| default="error"/> |
| </module> |
| </source> |
| |
| <p> |
| 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 flexibility |
| to adjust a few settings to fit their needs without having to |
| copy and maintain the whole configuration. |
| </p> |
| |
| <p> |
| You can find information about property types on |
| <a href="property_types.html">Property Types</a> page. |
| </p> |
| |
| </section> |
| |
| <section name="Checker"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.0</p> |
| <p> |
| All configurations have root module <code>Checker</code>. <code>Checker</code> |
| contains: |
| </p> |
| |
| <ul> |
| <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>FileFilter</em> children: modules that filter files |
| for Checkstyle to process.</li> |
| <li><em>AuditListener</em> children: modules that report |
| filtered events.</li> |
| </ul> |
| |
| <p> |
| <code>Checker</code> also defines properties that are |
| inherited by all other modules of a configuration. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</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><code>null</code></td> |
| <td>3.0</td> |
| </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><code>null</code> (no cache file)</td> |
| <td>6.16</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> |
| <td>3.0</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> |
| <td>3.0</td> |
| </tr> |
| <tr> |
| <td>charset</td> |
| <td>name of the file charset</td> |
| <td><a href="property_types.html#string">String</a></td> |
| <td>System property "file.encoding"</td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>fileExtensions</td> |
| <td>file extensions that are accepted</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>null</code></td> |
| <td>6.3</td> |
| </tr> |
| <tr> |
| <td>severity</td> |
| <td>the default severity level of all violations</td> |
| <td><a href="property_types.html#severity">Severity</a></td> |
| <td><code>error</code></td> |
| <td>3.1</td> |
| </tr> |
| <tr> |
| <td>haltOnException</td> |
| <td>whether to stop execution of Checkstyle if a single file produces any kind of |
| exception during verification</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>7.4</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| For example, the following configuration fragment specifies base |
| directory <code>src/checkstyle</code>, cache file <code>target/cachefile</code> and German |
| locale for all modules: |
| </p> |
| |
| <source> |
| <module name="Checker"> |
| <property name="basedir" value="src/checkstyle"/> |
| <property name="cacheFile" value="target/cachefile"/> |
| <property name="localeCountry" value="DE"/> |
| <property name="localeLanguage" value="de"/> |
| <module name="JavadocPackage"/> |
| <module name="TreeWalker"> |
| ... |
| </module> |
| </module> |
| </source> |
| |
| <p> |
| To configure a <code>Checker</code> so that it |
| handles files with the <code>UTF-8</code> charset: |
| </p> |
| |
| <source> |
| <module name="Checker"> |
| <property name="charset" value="UTF-8"/> |
| ... |
| </module> |
| </source> |
| |
| <p> |
| To configure a <code>Checker</code> so that it |
| handles files with the <code>java, xml, properties</code> extensions: |
| </p> |
| |
| <source> |
| <module name="Checker"> |
| <property name="fileExtensions" value="java, xml, properties"/> |
| ... |
| </module> |
| </source> |
| |
| <p> |
| To configure a <code>Checker</code> so that it doesn't stop execution on an |
| <code>Exception</code> and instead prints it as a violation: |
| </p> |
| |
| <source> |
| <module name="Checker"> |
| <property name="haltOnException" value="false"/> |
| ... |
| </module> |
| </source> |
| |
| <p> |
| To configure a <code>Checker</code> so that it |
| handles files with any extension: |
| </p> |
| |
| <source> |
| <module name="Checker"> |
| <property name="fileExtensions" value="null"/> |
| ... |
| </module> |
| </source> |
| <p>OR</p> |
| <source> |
| <module name="Checker"> |
| <property name="fileExtensions" value=""/> |
| ... |
| </module> |
| </source> |
| |
| </subsection> |
| </section> |
| |
| <section name="TreeWalker"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.0</p> |
| <p> |
| FileSetCheck <code>TreeWalker</code> checks |
| individual Java source files and defines properties that are |
| applicable to checking such files. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>tabWidth</td> |
| <td>number of expanded spaces for a tab character (<code>'\t'</code>); used in messages and Checks that |
| require a tab width, such as <a |
| href="config_sizes.html#LineLength"><code>LineLength</code></a></td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td><code>8</code></td> |
| <td>3.0</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 <code>.java</code></td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>java</code></td> |
| <td>3.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| For example, the following configuration fragment specifies |
| <code>TreeWalker</code> a <code>tabWidth</code> of <code>4</code>: |
| </p> |
| |
| <source> |
| <module name="Checker"> |
| <module name="TreeWalker"> |
| <property name="tabWidth" value="4"/> |
| ... |
| </module> |
| </module> |
| </source> |
| |
| <p> |
| <!-- |
| 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> |
| |
| <source> |
| <module name="Checker"> |
| <module name="TreeWalker"> |
| <property name="fileExtensions" value="java,ejb,jpf"/> |
| ... |
| </module> |
| </module> |
| </source> |
| |
| <p> |
| To configure <code>TreeWalker</code> so that it |
| handles files with the <code>java</code> extension: |
| </p> |
| |
| <source> |
| <module name="TreeWalker"> |
| <property name="fileExtensions" value="java"/> |
| ... |
| </module> |
| </source> |
| |
| <p> |
| To configure <code>TreeWalker</code> so that it |
| handles files with any extension: |
| </p> |
| |
| <source> |
| <module name="TreeWalker"> |
| <property name="fileExtensions" value="null"/> |
| ... |
| </module> |
| </source> |
| <p>OR</p> |
| <source> |
| <module name="TreeWalker"> |
| <property name="fileExtensions" value=""/> |
| ... |
| </module> |
| </source> |
| </subsection> |
| </section> |
| |
| <section name="TreeWalker Checks"> |
| |
| <p> |
| The <code>TreeWalker</code> 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 <code>MethodLength</code> has been configured as a |
| submodule of <code>TreeWalker</code>, then a visit |
| to a node with a method or a constructor definition token |
| triggers <code>MethodLength</code> to check the |
| number of lines of the node's code block. |
| </p> |
| |
| <p> |
| Some Checks, such as <code>FileLength</code> and |
| <code>LineLength</code>, 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 |
| <code>MethodLength</code>: |
| </p> |
| |
| <source> |
| <module name="MethodLength"/> |
| </source> |
| |
| <p> |
| The default token set for <code>MethodLength</code> |
| is <code>{METHOD_DEF, CTOR_DEF}</code>, method |
| definition and constructor definition tokens, so <code>TreeWalker</code> invokes <code>MethodLength</code> whenever it visits a node with |
| a <code>METHOD_DEF</code> or a <code>CTOR_DEF</code> token. |
| </p> |
| |
| <p> |
| You specify the trigger tokens for a Check with property <code>tokens</code>. The value of <code>tokens</code> is a list that denotes a subset of |
| the Check's tokens, as in the following element that configures |
| Check <code>MethodLength</code> to check the number |
| of lines of methods only: |
| </p> |
| |
| <source> |
| <module name="MethodLength"> |
| <property name="tokens" value="METHOD_DEF"/> |
| </module> |
| </source> |
| |
| <p> |
| 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 |
| <code>MethodLength</code> property <code>max</code>) and the length of each constructor is |
| at most 60 lines, include the following in the <code>TreeWalker</code> configuration: |
| </p> |
| |
| <source> |
| <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> |
| </source> |
| |
| <p> |
| Configurations of the Checks are specified in the pages under <a |
| href="checks.html">here</a>. |
| </p> |
| |
| </section> |
| |
| <section name="Severity"> |
| <p> |
| 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 <code>error</code>. |
| </p> |
| |
| <p> |
| 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 <code>ignore</code>, and notes violations with |
| severity level <code>warning</code>. For |
| example, according to the following configuration fragment, the |
| plain formatter outputs warnings for translation violations: |
| </p> |
| |
| <source> |
| <module name="Translation"> |
| <property name="severity" value="warning"/> |
| </module> |
| </source> |
| |
| <p> |
| The XML formatter reports the severity level of every violation |
| as an attribute of the violation's <code>error</code> element. |
| </p> |
| </section> |
| |
| <section name="Custom messages"> |
| <p> |
| As of Checkstyle 5 all checks can be configured to report |
| custom, configuration specific messages instead of the |
| Checkstyle default messages. This can be useful in cases where |
| the check message should reference corresponding sections in a |
| coding style document or the default is too generic for |
| developers to understand. |
| </p> |
| |
| <p>An example usage is:</p> |
| |
| <source> |
| <module name="MemberName"> |
| <property name="format" value="^m[a-zA-Z0-9]*$"/> |
| <message key="name.invalidPattern" |
| value="Member ''{0}'' must start with a lowercase ''m'' (checked pattern ''{1}'')." |
| /> |
| </module> |
| </source> |
| |
| <p> |
| Each check configuration element can have zero or more <code>message</code> elements. Every check uses one or |
| more distinct message keys to log violations. If you want to |
| customize a certain message you need to specify the message key |
| in the <code>key</code> attribute of the <code>message</code> element. |
| </p> |
| |
| <p> |
| The <code>value</code> attribute specifies the |
| custom message pattern, as shown in the example above. |
| Placeholders used in the default message can also be used in the |
| custom message. Note that the message pattern must be a valid |
| <a href="https://docs.oracle.com/javase/8/docs/api/java/text/MessageFormat.html">java.text.MessageFormat</a> |
| style pattern, |
| so be careful about curly braces outside a placeholder |
| definition. |
| </p> |
| |
| <p> |
| The obvious question is how do you know which message keys a |
| Check uses, so that you can override them? You can examine all |
| keys in the check's specific <a href="checks.html">configuration |
| documentation</a>. Each check has a section called 'Error Messages'. |
| This section lists every key the check uses and links to the default |
| message used by checkstyle. |
| </p> |
| </section> |
| |
| <section name="Filters"> |
| |
| <p> |
| 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. For more information please visit |
| <a href="config_filters.html">filters page</a>. |
| </p> |
| |
| </section> |
| |
| <section name="Before Execution File Filters"> |
| |
| <p> |
| A Checker module has a Before Execution File Filter submodule to filter |
| files from being processed by the utility. A Before Execution File Filter |
| can accept or reject a file by its name. If all Before Execution File Filters |
| accept a file, then Checker will process and validate the file. |
| If any Before Execution File Filter rejects an file, then Checker skips over |
| the file and acts like it does not exist. |
| For more information, please visit the <a href="config_filefilters.html">file filters page</a>. |
| </p> |
| |
| </section> |
| |
| <section name="AuditListeners"> |
| |
| <p> |
| 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 <code>Checker</code> submodule for the |
| listener and its properties. For example, to configure a <code>Checker</code> so that it uses custom listener <a |
| href="writinglisteners.html#Writing_Listeners">VerboseListener</a> to |
| print audit messages to a file named "audit.txt", |
| include the following module in the configuration file: |
| </p> |
| |
| <source> |
| <module name="com.mycompany.listeners.VerboseListener"> |
| <property name="file" value="audit.txt"/> |
| </module> |
| </source> |
| |
| </section> |
| |
| <section name="Packages"> |
| <p> |
| Checkstyle loads a module class according to the <code>name</code> of a <code>module</code> |
| element, and automatically appends pre-specified package |
| prefixes to that <code>name</code> in its search |
| for a loadable class. By default, Checkstyle applies packages |
| <code> com.puppycrawl.tools.checkstyle</code>, |
| <code> |
| com.puppycrawl.tools.checkstyle.filters</code>, and <code> com.puppycrawl.tools.checkstyle.checks</code> as |
| well as any sub-packages of <code>com.puppycrawl.tools.checkstyle.checks</code> that |
| are distributed with Checkstyle. However standard checkstyle modules are loaded |
| with the help of inner map of their names to fully qualified names. |
| </p> |
| <p> |
| To specify other packages to apply, |
| create a <em>package names XML document</em> in a file |
| named <code>checkstyle_packages.xml</code>, |
| and provide that file in the root of the .jar containing your |
| custom checks. |
| </p> |
| <p> |
| Note that the support for providing a <em>package names XML document</em> |
| via <a href="cmdline.html">command line</a> option or as a attribute |
| of an <a href="anttask.html">ant Checkstyle task</a> has been dropped |
| with Checkstyle 5.0. |
| </p> |
| |
| <p> |
| A <em>package names XML document</em> specifies a list of |
| package names. Here is a sample package names XML document for |
| packages <code> |
| com.puppycrawl.tools.checkstyle</code> and <code> |
| com.puppycrawl.tools.checkstyle.checks</code>: |
| </p> |
| |
| <source> |
| <checkstyle-packages> |
| <package name="com.puppycrawl.tools.checkstyle"> |
| <package name="checks"/> |
| </package> |
| </checkstyle-packages> |
| </source> |
| |
| <p> |
| Notice that the packages are specified recursively - a child |
| <code>package</code> element is a subpackage of its |
| parent <code>package</code> element. |
| </p> |
| |
| <p> |
| For example, to incorporate modules from package <code>com.mycompany.checks</code> with Checkstyle |
| modules, create the XML file below and put this file into the |
| <b>root of the jar</b> file which contains your custom check modules. |
| The XML file must be named exactly <code>checkstyle_packages.xml</code>: |
| </p> |
| |
| <source> |
| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <!DOCTYPE checkstyle-packages PUBLIC |
| "-//Puppy Crawl//DTD Package Names 1.0//EN" |
| "http://checkstyle.sourceforge.net/dtds/packages_1_0.dtd"> |
| |
| <checkstyle-packages> |
| <package name="com.mycompany.checks"/> |
| </checkstyle-packages> |
| </source> |
| |
| <p> |
| Now you can configure a module of package <code>com.mycompany.checks</code>, say <code>com.mycompany.checks.MethodLimitCheck</code>, with |
| a shortened <code>module</code> element in the |
| configuration document: |
| </p> |
| |
| <source> |
| <module name="MethodLimit"/> |
| </source> |
| |
| <div class="tip"> |
| <b>Note</b> |
| <p> |
| As of Checkstyle 5.0 it is unnecessary to repeat the |
| <code>package</code> elements for Checkstyle's packages in |
| your custom <code>checkstyle_packages.xml</code> file. |
| </p> |
| </div> |
| |
| </section> |
| |
| <section name="XML Structure"> |
| |
| <b>Configuration XML Document</b> |
| <p> |
| The following DTD for a configuration XML document specifies the |
| hierarchy of modules and their properties: |
| </p> |
| |
| <source> |
| <?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 |
| > |
| </source> |
| |
| <p> |
| 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> |
| |
| <source> |
| <!DOCTYPE module PUBLIC |
| "-//Puppy Crawl//DTD Check Configuration 1.3//EN" |
| "http://checkstyle.sourceforge.net/dtds/configuration_1_3.dtd"> |
| </source> |
| |
| <p> |
| 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> |
| For a complete example of a configuration XML document, examine |
| file <code>docs/sun_checks.xml</code> that checks the Sun coding |
| conventions. |
| </p> |
| |
| <b>Package Names XML Document</b> |
| <p> |
| This is a DTD for a package names XML document: |
| </p> |
| |
| <source> |
| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <!ELEMENT checkstyle-packages (package)*> |
| |
| <!ELEMENT package (package)*> |
| <!ATTLIST package name NMTOKEN #REQUIRED> |
| </source> |
| |
| <p> |
| 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> |
| |
| <source> |
| <!DOCTYPE checkstyle-packages PUBLIC |
| "-//Puppy Crawl//DTD Package Names 1.1//EN" |
| "http://checkstyle.sourceforge.net/dtds/packages_1_1.dtd"> |
| </source> |
| |
| <b>Suppressions XML Document</b> |
| <p> |
| This is a DTD for a suppressions XML document: |
| </p> |
| |
| <source> |
| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <!ELEMENT suppressions (suppress*)> |
| |
| <!ELEMENT suppress EMPTY> |
| <!ATTLIST suppress files CDATA #IMPLIED |
| checks CDATA #IMPLIED |
| message CDATA #IMPLIED |
| id CDATA #IMPLIED |
| lines CDATA #IMPLIED |
| columns CDATA #IMPLIED> |
| </source> |
| |
| </section> |
| </body> |
| </document> |