Checks that there are no import statements that use the * notation.
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.
name | description | type | default value |
---|---|---|---|
excludes | packages where star imports are allowed. Note that this property is not recursive, subpackages of excluded packages are not automatically excluded. | String Set | empty list |
allowClassImports |
whether to allow starred class imports like
import java.util.*; .
|
Boolean | false |
allowStaticMemberImports |
whether to allow starred static member imports like
import static org.junit.Assert.*;
|
Boolean | false |
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:
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.imports
Checks that there are no static import statements.
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).
name | description | type | default value |
---|---|---|---|
excludes |
Allows for certain classes via a star notation to be
excluded such as java.lang.Math.* or specific static
members to be excluded like java.lang.System.out for a variable or
java.lang.Math.random for a
method.
If you exclude a starred import on a class this automatically excludes each member individually. For example: Excluding java.lang.Math.* . will allow the
import of each static member in the Math class
individually like java.lang.Math.PI .
|
String Set | empty list |
An example of how to configure the check so that the java.lang.System.out
member and all
members from java.lang.Math
are
allowed:
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.imports
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.
Examples section contains examples that work with default formatter configurations of Eclipse, IntelliJ IDEA and NetBeans
The rule consists of:
1) STATIC group. This group sets the ordering of static imports.
2) SAME_PACKAGE(n) group. This group sets the ordering of the same package imports. Imports are considered on SAME_PACKAGE group if n first domains in package name and import name are identical. For example:
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.
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.
4) STANDARD_JAVA_PACKAGE group. This group sets ordering of standard java/javax imports.
5) SPECIAL_IMPORTS group. This group may contains some imports that have particular meaning for the user.
Use the separator '###' between rules.
To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use thirdPartyPackageRegExp and standardPackageRegExp options.
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:
Few examples to illustrate "best match":
1. patterns STANDARD_JAVA_PACKAGE = "Check", SPECIAL_IMPORTS="ImportOrderCheck" and input file:
Result: imports will be assigned to SPECIAL_IMPORTS, because matching substring length is 16. Matching substring for STANDARD_JAVA_PACKAGE is 5.
2. patterns STANDARD_JAVA_PACKAGE = "Check", SPECIAL_IMPORTS="Avoid" and file:
Result: import will be assigned to SPECIAL_IMPORTS. Matching substring length is 5 for both patterns. However, "Avoid" position is lower then "Check" position.
name | description | type | default value |
---|---|---|---|
customImportOrderRules | List of order declaration customizing by user. | string | null |
standardPackageRegExp | RegExp for STANDARD_JAVA_PACKAGE group imports. | Regular Expression | "^(java|javax)\." |
thirdPartyPackageRegExp | RegExp for THIRDPARTY_PACKAGE group imports. | Regular Expression | ".*" |
specialImportsRegExp | RegExp for SPECIAL_IMPORTS group imports. | Regular Expression | "^$" |
separateLineBetweenGroups | Force empty line separator between import groups. | Boolean | true |
sortImportsInGroupAlphabetically | Force grouping alphabetically, in ASCII sort order. | Boolean | false |
To configure the check so that it matches default Eclipse formatter configuration (tested on Kepler and Luna releases):
Notes:
To configure the check so that it matches default Eclipse formatter configuration (tested on Mars release):
To configure the check so that it matches default IntelliJ IDEA formatter configuration (tested on v14):
Note: "separated" option is disabled because IDEA default has blank line between "java" and static imports, and no blank line between "javax" and "java"
To configure the check so that it matches default NetBeans formatter configuration (tested on v8):
To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use thirdPartyPackageRegExp and standardPackageRegExp options.
Also, this check can be configured to force empty line separator between import groups. For example.
It is possible to enforce ASCII sort order of imports in groups using the following configuration:
Example of ASCII order:
To force checking imports sequence such as:
configure as follows:
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.imports
Checks for imports from a set of illegal packages. By default, the
check rejects all sun.*
packages since
programs that contain direct calls to the sun.*
packages are "not guaranteed
to work on all Java-compatible platforms". To reject other packages, set property illegalPkgs
to a list of the illegal packages.
name | description | type | default value |
---|---|---|---|
illegalPkgs | packages to reject | String Set | sun |
To configure the check:
To configure the check so that it rejects packages java.io.*
and java.sql.*
:
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.imports
Controls what can be imported in each package. Useful for ensuring that application layering rules are not violated, especially on large projects.
The DTD for a import control XML document is at http://checkstyle.sourceforge.net/dtds/import_control_1_2.dtd. It contains documentation on each of the elements and attributes.
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:
<!DOCTYPE import-control PUBLIC "-//Puppy Crawl//DTD Import Control 1.2//EN" "http://checkstyle.sourceforge.net/dtds/import_control_1_2.dtd">
name | description | type | default value |
---|---|---|---|
file | 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. | URI | null |
url | URL of the file containing the import control configuration. This property is deprecated. Please use the file property to load configurations from URLs. | URI | null |
path | 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. | Regular Expression | ".*" |
To configure the check using an import control file called "config/import-control.xml", then have the following:
To configure the check to only check the "src/main" directory using an import control file called "config/import-control.xml", then have the following:
In the example below access to package
com.puppycrawl.tools.checkstyle.checks
and its subpackages is
allowed from anywhere in com.puppycrawl.tools.checkstyle
except
from the filters
subpackage where access to all
check
's subpackages is disallowed. Two java.lang.ref
classes are allowed by virtue of one regular expression instead of listing
them in two separate allow rules (as it is done with the Files
and ClassPath
classes).
In the next example regular expressions are used to enforce a layering rule: In all
dao
packages it is not allowed to access UI layer code (ui
,
awt
, and swing
). On the other hand it is not allowed to directly
access dao
and service
layer from ui
packages. The
root package is also a regular expression that is used to handle old and new domain name
with the same rules.
For a real-life import control file look at the file called import-control.xml which is part of the Checkstyle distribution.
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 Java specs):
[\p{Letter}_$][\p{Letter}\p{Number}_$]*
or short
[\p{L}_$][\p{L}\p{N}_$]*
for a class name or package component.
([\p{L}_$][\p{L}\p{N}_$]*\.)*[\p{L}_$][\p{L}\p{N}_$]*
for a fully qualified name.
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 \.
to match an actual dot.
[^.]+
(one or more "not a dot" characters) for a class name or
package component.
com\.google\.common\.[^.]+
to match any subpackage of
com.google.common
.
com.google.common
omitting the
backslash before the dots may improve readability and may be just exact enough:
com.google.common\.[^.]+
matches not only subpackages of
com.google.common
but e.g. also of com.googleecommon
but
you may not care for that.
.*
unless you really do not care for what is matched. Often
you want to match only a certain package level instead.
Static inner classes have to be explicitly allowed when they are imported, they are not automatically allowed along with their enclosing class.
For example, to allow importing both java.util.Map
and
java.util.Map.Entry
use the following configuration:
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.imports
Checks the ordering/grouping of imports. Features are:
Examples section contains examples that work with default formatter configurations of Eclipse, IntelliJ IDEA and NetBeans
name | description | type | default value |
---|---|---|---|
option | policy on the relative order between regular imports and static imports | import order | under |
groups |
list of imports groups (every group identified either by a
common prefix string, or by a regular expression enclosed
in forward slashes (e.g. /regexp/ )
|
String Set | empty list |
ordered | whether imports within group should be sorted | Boolean | true |
separated | whether imports groups should be separated by, at least, one blank line and aren't separated internally | Boolean | false |
caseSensitive | whether string comparison should be case sensitive or not. Case sensitive sorting is in ASCII sort order | Boolean | true |
sortStaticImportsAlphabetically | whether static imports grouped by top or bottom option are sorted alphabetically or not | Boolean | false |
useContainerOrderingForStatic | whether to use container ordering (Eclipse IDE term) for static imports or not | Boolean | false |
tokens | tokens to check | subset of tokens STATIC_IMPORT. | STATIC_IMPORT. |
To configure the check so that it matches default Eclipse formatter configuration (tested on Kepler and Luna releases):
Notes:
To configure the check so that it matches default Eclipse formatter configuration (tested on Mars release):
To configure the check so that it matches default IntelliJ IDEA formatter configuration (tested on v14):
Note: "separated" option is disabled because IDEA default has blank line between "java" and static imports, and no blank line between "javax" and "java"
To configure the check so that it matches default NetBeans formatter configuration (tested on v8):
To configure the Check allows static imports grouped to the top being sorted alphabetically:
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.
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.imports
Checks for redundant import statements. An import statement is considered redundant if:
java.lang
package, e.g. importing java.lang.String
.
To configure the check:
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.imports
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:
import
java.io.*;
. Most IDE's provide very sophisticated checks
for imports that handle wild-card imports.
java.lang
package. For example importing java.lang.String
.
java.util.Date
would be
considered referenced with the Javadoc comment
{@link Date}
. The alternative to avoid introducing a
compile time dependency would be to write the Javadoc comment as
{@link java.util.Date}
.
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.
For example, in the following case the import java.awt.Component
will not be flagged as
unused:
name | description | type | default value |
---|---|---|---|
processJavadoc | whether to process Javadoc | Boolean | true |
To configure the check:
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.imports