checkstyle/src/xdocs/config_imports.xml

745 lines
25 KiB
XML

<?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">
<properties>
<title>Imports</title>
<author>Checkstyle Development Team</author>
</properties>
<body>
<section name="AvoidStarImport">
<subsection name="Description">
<p>
Checks that there are no import statements that use the * notation.
</p>
<p>
Rationale: Importing all classes from a package or static
members from a class leads to tight coupling between packages
or classes and might lead to problems when a new version of a
library introduces name clashes.
</p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>excludes</td>
<td>
packages where star imports are allowed. Note that this property
is not recursive, subpackages of excluded packages are not
automatically excluded.
</td>
<td><a href="property_types.html#stringSet">list of strings</a></td>
<td><code>empty list</code></td>
</tr>
<tr>
<td>allowClassImports</td>
<td>
whether to allow starred class imports like
<code>import java.util.*;</code>.
</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>false</code></td>
</tr>
<tr>
<td>allowStaticMemberImports</td>
<td>
whether to allow starred static member imports like
<code>import static org.junit.Assert.*;</code>
</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>false</code></td>
</tr>
</table>
</subsection>
<subsection name="Example">
<p>
An example how to configure the check so that star imports from
packages java.io and java.net as well as static members from class
from java.lang.Math are allowed:
</p>
<source>
&lt;module name="AvoidStarImport"&gt;
&lt;property name="excludes" value="java.io,java.net,java.lang.Math"/&gt;
&lt;property name="allowClassImports" value="false"/&gt;
&lt;property name="allowStaticMemberImports" value="false"/&gt;
&lt;/module&gt;
</source>
</subsection>
<subsection name="Package">
<p> com.puppycrawl.tools.checkstyle.checks.imports </p>
</subsection>
<subsection name="Parent Module">
<p>
<a href="config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
<section name="AvoidStaticImport">
<subsection name="Description">
<p>
Checks that there are no static import statements.
</p>
<p>
Rationale: Importing static members can lead to naming
conflicts between class' members. It may lead to poor code
readability since it may no longer be clear what class a
member resides in (without looking at the import statement).
</p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>excludes</td>
<td>
Allows for certain classes via a star notation to be
excluded such as <code>java.lang.Math.*</code> or specific static
members to be excluded like <code>java.lang.System.out</code> for a variable or
<code>java.lang.Math.random</code> for a
method.
<br/>
If you exclude a starred import on a class this automatically
excludes each member individually.
<br/>
For example: Excluding <code>java.lang.Math.*</code>. will allow the
import of each static member in the Math class
individually like <code>java.lang.Math.PI</code>.
</td>
<td><a href="property_types.html#stringSet">list of strings</a></td>
<td><code>empty list</code></td>
</tr>
</table>
</subsection>
<subsection name="Example">
<p>
An example of how to configure the check so that the <code>java.lang.System.out</code> member and all
members from <code>java.lang.Math</code> are
allowed:
</p>
<source>
&lt;module name="AvoidStaticImport"&gt;
&lt;property name="excludes" value="java.lang.System.out,java.lang.Math.*"/&gt;
&lt;/module&gt;
</source>
</subsection>
<subsection name="Package">
<p> com.puppycrawl.tools.checkstyle.checks.imports </p>
</subsection>
<subsection name="Parent Module">
<p>
<a href="config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
<section name="IllegalImport">
<subsection name="Description">
<p>
Checks for imports from a set of illegal packages. By default, the
check rejects all <code>sun.*</code> packages since
programs that contain direct calls to the <code>sun.*</code> packages are <a
href="http://java.sun.com/products/jdk/faq/faq-sun-packages.html">"not guaranteed
to work on all Java-compatible platforms"</a>. To reject other packages, set property <code> illegalPkgs</code> to a list of the illegal packages.
</p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>illegalPkgs</td>
<td>packages to reject</td>
<td><a href="property_types.html#stringSet">list of strings</a></td>
<td><code>sun</code></td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p>
To configure the check:
</p>
<source>
&lt;module name=&quot;IllegalImport&quot;/&gt;
</source>
<p>
To configure the check so that it rejects packages <code>java.io.*</code> and <code>java.sql.*</code>:
</p>
<source>
&lt;module name=&quot;IllegalImport&quot;&gt;
&lt;property name=&quot;illegalPkgs&quot; value=&quot;java.io, java.sql&quot;/&gt;
&lt;/module&gt;
</source>
</subsection>
<subsection name="Package">
<p>
com.puppycrawl.tools.checkstyle.checks.imports
</p>
</subsection>
<subsection name="Parent Module">
<p>
<a href="config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
<section name="RedundantImport">
<subsection name="Description">
<p>
Checks for redundant import statements. An import statement is
considered redundant if:
</p>
<ul>
<li>
It is a duplicate of another import. This is, when a class is
imported more than once.
</li>
<li>
The class imported is from the <code>java.lang</code>
package, e.g. importing <code>java.lang.String</code>.
</li>
<li>
The class imported is from the same package.
</li>
</ul>
</subsection>
<subsection name="Example">
<p>
To configure the check:
</p>
<source>
&lt;module name=&quot;RedundantImport&quot;/&gt;
</source>
</subsection>
<subsection name="Package">
<p>
com.puppycrawl.tools.checkstyle.checks.imports
</p>
</subsection>
<subsection name="Parent Module">
<p>
<a href="config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
<section name="UnusedImports">
<subsection name="Description">
<p>
Checks for unused import statements. Checkstyle uses a simple but
very reliable algorithm to report on unused import statements. An
import statement is considered unused if:
</p>
<ul>
<li>
It is not referenced in the file. The algorithm does not support
wild-card imports like <code>import
java.io.*;</code>. Most IDE's provide very sophisticated checks
for imports that handle wild-card imports.
</li>
<li>
It is a duplicate of another import. This is when a class is
imported more than once.
</li>
<li>
The class imported is from the <code>java.lang</code>
package. For example importing <code>java.lang.String</code>.
</li>
<li>
The class imported is from the same package.
</li>
<li>
<b>Optionally:</b> it is referenced in Javadoc comments. This check
is off by default, as it is considered bad practice to introduce
a compile time dependency for documentation purposes only.
As an example, the import <code>java.util.Date</code> would be
considered referenced with the Javadoc comment
<code>{@link Date}</code>. The alternative to avoid introducing a
compile time dependency would be to write the Javadoc comment as
<code>{@link java.util.Date}</code>.
</li>
</ul>
<p>
The main limitation of this check is handling the case where
an imported type has the same name as a declaration, such as a
member variable.
</p>
<p>
For example, in the following case the import <code>java.awt.Component</code> will not be flagged as
unused:
</p>
<source>
import java.awt.Component;
class FooBar {
private Object Component; // a bad practice in my opinion
...
}
</source>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>processJavadoc</td>
<td>whether to process Javadoc</td>
<td><a href="property_types.html#boolean">boolean</a></td>
<td><code>false</code></td>
</tr>
</table>
</subsection>
<subsection name="Example">
<p>
To configure the check:
</p>
<source>
&lt;module name=&quot;UnusedImports&quot;/&gt;
</source>
</subsection>
<subsection name="Package">
<p>
com.puppycrawl.tools.checkstyle.checks.imports
</p>
</subsection>
<subsection name="Parent Module">
<p>
<a href="config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
<section name="ImportOrder">
<subsection name="Description">
<p>Checks the ordering/grouping of imports. Features are:</p>
<ul>
<li>groups imports: ensures that groups of imports come in a
specific order (e.g., java. comes first, javax. comes second,
then everything else)</li>
<li>adds a separation between groups : ensures that a blank
line sit between each group</li>
<li>sorts imports inside each group: ensures that imports
within each group are in lexicographic order</li>
<li>sorts according to case: ensures that the comparison
between imports is case sensitive</li>
<li>groups static imports: ensures the relative order between
regular imports and static imports (see
<a href="property_types.html#importOrder">import orders</a>)</li>
</ul>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>option</td>
<td>policy on the relative order between regular imports and static imports</td>
<td><a href="property_types.html#importOrder">import order</a></td>
<td><code>under</code></td>
</tr>
<tr>
<td>groups</td>
<td>
list of imports groups (every group identified either by a
common prefix string, or by a regular expression enclosed
in forward slashes (e.g. <code>/regexp/</code>)
</td>
<td><a href="property_types.html#stringSet">list of strings</a></td>
<td><code>empty list</code></td>
</tr>
<tr>
<td>ordered</td>
<td>whether imports within group should be sorted</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>true</td>
</tr>
<tr>
<td>separated</td>
<td>
whether imports groups should be separated by, at least, one
blank line
</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>false</td>
</tr>
<tr>
<td>caseSensitive</td>
<td>whether string comparison should be case sensitive or not</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>true</td>
</tr>
</table>
</subsection>
<subsection name="Example">
<p>To configure the check so that it requires that:</p>
<ul>
<li>&quot;java&quot; and &quot;javax&quot; packages together first, then &quot;org&quot; and then all other imports</li>
<li>imports will be sorted in the groups</li>
<li>groups are separated by, at least, one blank line</li>
<li>static imports are above each local groups</li>
</ul>
<source>
&lt;module name=&quot;ImportOrder&quot;>
&lt;property name=&quot;groups&quot; value=&quot;/^javax?\./,org&quot;/>
&lt;property name=&quot;ordered&quot; value=&quot;true&quot;/>
&lt;property name=&quot;separated&quot; value=&quot;true&quot;/>
&lt;property name=&quot;option&quot; value=&quot;above&quot;/>
&lt;/module>
</source>
</subsection>
<subsection name="Package">
<p>
com.puppycrawl.tools.checkstyle.checks.imports
</p>
</subsection>
<subsection name="Parent Module">
<p>
<a href="config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
<section name="ImportControl">
<subsection name="Description">
<p>
Controls what can be imported in each package. Useful for
ensuring that application layering rules are not violated,
especially on large projects.
</p>
<p>
The DTD for a import control XML document is at <a
href="http://www.puppycrawl.com/dtds/import_control_1_1.dtd">http://www.puppycrawl.com/dtds/import_control_1_1.dtd</a>. It
contains documentation on each of the elements and attributes.
</p>
<p>
The check validates a XML document when it loads the document.
To validate against the above DTD, include the following
document type declaration in your XML document:
</p>
<pre>
&lt;!DOCTYPE import-control PUBLIC
&quot;-//Puppy Crawl//DTD Import Control 1.1//EN&quot;
&quot;http://www.puppycrawl.com/dtds/import_control_1_1.dtd&quot;&gt;
</pre>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>file</td>
<td>
name of the file containing the import control configuration.
</td>
<td><a href="property_types.html#string">string</a></td>
<td><code>null</code></td>
</tr>
<tr>
<td>url</td>
<td>
URL of the file containing the import control configuration.
</td>
<td><a href="property_types.html#string">string</a></td>
<td><code>null</code></td>
</tr>
</table>
</subsection>
<subsection name="Example">
<p>
To configure the check using a import control file called
&quot;import-control.xml&quot;, then have the following:
</p>
<source>
&lt;module name=&quot;ImportControl&quot;>
&lt;property name=&quot;file&quot; value=&quot;import-control.xml&quot;/>
&lt;/module>
</source>
<p>
In the example below, all classes beginning with an I in the package
java.awt are allowed. In the package java.io only the classes File
and InputStream are allowed.
</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle&quot;>
&lt;allow class=&quot;java\.awt\.I.*&quot; regex=&quot;true&quot;/>
&lt;allow class=&quot;java\.io\.(File|InputStream)&quot; local-only=&quot;true&quot;
regex=&quot;true&quot;/>
&lt;/import-control>
</source>
<p>
For an example import control file, look at the file called <a
href="https://github.com/checkstyle/checkstyle/blob/master/config/import-control.xml">import-control.xml</a>
which is part of the Checkstyle distribution.
</p>
</subsection>
<subsection name="Package">
<p>
com.puppycrawl.tools.checkstyle.checks.imports
</p>
</subsection>
<subsection name="Parent Module">
<p>
<a href="config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
<section name="CustomImportOrder">
<subsection name="Description">
<p>
Checks that the groups of import declarations appear in the order specified
by the user. If there is an import but its group is not specified in the
configuration such an import should be placed at the end of the import list.
</p>
</subsection>
<subsection name="RuleDescription">
<p>
The rule consists of:
</p>
<p>
1) STATIC group. This group sets the ordering of static imports.
</p>
<p>
2) SAME_PACKAGE(n) group. This group sets the ordering of the same package imports.
n' - a number of the first package domains. For example:
</p>
<source>
package java.util.concurrent;
import java.util.regex.Pattern;
import java.util.List;
import java.util.StringTokenizer;
import java.util.regex.Pattern;
import java.util.*;
import java.util.concurrent.AbstractExecutorService;
import java.util.concurrent.*;
</source>
<p>
And we have such configuration: SAME_PACKAGE (3).
Same package imports are java.util.*, java.util.concurrent.*,
java.util.concurrent.AbstractExecutorService,
java.util.List and java.util.StringTokenizer
</p>
<p>
3) THIRD_PARTY_PACKAGE group. This group sets ordering of third party imports.
Third party imports are all imports except STATIC,
SAME_PACKAGE(n), STANDARD_JAVA_PACKAGE and SPECIAL_IMPORTS.
</p>
<p>
4) STANDARD_JAVA_PACKAGE group. This group sets ordering of standard java (java|javax) imports.
</p>
<p>
5) SPECIAL_IMPORTS group. This group may contains some imports
that have particular meaning for the user.
</p>
</subsection>
<subsection name="Note">
<p>
Use the separator '###' between rules.
</p>
</subsection>
<subsection name="Properties">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
</tr>
<tr>
<td>customImportOrderRules</td>
<td>List of order declaration customizing by user.</td>
<td><a href="property_types.html#string">string</a></td>
<td><code>null</code></td>
</tr>
<tr>
<td>standardPackageRegExp</td>
<td>RegExp for STANDARD_JAVA_PACKAGE group imports.</td>
<td><a href="property_types.html#regexp">regular expression</a></td>
<td><code>java|javax</code></td>
</tr>
<tr>
<td>thirdPartyPackageRegExp</td>
<td>RegExp for THIRDPARTY_PACKAGE group imports.</td>
<td><a href="property_types.html#regexp">regular expression</a></td>
<td><code>.*</code></td>
</tr>
<tr>
<td>specialImportsRegExp</td>
<td>RegExp for SPECIAL_IMPORTS group imports.</td>
<td><a href="property_types.html#regexp">regular expression</a></td>
<td><code>^$</code></td>
</tr>
<tr>
<td>samePackageMatchingDepth</td>
<td>Number of first domains for SAME_PACKAGE group.</td>
<td><a href="property_types.html#integer">Integer</a></td>
<td><code>2</code></td>
</tr>
<tr>
<td>separateLineBetweenGroups</td>
<td>Force empty line separator between import groups.</td>
<td><a href="property_types.html#boolean">boolean</a></td>
<td><code>true</code></td>
</tr>
<tr>
<td>sortImportsInGroupAlphabetically</td>
<td>Force grouping alphabetically.</td>
<td><a href="property_types.html#boolean">boolean</a></td>
<td><code>false</code></td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p>
To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use
thirdPartyPackageRegExp and standardPackageRegExp options.
</p>
<source>
&lt;module name=&quot;CustomImportOrder&quot;&gt;
&lt;property name=&quot;customImportOrderRules&quot;
value=&quot;STATIC###SAME_PACKAGE(3)###THIRD_PARTY_PACKAGE###STANDARD_JAVA_PACKAGE&quot;/&gt;
&lt;property name=&quot;thirdPartyPackageRegExp&quot; value=&quot;com|org&quot;/&gt;
&lt;property name=&quot;standardPackageRegExp&quot; value=&quot;java|javax&quot;/&gt;
&lt;/module&gt;
</source>
<p>
Also, this check can be configured to force empty line separator between
import groups. For example.
</p>
<source>
&lt;module name=&quot;CustomImportOrder&quot;&gt;
&lt;property name=&quot;separateLineBetweenGroups&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>
By the option it is possible to force alphabetically sorting.
</p>
<source>
&lt;module name=&quot;CustomImportOrder&quot;&gt;
&lt;property name=&quot;sortImportsInGroupAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>
To force checking imports sequence such as:
</p>
<source>
package com.puppycrawl.tools.checkstyle.imports;
import com.google.common.annotations.GwtCompatible;
import com.google.common.annotations.Beta;
import com.google.common.annotations.VisibleForTesting;
import org.abego.treelayout.Configuration;
import static sun.tools.util.ModifierFilter.ALL_ACCESS;
import com.google.common.annotations.GwtCompatible; // violation here - should be in the
// THIRD_PARTY_PACKAGE group
import android.*;
</source>
<p>
configure as follows:
</p>
<source>
&lt;module name=&quot;CustomImportOrder&quot;&gt;
&lt;property name=&quot;customImportOrderRules&quot;
value=&quot;SAME_PACKAGE(3)###THIRD_PARTY_PACKAGE###STATIC###SPECIAL_IMPORTS&quot;/&gt;
&lt;property name=&quot;specialImportsRegExp&quot; value=&quot;android.*&quot;/&gt;
&lt;/module&gt;
</source>
</subsection>
<subsection name="Package">
<p>
com.puppycrawl.tools.checkstyle.checks.imports
</p>
</subsection>
<subsection name="Parent Module">
<p>
<a href="config.html#TreeWalker">TreeWalker</a>
</p>
</subsection>
</section>
</body>
</document>