Google Git
Sign in
android / platform / external / checkstyle / 36fdb1ba18843c9e5a6e3a7e3bbacfad7fde7369 / . / src / xdocs / config_imports.xml
blob: dc64d2ffd7070ecaede11b007d1e01a1844634a2 [file] [log] [blame]
<?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>Imports</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="AvoidStarImport">
<subsection name="Description">
<p>Since Checkstyle 3.0</p>
<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>
<th>since</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">String Set</a></td>
<td><code>empty list</code></td>
<td>3.2</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>
<td>5.3</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>
<td>5.3</td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<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="Example of Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AvoidStarImport">
Google Style</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AvoidStarImport">
Sun Style</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AvoidStarImport">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Error Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.avoidStar%22">
import.avoidStar</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
</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="AvoidStaticImport">
<subsection name="Description">
<p>Since Checkstyle 5.0</p>
<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>
<th>since</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">String Set</a></td>
<td><code>empty list</code></td>
<td>5.0</td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<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="Example of Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AvoidStaticImport">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Error Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.avoidStatic%22">
import.avoidStatic</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
</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>Since Checkstyle 5.8</p>
<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>
<p>
<a href="#CustomImportOrder_Example">Examples section</a> contains examples that
work with default formatter configurations of Eclipse, IntelliJ IDEA and NetBeans
</p>
</subsection>
<subsection name="Rule Description">
<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.
Imports are considered on SAME_PACKAGE group if <b>n</b> first domains in package name and import name are identical. For example:
</p>
<source>
package java.util.concurrent.locks;
import java.io.File;
import java.util.*; //#1
import java.util.List; //#2
import java.util.StringTokenizer; //#3
import java.util.concurrent.*; //#4
import java.util.concurrent.AbstractExecutorService; //#5
import java.util.concurrent.locks.LockSupport; //#6
import java.util.regex.Pattern; //#7
import java.util.regex.Matcher; //#8
</source>
<p>
If we have SAME_PACKAGE(3) on configuration file, imports #4-6 will be considered as a SAME_PACKAGE group (java.util.concurrent.*, java.util.concurrent.AbstractExecutorService, java.util.concurrent.locks.LockSupport). SAME_PACKAGE(2) will include #1-8. SAME_PACKAGE(4) will include only #6. SAME_PACKAGE(5) will result in no imports assigned to SAME_PACKAGE group because actual package java.util.concurrent.locks has only 4 domains.
</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/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="Notes">
<p>
Use the separator '###' between rules.
</p>
<p>
To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use
thirdPartyPackageRegExp and standardPackageRegExp options.
</p>
<p>
Pretty often one import can match more than one group. For example, static import from standard
package or regular expressions are configured to allow one import match multiple groups.
In this case, group will be assigned according to priorities:
</p>
<ol>
<li>STATIC has top priority</li>
<li>SAME_PACKAGE has second priority</li>
<li>STANDARD_JAVA_PACKAGE and SPECIAL_IMPORTS will compete using "best match" rule: longer
matching substring wins; in case of the same length, lower position of matching substring
wins; if position is the same, order of rules in configuration solves the puzzle.</li>
<li>THIRD_PARTY has the least priority</li>
</ol>
<p>
Few examples to illustrate "best match":
</p>
<p>
1. patterns STANDARD_JAVA_PACKAGE = "Check", SPECIAL_IMPORTS="ImportOrderCheck" and input file:
</p>
<source>
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
</source>
<p>
Result: imports will be assigned to SPECIAL_IMPORTS, because matching substring length is 16. Matching
substring for STANDARD_JAVA_PACKAGE is 5.
</p>
<p>
2. patterns STANDARD_JAVA_PACKAGE = "Check", SPECIAL_IMPORTS="Avoid" and file:
</p>
<source>
import com.puppycrawl.tools.checkstyle.checks.imports.AvoidStarImportCheck;
</source>
<p>
Result: import will be assigned to SPECIAL_IMPORTS. Matching substring length is 5 for both
patterns. However, "Avoid" position is lower then "Check" position.
</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>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>
<td>5.8</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>
<td>5.8</td>
</tr>
<tr>
<td>thirdPartyPackageRegExp</td>
<td>RegExp for THIRD_PARTY_PACKAGE group imports.</td>
<td><a href="property_types.html#regexp">Regular Expression</a></td>
<td><code>".*"</code></td>
<td>5.8</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>
<td>5.8</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>
<td>5.8</td>
</tr>
<tr>
<td>sortImportsInGroupAlphabetically</td>
<td>Force grouping alphabetically, in
<a href="https://en.wikipedia.org/wiki/ASCII#Order">
ASCII sort order</a>.</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>false</code></td>
<td>5.8</td>
</tr>
</table>
</subsection>
<subsection name="Examples" id="CustomImportOrder_Example">
<p>To configure the check so that it matches default Eclipse formatter configuration
(tested on Kepler and Luna releases):</p>
<ul>
<li>group of static imports is on the top</li>
<li>groups of non-static imports: &quot;java&quot; and &quot;javax&quot; packages 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>
</ul>
<p>Notes:</p>
<ul>
<li>&quot;com&quot; package is not mentioned on configuration, because it is
ignored by Eclipse Kepler and Luna (looks like Eclipse defect)</li>
<li>configuration below doesn't work in all 100% cases due to inconsistent behavior
prior to Mars release, but covers most scenarios</li>
</ul>
<source>
&lt;module name=&quot;CustomImportOrder&quot;&gt;
&lt;property name=&quot;customImportOrderRules&quot;
value=&quot;STATIC###STANDARD_JAVA_PACKAGE###SPECIAL_IMPORTS&quot;/&gt;
&lt;property name=&quot;specialImportsRegExp&quot; value=&quot;^org\.&quot;/&gt;
&lt;property name=&quot;sortImportsInGroupAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;separateLineBetweenGroups&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>To configure the check so that it matches default Eclipse formatter configuration
(tested on Mars release):</p>
<ul>
<li>group of static imports is on the top</li>
<li>groups of non-static imports: &quot;java&quot; and &quot;javax&quot; packages first,
then &quot;org&quot; and &quot;com&quot;, then all other imports as one group</li>
<li>imports will be sorted in the groups</li>
<li>groups are separated by, at least, one blank line</li>
</ul>
<source>
&lt;module name=&quot;CustomImportOrder&quot;&gt;
&lt;property name=&quot;customImportOrderRules&quot;
value=&quot;STATIC###STANDARD_JAVA_PACKAGE###SPECIAL_IMPORTS###THIRD_PARTY_PACKAGE&quot;/&gt;
&lt;property name=&quot;specialImportsRegExp&quot; value=&quot;^org\.&quot;/&gt;
&lt;property name=&quot;thirdPartyPackageRegExp&quot; value=&quot;^com\.&quot;/&gt;
&lt;property name=&quot;sortImportsInGroupAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;separateLineBetweenGroups&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>To configure the check so that it matches default IntelliJ IDEA formatter configuration
(tested on v14):</p>
<ul>
<li>group of static imports is on the bottom</li>
<li>groups of non-static imports: all imports except of &quot;javax&quot; and
&quot;java&quot;, then &quot;javax&quot; and &quot;java&quot;</li>
<li>imports will be sorted in the groups</li>
<li>groups are separated by, at least, one blank line</li>
</ul>
<p>
Note: &quot;separated&quot; option is disabled because IDEA default has blank line
between &quot;java&quot; and static imports, and no blank line between
&quot;javax&quot; and &quot;java&quot;
</p>
<source>
&lt;module name=&quot;CustomImportOrder&quot;&gt;
&lt;property name=&quot;customImportOrderRules&quot;
value=&quot;THIRD_PARTY_PACKAGE###SPECIAL_IMPORTS###STANDARD_JAVA_PACKAGE###STATIC&quot;/&gt;
&lt;property name=&quot;specialImportsRegExp&quot; value=&quot;^javax\.&quot;/&gt;
&lt;property name=&quot;standardPackageRegExp&quot; value=&quot;^java\.&quot;/&gt;
&lt;property name=&quot;sortImportsInGroupAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;separateLineBetweenGroups&quot; value=&quot;false&quot;/&gt;
&lt;/module&gt;
</source>
<p>To configure the check so that it matches default NetBeans formatter configuration
(tested on v8):</p>
<ul>
<li>groups of non-static imports are not defined, all imports will be sorted as a one
group</li>
<li>static imports are not separated, they will be sorted along with other imports</li>
</ul>
<source>
&lt;module name=&quot;CustomImportOrder&quot;/&gt;
</source>
<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>
It is possible to enforce <a href="https://en.wikipedia.org/wiki/ASCII#Order">
ASCII sort order</a>
of imports in groups using the following configuration:
</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>
Example of ASCII order:
</p>
<source>
import java.awt.Dialog;
import java.awt.Window;
import java.awt.color.ColorSpace;
import java.awt.Frame; // violation here - in ASCII order 'F' should go before 'c',
// as all uppercase come before lowercase letters
</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="Example of Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+CustomImportOrder">
Google Style</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+CustomImportOrder">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Error Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22custom.import.order%22">
custom.import.order</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22custom.import.order.lex%22">
custom.import.order.lex</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22custom.import.order.line.separator%22">
custom.import.order.line.separator</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22custom.import.order.nonGroup.expected%22">
custom.import.order.nonGroup.expected</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22custom.import.order.nonGroup.import%22">
custom.import.order.nonGroup.import</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
</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="IllegalImport">
<subsection name="Description">
<p>Since Checkstyle 3.0</p>
<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://www.oracle.com/technetwork/java/faq-sun-packages-142232.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>
<th>since</th>
</tr>
<tr>
<td>illegalPkgs</td>
<td>Packages to reject, if <b>regexp</b> variable is not set, checks if import is the part of package. If <b>regexp</b> variable is set, then list of packages will be
interpreted as regular expressions. Note, all properties for match will be used.</td>
<td><a href="property_types.html#stringSet">String Set</a></td>
<td><code>sun</code></td>
<td>3.0</td>
</tr>
<tr>
<td>illegalClasses</td>
<td>Class names to reject, if <b>regexp</b> variable is not set, checks if import equals class name. If <b>regexp</b> variable is set, then list of class name will be
interpreted as regular expressions. Note, all properties for match will be used.</td>
<td><a href="property_types.html#stringSet">String Set</a></td>
<td><code>{}</code></td>
<td>7.8</td>
</tr>
<tr>
<td>regexp</td>
<td>Whether the <b>illegalPkgs</b> and <b>illegalClasses</b> should be interpreted as regular expressions</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>false</code></td>
<td>7.8</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>
<p>
The following example shows class with no illegal imports
</p>
<source>
import java.lang.ArithmeticException;
import java.util.List;
import java.util.Enumeration;
import java.util.Arrays;
import sun.applet.*;
public class InputIllegalImport { }
</source>
<p>
The following example shows class with two illegal imports
<ul>
<li><b>java.io.*</b>, illegalPkgs property contains this package</li>
<li><b>java.sql.Connection</b> is inside java.sql package</li>
</ul>
</p>
<source>
import java.io.*; // violation
import java.lang.ArithmeticException;
import java.sql.Connection; // violation
import java.util.List;
import java.util.Enumeration;
import java.util.Arrays;
import sun.applet.*;
public class InputIllegalImport { }
</source>
<p>
To configure the check so that it rejects classes <code>java.util.Date</code> and <code>java.sql.Connection</code>:
</p>
<source>
&lt;module name=&quot;IllegalImport&quot;&gt;
&lt;property name=&quot;illegalClasses&quot; value=&quot;java.util.Date, java.sql.Connection&quot;/&gt;
&lt;/module&gt;
</source>
<p>
The following example shows class with no illegal imports
</p>
<source>
import java.io.*;
import java.lang.ArithmeticException;
import java.util.List;
import java.util.Enumeration;
import java.util.Arrays;
import sun.applet.*;
public class InputIllegalImport { }
</source>
<p>
The following example shows class with two illegal imports
<ul>
<li><b>java.sql.Connection</b>, illegalClasses property contains this class</li>
<li><b>java.util.Date</b>, illegalClasses property contains this class</li>
</ul>
</p>
<source>
import java.io.*;
import java.lang.ArithmeticException;
import java.sql.Connection; // violation
import java.util.List;
import java.util.Enumeration;
import java.util.Arrays;
import java.util.Date; // violation
import sun.applet.*;
public class InputIllegalImport { }
</source>
<p>
To configure the check so that it rejects packages not satisfying to regular expression <code>java\.util</code>:
</p>
<source>
&lt;module name=&quot;IllegalImport&quot;&gt;
&lt;property name=&quot;regexp&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;illegalPkgs&quot; value=&quot;java\.util&quot;/&gt;
&lt;/module&gt;
</source>
<p>
The following example shows class with no illegal imports
</p>
<source>
import java.io.*;
import java.lang.ArithmeticException;
import java.sql.Connection;
import sun.applet.*;
public class InputIllegalImport { }
</source>
<p>
The following example shows class with four illegal imports
<ul>
<li><b>java.util.List</b></li>
<li><b>java.util.Enumeration</b></li>
<li><b>java.util.Arrays</b></li>
<li><b>java.util.Date</b></li>
</ul>
All four imports match "java\.util" regular expression
</p>
<source>
import java.io.*;
import java.lang.ArithmeticException;
import java.sql.Connection;
import java.util.List; // violation
import java.util.Enumeration; // violation
import java.util.Arrays; // violation
import java.util.Date; // violation
import sun.applet.*;
public class InputIllegalImport { }
</source>
<p>
To configure the check so that it rejects class names not satisfying to regular expression <code>^java\.util\.(List|Arrays)</code> and <code>^java\.sql\.Connection</code>:
</p>
<source>
&lt;module name=&quot;IllegalImport&quot;&gt;
&lt;property name=&quot;regexp&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;illegalClasses&quot; value=&quot;^java\.util\.(List|Arrays), ^java\.sql\.Connection&quot;/&gt;
&lt;/module&gt;
</source>
<p>
The following example shows class with no illegal imports
</p>
<source>
import java.io.*;
import java.lang.ArithmeticException;
import java.util.Enumeration;
import java.util.Date;
import sun.applet.*;
public class InputIllegalImport { }
</source>
<p>
The following example shows class with three illegal imports
<ul>
<li><b>java.sql.Connection</b> matches "^java\.sql\.Connection" regular expression</li>
<li><b>java.util.List</b> matches "^java\.util\.(List|Arrays)" regular expression</li>
<li><b>java.util.Arrays</b> matches "^java\.util\.(List|Arrays)" regular expression</li>
</ul>
</p>
<source>
import java.io.*;
import java.lang.ArithmeticException;
import java.sql.Connection; // violation
import java.util.List; // violation
import java.util.Enumeration;
import java.util.Arrays; // violation
import java.util.Date;
import sun.applet.*;
public class InputIllegalImport { }
</source>
</subsection>
<subsection name="Example of Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+IllegalImport">
Sun Style</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+IllegalImport">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Error Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.illegal%22">
import.illegal</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
</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="ImportControl">
<subsection name="Description">
<p>Since Checkstyle 4.0</p>
<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>
Short description of the behaviour:
<ul>
<li>Check starts checking from the longest matching subpackage (later 'current subpackage') described inside import control file to package defined in class file.</li>
<li>If there is matching allow/disallow rule inside the current subpackage then the Check returns "allowed" or "disallowed" message.</li>
<li>If there is no matching allow/disallow rule inside the current subpackage then it continues checking in the parent subpackage.</li>
<li>If there is no matching allow/disallow rule in any of the subpackages, including the root level (import-control), then the import is disallowed by default.</li>
</ul>
</p>
<p>
The DTD for a import control XML document is at <a
href="http://checkstyle.sourceforge.net/dtds/import_control_1_3.dtd">
http://checkstyle.sourceforge.net/dtds/import_control_1_3.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.3//EN&quot;
&quot;http://checkstyle.sourceforge.net/dtds/import_control_1_3.dtd&quot;&gt;
</pre>
</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>file</td>
<td>
The location of the file containing the import control configuration.
It can be a regular file, URL or resource path. It will try loading
the path as a URL first, then as a file, and finally as a resource.
</td>
<td><a href="property_types.html#uri">URI</a></td>
<td><code>null</code></td>
<td>4.0</td>
</tr>
<tr>
<td>path</td>
<td>
Regular expression of file paths to which this check should apply. Files that
don't match the pattern will not be checked. The pattern will be matched against
the full absolute file path.
</td>
<td><a href="property_types.html#regexp">Regular Expression</a></td>
<td><code>".*"</code></td>
<td>7.5</td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p>
To configure the check using an import control file called
&quot;config/import-control.xml&quot;, then have the following:
</p>
<source>
&lt;module name=&quot;ImportControl&quot;&gt;
&lt;property name=&quot;file&quot; value=&quot;config/import-control.xml&quot;/&gt;
&lt;/module&gt;
</source>
<p>
To configure the check to only check the &quot;src/main&quot; directory
using an import control file called &quot;config/import-control.xml&quot;,
then have the following:
</p>
<source>
&lt;module name=&quot;ImportControl&quot;&gt;
&lt;property name=&quot;file&quot; value=&quot;config/import-control.xml&quot;/&gt;
&lt;property name=&quot;path&quot; value=&quot;^.*[\\/]src[\\/]main[\\/].*$&quot;/&gt;
&lt;/module&gt;
</source>
<p>
In the example below access to package
<code>com.puppycrawl.tools.checkstyle.checks</code> and its subpackages is
allowed from anywhere in <code>com.puppycrawl.tools.checkstyle</code> except
from the <code>filters</code> subpackage where access to all
<code>check</code>'s subpackages is disallowed. Two <code>java.lang.ref</code>
classes are allowed by virtue of one regular expression instead of listing
them in two separate allow rules (as it is done with the <code>Files</code>
and <code>ClassPath</code> classes).
</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle&quot;&gt;
&lt;disallow pkg=&quot;sun&quot;/&gt;
&lt;allow pkg=&quot;com.puppycrawl.tools.checkstyle.api&quot;/&gt;
&lt;allow pkg=&quot;com.puppycrawl.tools.checkstyle.checks&quot;/&gt;
&lt;allow class=&quot;com.google.common.io.Files&quot;/&gt;
&lt;allow class=&quot;com.google.common.reflect.ClassPath&quot;/&gt;
&lt;subpackage name=&quot;filters&quot;&gt;
&lt;allow class=&quot;java\.lang\.ref\.(Weak|Soft)Reference&quot;
regex=&quot;true&quot;/&gt;
&lt;disallow pkg=&quot;com\.puppycrawl\.tools\.checkstyle\.checks\.[^.]+&quot;
regex=&quot;true&quot;/&gt;
&lt;disallow pkg=&quot;com.puppycrawl.tools.checkstyle.ant&quot;/&gt;
&lt;disallow pkg=&quot;com.puppycrawl.tools.checkstyle.doclets&quot;/&gt;
&lt;disallow pkg=&quot;com.puppycrawl.tools.checkstyle.gui&quot;/&gt;
&lt;/subpackage&gt;
&lt;subpackage name=&quot;dao&quot;&gt;
&lt;disallow pkg=&quot;javax.swing&quot; exact-match=&quot;true&quot;/&gt;
&lt;/subpackage&gt;
&lt;/import-control&gt;
</source>
<p>
In the next example regular expressions are used to enforce a layering rule: In all
<code>dao</code> packages it is not allowed to access UI layer code (<code>ui</code>,
<code>awt</code>, and <code>swing</code>). On the other hand it is not allowed to directly
access <code>dao</code> and <code>service</code> layer from <code>ui</code> packages. The
root package is also a regular expression that is used to handle old and new domain name
with the same rules.
</p>
<source>
&lt;import-control pkg=&quot;(de.olddomain|de.newdomain)\..*&quot; regex=&quot;true&quot;&gt;
&lt;subpackage pkg=&quot;[^.]+\.dao&quot; regex=&quot;true&quot;&gt;
&lt;disallow pkg=&quot;.*\.ui&quot; regex=&quot;true&quot;/&gt;
&lt;disallow pkg=&quot;.*\.(awt|swing).\.*&quot; regex=&quot;true&quot;/&gt;
&lt;/subpackage&gt;
&lt;subpackage pkg=&quot;[^.]+\.ui&quot; regex=&quot;true&quot;&gt;
&lt;disallow pkg=&quot;.*\.(dao|service)&quot; regex=&quot;true&quot;/&gt;
&lt;/subpackage&gt;
&lt;/import-control&gt;
</source>
<p>
In the next examples usage of <code>strategyOnMismatch</code> property is shown.
This property defines strategy in a case when no matching allow/disallow rule was found.
Property <code>strategyOnMismatch</code> is attribute of <code>import-control</code> and <code>subpackage</code> tags.
Property can have following values for <code>import-control</code> tag:
<ul>
<li>disallowed (default value) - if there is no matching allow/disallow rule in any of the subpackages, including the root level (import-control), then the import is disallowed.</li>
<li>allowed - if there is no matching allow/disallow rule in any of the subpackages, including the root level, then the import is allowed.</li>
</ul>
And following values for <code>subpackage</code> tags:
<ul>
<li>delegateToParent (default value) - if there is no matching allow/disallow rule inside the current subpackage, then it continues checking in the parent subpackage.</li>
<li>allowed - if there is no matching allow/disallow rule inside the current subpackage, then the import is allowed.</li>
<li>disallowed - if there is no matching allow/disallow rule inside the current subpackage, then the import is disallowed.</li>
</ul>
</p>
<p>
The following example demonstrates usage of <code>strategyOnMismatch</code> property for <code>import-control</code> tag. Here all imports are allowed except <code>java.awt.Image</code> and <code>java.io.File</code> classes.
</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle.checks&quot; strategyOnMismatch=&quot;allowed&quot;&gt;
&lt;disallow class=&quot;java.awt.Image&quot;/&gt;
&lt;disallow class=&quot;java.io.File&quot;/&gt;
&lt;/import-control&gt;
</source>
<p>
In the example below, any import is disallowed inside <code>com.puppycrawl.tools.checkstyle.checks.imports</code> package except imports from package <code>javax.swing</code> and class <code>java.io.File</code>.
However, any import is allowed in the classes outside of <code>com.puppycrawl.tools.checkstyle.checks.imports</code> package.
</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle.checks&quot; strategyOnMismatch=&quot;allowed&quot;&gt;
&lt;subpackage name=&quot;imports&quot; strategyOnMismatch=&quot;disallowed&quot;&gt;
&lt;allow pkg=&quot;javax.swing&quot;/&gt;
&lt;allow class=&quot;java.io.File&quot;/&gt;
&lt;/subpackage&gt;
&lt;/import-control&gt;
</source>
<p>
When <code>strategyOnMismatch</code> has <code>allowed</code> or <code>disallowed</code> value for <code>subpackage</code> tag, it makes <code>subpackage</code> isolated from parent rules.
In the next example, if no matching rule was found inside <code>com.puppycrawl.tools.checkstyle.checks.filters</code> then it continues checking in the parent subpackage, while for <code>com.puppycrawl.tools.checkstyle.checks.imports</code> import will be allowed by default.
</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle.checks&quot;&gt;
&lt;allow class=&quot;java\.awt\.Image&quot; regex=&quot;true&quot;/&gt;
&lt;allow class=&quot;java\..*\.File&quot; local-only=&quot;true&quot; regex=&quot;true&quot;/&gt;
&lt;subpackage name=&quot;imports&quot; strategyOnMismatch=&quot;allowed&quot;&gt;
&lt;allow pkg=&quot;javax\.swing&quot; regex=&quot;true&quot;/&gt;
&lt;allow pkg=&quot;java\.io&quot; exact-match=&quot;true&quot; local-only=&quot;true&quot; regex=&quot;true&quot;/&gt;
&lt;/subpackage&gt;
&lt;subpackage name=&quot;filters&quot;&gt;
&lt;allow class=&quot;javax.util.Date&quot;/&gt;
&lt;/subpackage&gt;
&lt;/import-control&gt;
</source>
<p>
For a real-life 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>
<h4 id="blacklist-example">Example of blacklist mode</h4>
<p>To have a <b>blacklist mode</b>, it is required to have disallows inside subpackage and to have allow rule inside parent of the current subpackage to catch classes and packages those are not in the blacklist.</p>
<p>In the example below any import from <code>java.util</code> (<code>java.util.List</code>, <code>java.util.Date</code>) package is allowed except <code>java.util.Map</code> inside subpackage <code>com.puppycrawl.tools.checkstyle.filters</code>.</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle&quot;&gt;
&lt;allow pkg=&quot;java.util&quot;/&gt;
&lt;subpackage name=&quot;filters&quot; &gt;
&lt;disallow class=&quot;java.util.Map&quot;/&gt;
&lt;/subpackage&gt;
&lt;/import-control&gt;
</source>
<p>
In the next example imports <code>java.util.stream.Stream</code> and <code>java.util.stream.Collectors</code> are disallowed inside <code>com.puppycrawl.tools.checkstyle.checks.imports</code> package,
but because of <code>&lt;allow pkg=&quot;java.util.stream&quot;/&gt;</code> every import from <code>java.util.stream</code> is allowed except described ones.
</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle.checks&quot;&gt;
&lt;allow pkg=&quot;java.util.stream&quot;/&gt;
&lt;subpackage name=&quot;imports&quot;&gt;
&lt;disallow class=&quot;java.util.stream.Stream&quot;/&gt;
&lt;disallow class=&quot;java.util.stream.Collectors&quot;/&gt;
&lt;/subpackage&gt;
&lt;/import-control&gt;
</source>
<source>
package com.puppycrawl.tools.checkstyle.checks.imports;
import java.util.stream.Stream; // violation here
import java.util.stream.Collectors; // violation here
import java.util.stream.IntStream;
</source>
<p>
In the following example, all imports are allowed except the classes <code>java.util.Date</code>, <code>java.util.List</code> and package <code>sun</code>.
</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle.checks&quot;&gt;
&lt;allow pkg=&quot;.*&quot; regex=&quot;true&quot;/&gt;
&lt;subpackage name=&quot;imports&quot;&gt;
&lt;disallow class=&quot;java.util.Date&quot;/&gt;
&lt;disallow class=&quot;java.util.List&quot;/&gt;
&lt;disallow pkg=&quot;sun&quot;/&gt;
&lt;/subpackage&gt;
&lt;/import-control&gt;
</source>
<h4 id="regex-notes">Notes on regular expressions</h4>
<p>
Regular expressions in import rules have to match either Java packages or
classes. The language rules for packages and class names can be described by the
following complicated regular expression that takes into account that Java names may
contain any unicode letter, numbers, underscores, and dollar signs (see section 3.8
in the <a href="https://docs.oracle.com/javase/specs/">Java specs</a>):
</p>
<ul>
<li>
<code>[\p{Letter}_$][\p{Letter}\p{Number}_$]*</code> or short
<code>[\p{L}_$][\p{L}\p{N}_$]*</code> for a class name or package component.
</li>
<li>
<code>([\p{L}_$][\p{L}\p{N}_$]*\.)*[\p{L}_$][\p{L}\p{N}_$]*</code>
for a fully qualified name.
</li>
</ul>
<p>
But it is not necessary to use these complicated expressions since no validation is
required. Differentiating between package separator '.' and others is
sufficient. Unfortunately '.' has a special meaning in regular expressions so one has
to write <code>\.</code> to match an actual dot.
</p>
<ul>
<li>
Use <code>[^.]+</code> (one or more "not a dot" characters) for a class name or
package component.
</li>
<li>
Use <code>com\.google\.common\.[^.]+</code> to match any subpackage of
<code>com.google.common</code>.
</li>
<li>
When matching concrete packages like <code>com.google.common</code> omitting the
backslash before the dots may improve readability and may be just exact enough:
<code>com.google.common\.[^.]+</code> matches not only subpackages of
<code>com.google.common</code> but e.g. also of <code>com.googleecommon</code> but
you may not care for that.
</li>
<li>
Do not use <code>.*</code> unless you really do not care for what is matched. Often
you want to match only a certain package level instead.
</li>
</ul>
<h4 id="static-import-notes">Notes on static imports</h4>
<p>
Static members (including methods, constants and static inner classes) have to be
explicitly allowed when they are imported, they
are not automatically allowed along with their enclosing class.
</p>
<p>
For example, to allow importing both <code>java.util.Map</code> and
<code>java.util.Map.Entry</code> use the following configuration:
</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle&quot;&gt;
&lt;allow class=&quot;java.util.Map&quot;/&gt;
&lt;allow class=&quot;java.util.Map.Entry&quot;/&gt;
&lt;/import-control&gt;
</source>
<p>It is also possible to use a regex with a wildcard:</p>
<source>
&lt;import-control pkg=&quot;com.puppycrawl.tools.checkstyle&quot;&gt;
&lt;allow class=&quot;java.util.Map&quot;/&gt;
&lt;allow class=&quot;java.util.Map.*&quot; regex=&quot;true&quot; /&gt;
&lt;/import-control&gt;
</source>
</subsection>
<subsection name="Example of Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+ImportControl">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Error Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.control.disallowed%22">
import.control.disallowed</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.control.missing.file%22">
import.control.missing.file</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.control.unknown.pkg%22">
import.control.unknown.pkg</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
</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="ImportOrder">
<subsection name="Description">
<p>Since Checkstyle 3.2</p>
<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>import groups aren't separated internally: ensures that
each group aren't separated internally by blank line or comment</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, in
<a href="https://en.wikipedia.org/wiki/ASCII#Order">ASCII sort order</a></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>
<p>
<a href="#ImportOrder_Example">Examples section</a> contains examples that
work with default formatter configurations of Eclipse, IntelliJ IDEA and NetBeans
</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>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>
<td>5.0</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">String Set</a></td>
<td><code>empty list</code></td>
<td>3.2</td>
</tr>
<tr>
<td>ordered</td>
<td>whether imports within group should be sorted
(It doesn't affect sorting for static imports.)</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>true</td>
<td>3.2</td>
</tr>
<tr>
<td>separated</td>
<td>
whether imports groups should be separated by, at least, one
blank line or comment and aren't separated internally
</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>false</td>
<td>3.2</td>
</tr>
<tr>
<td>caseSensitive</td>
<td>whether string comparison should be case sensitive or not.
Case sensitive sorting is in
<a href="https://en.wikipedia.org/wiki/ASCII#Order">ASCII sort order</a>
</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>true</td>
<td>3.3</td>
</tr>
<tr>
<td>sortStaticImportsAlphabetically</td>
<td>whether <b>static imports</b> grouped by <b>top</b> or <b>bottom</b> option
are sorted alphabetically or not.
Attention: It is applied to all static imports as one group.</td>>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>false</td>
<td>6.5</td>
</tr>
<tr>
<td>useContainerOrderingForStatic</td>
<td>whether to use container ordering (Eclipse IDE term) for static imports or not</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>false</td>
<td>7.1</td>
</tr>
<tr>
<td>tokens</td>
<td>tokens to check</td>
<td>
subset of tokens
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#STATIC_IMPORT">STATIC_IMPORT</a>.
</td>
<td>
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#STATIC_IMPORT">STATIC_IMPORT</a>.
</td>
<td>3.2</td>
</tr>
</table>
</subsection>
<subsection name="Examples" id="ImportOrder_Example">
<p>To configure the check so that it matches default Eclipse formatter configuration
(tested on Kepler and Luna releases):</p>
<ul>
<li>group of static imports is on the top</li>
<li>groups of non-static imports: &quot;java&quot; and &quot;javax&quot; packages 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 and aren't separated internally</li>
</ul>
<p>Notes:</p>
<ul>
<li>&quot;com&quot; package is not mentioned on configuration, because it is
ignored by Eclipse Kepler and Luna (looks like Eclipse defect)</li>
<li>configuration below doesn't work in all 100% cases due to inconsistent behavior
prior to Mars release, but covers most scenarios</li>
</ul>
<source>
&lt;module name=&quot;ImportOrder&quot;&gt;
&lt;property name=&quot;groups&quot; value=&quot;/^java\./,javax,org&quot;/&gt;
&lt;property name=&quot;ordered&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;separated&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;option&quot; value=&quot;above&quot;/&gt;
&lt;property name=&quot;sortStaticImportsAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>To configure the check so that it matches default Eclipse formatter
configuration (tested on Mars release):</p>
<ul>
<li>group of static imports is on the top</li>
<li>groups of non-static imports: &quot;java&quot; and &quot;javax&quot; packages first,
then &quot;org&quot; and &quot;com&quot;, then all other imports as one group</li>
<li>imports will be sorted in the groups</li>
<li>groups are separated by, at least, one blank line and aren't separated internally</li>
</ul>
<source>
&lt;module name=&quot;ImportOrder&quot;&gt;
&lt;property name=&quot;groups&quot; value=&quot;/^java\./,javax,org,com&quot;/&gt;
&lt;property name=&quot;ordered&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;separated&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;option&quot; value=&quot;above&quot;/&gt;
&lt;property name=&quot;sortStaticImportsAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>To configure the check so that it matches default IntelliJ IDEA formatter
configuration (tested on v14):</p>
<ul>
<li>group of static imports is on the bottom</li>
<li>groups of non-static imports: all imports except of &quot;javax&quot;
and &quot;java&quot;, then &quot;javax&quot; and &quot;java&quot;</li>
<li>imports will be sorted in the groups</li>
<li>groups are separated by, at least, one blank line and aren't separated internally</li>
</ul>
<p>
Note: &quot;separated&quot; option is disabled because IDEA default has blank line
between &quot;java&quot; and static imports, and no blank line between
&quot;javax&quot; and &quot;java&quot;
</p>
<source>
&lt;module name=&quot;ImportOrder&quot;&gt;
&lt;property name=&quot;groups&quot; value=&quot;*,javax,java&quot;/&gt;
&lt;property name=&quot;ordered&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;separated&quot; value=&quot;false&quot;/&gt;
&lt;property name=&quot;option&quot; value=&quot;bottom&quot;/&gt;
&lt;property name=&quot;sortStaticImportsAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<p>To configure the check so that it matches default NetBeans formatter configuration
(tested on v8):</p>
<ul>
<li>groups of non-static imports are not defined, all imports will be sorted as a one
group</li>
<li>static imports are not separated, they will be sorted along with other imports</li>
</ul>
<source>
&lt;module name=&quot;ImportOrder&quot;&gt;
&lt;property name=&quot;option&quot; value=&quot;inflow&quot;/&gt;
&lt;/module&gt;
</source>
<p>
To configure the Check allows static imports grouped to the <b>top</b>
being sorted alphabetically:
</p>
<source>
&lt;module name=&quot;ImportOrder&quot;&gt;
&lt;property name=&quot;sortStaticImportsAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;option&quot; value=&quot;top&quot;/&gt;
&lt;/module&gt;
</source>
<source>
import static java.lang.Math.PI;
import static java.lang.Math.abs; // OK, alphabetical case sensitive ASCII order, 'P' &lt; 'a'
import static org.abego.treelayout.Configuration.AlignmentInLevel; // OK, alphabetical order
import org.abego.*;
import java.util.Set; // Wrong order for 'java.util.Set' import.
public class SomeClass { ... }
</source>
<p>
The following example shows the idea of 'useContainerOrderingForStatic' option that is
useful for Eclipse IDE users to match ordering validation.
This is how the import comparison works for static imports: we first compare
the container of the static import, container is the type enclosing the static element
being imported. When the result of the comparison is 0 (containers are equal),
we compare the fully qualified import names.
For e.g. this is what is considered to be container names for the given example:
import static HttpConstants.COLON => HttpConstants
import static HttpHeaders.addHeader => HttpHeaders
import static HttpHeaders.setHeader => HttpHeaders
import static HttpHeaders.Names.DATE => HttpHeaders.Names
According to this logic, HttpHeaders.Names should come after HttpHeaders.
</p>
<source>
&lt;module name=&quot;ImportOrder&quot;&gt;
&lt;property name=&quot;useContainerOrderingForStatic&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;ordered&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;option&quot; value=&quot;top&quot;/&gt;
&lt;property name=&quot;caseSensitive&quot; value=&quot;false&quot;/&gt;
&lt;property name=&quot;sortStaticImportsAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<source>
import static io.netty.handler.codec.http.HttpConstants.COLON;
import static io.netty.handler.codec.http.HttpHeaders.addHeader;
import static io.netty.handler.codec.http.HttpHeaders.setHeader;
import static io.netty.handler.codec.http.HttpHeaders.Names.DATE;
public class InputEclipseStaticImportsOrder { }
</source>
<source>
&lt;module name=&quot;ImportOrder&quot;&gt;
&lt;property name=&quot;useContainerOrderingForStatic&quot; value=&quot;false&quot;/&gt;
&lt;property name=&quot;ordered&quot; value=&quot;true&quot;/&gt;
&lt;property name=&quot;option&quot; value=&quot;top&quot;/&gt;
&lt;property name=&quot;caseSensitive&quot; value=&quot;false&quot;/&gt;
&lt;property name=&quot;sortStaticImportsAlphabetically&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
</source>
<source>
import static io.netty.handler.codec.http.HttpConstants.COLON;
import static io.netty.handler.codec.http.HttpHeaders.addHeader;
import static io.netty.handler.codec.http.HttpHeaders.setHeader;
import static io.netty.handler.codec.http.HttpHeaders.Names.DATE; // violation
public class InputEclipseStaticImportsOrder { }
</source>
</subsection>
<subsection name="Example of Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+ImportOrder">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Error Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.groups.separated.internally%22">
import.groups.separated.internally</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.ordering%22">
import.ordering</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.separation%22">
import.separation</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
</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="RedundantImport">
<subsection name="Description">
<p>Since Checkstyle 3.0</p>
<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 non-statically imported is from the <code>java.lang</code>
package, e.g. importing <code>java.lang.String</code>.
</li>
<li>
The class non-statically imported is from the same package as the current package.
</li>
</ul>
</subsection>
<subsection name="Examples">
<p>
To configure the check:
</p>
<source>
&lt;module name=&quot;RedundantImport&quot;/&gt;
</source>
</subsection>
<subsection name="Example of Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+RedundantImport">
Sun Style</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+RedundantImport">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Error Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.duplicate%22">
import.duplicate</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.lang%22">
import.lang</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.same%22">
import.same</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
</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="UnusedImports">
<subsection name="Description">
<p>Since Checkstyle 3.0</p>
<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 on by default, but 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>
<th>since</th>
</tr>
<tr>
<td>processJavadoc</td>
<td>whether to process Javadoc</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>true</code></td>
<td>5.4</td>
</tr>
</table>
</subsection>
<subsection name="Examples">
<p>
To configure the check:
</p>
<source>
&lt;module name=&quot;UnusedImports&quot;/&gt;
</source>
</subsection>
<subsection name="Example of Usage">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+UnusedImports">
Sun Style</a>
</li>
<li>
<a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+UnusedImports">
Checkstyle Style</a>
</li>
</ul>
</subsection>
<subsection name="Error Messages">
<ul>
<li>
<a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fimports+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22import.unused%22">
import.unused</a>
</li>
</ul>
<p>
All messages can be customized if the default message doesn't suit you.
Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
</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>
</body>
</document>