public class CustomImportOrderCheck extends AbstractCheck
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.
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.
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
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. By default 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.
NOTE!
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:
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
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:
import com.puppycrawl.tools.checkstyle.checks.imports.AvoidStarImportCheck;
Result: import will be assigned to SPECIAL_IMPORTS. Matching substring length is 5 for both patterns. However, "Avoid" position is lower then "Check" position.
Properties:
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 THIRD_PARTY_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 |
For example:
To configure the check so that it matches default Eclipse formatter configuration (tested on Kepler, Luna and Mars):
<module name="CustomImportOrder"> <property name="customImportOrderRules" value="STATIC###STANDARD_JAVA_PACKAGE###SPECIAL_IMPORTS"/> <property name="specialImportsRegExp" value="org"/> <property name="sortImportsInGroupAlphabetically" value="true"/> <property name="separateLineBetweenGroups" value="true"/> </module>
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"
<module name="CustomImportOrder"> <property name="customImportOrderRules" value="THIRD_PARTY_PACKAGE###SPECIAL_IMPORTS###STANDARD_JAVA_PACKAGE ###STATIC"/> <property name="specialImportsRegExp" value="^javax\."/> <property name="standardPackageRegExp" value="^java\."/> <property name="sortImportsInGroupAlphabetically" value="true"/> <property name="separateLineBetweenGroups" value="false"/> </module>
To configure the check so that it matches default NetBeans formatter configuration (tested on v8):
<module name="CustomImportOrder"/>
To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use thirdPartyPackageRegExp and standardPackageRegExp options.
<module name="CustomImportOrder"> <property name="customImportOrderRules" value="STATIC###SAME_PACKAGE(3)###THIRD_PARTY_PACKAGE###STANDARD_JAVA_PACKAGE"/> <property name="thirdPartyPackageRegExp" value="com|org"/> <property name="standardPackageRegExp" value="^(java|javax)\."/> </module>
Also, this check can be configured to force empty line separator between import groups. For example
<module name="CustomImportOrder"> <property name="separateLineBetweenGroups" value="true"/> </module>
It is possible to enforce ASCII sort order of imports in groups using the following configuration:
<module name="CustomImportOrder"> <property name="sortImportsInGroupAlphabetically" value="true"/> </module>
Example of ASCII order:
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
To force checking imports sequence such as:
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.*;
configure as follows:
<module name="CustomImportOrder"> <property name="customImportOrderRules" value="SAME_PACKAGE(3)###THIRD_PARTY_PACKAGE###STATIC###SPECIAL_IMPORTS"/> <property name="specialImportsRegExp" value="android.*"/> </module>
Modifier and Type | Class and Description |
---|---|
private static class |
CustomImportOrderCheck.ImportDetails
Contains import attributes as line number, import full path, import
group.
|
private static class |
CustomImportOrderCheck.RuleMatchForImport
Contains matching attributes assisting in definition of "best matching"
group for import.
|
Modifier and Type | Field and Description |
---|---|
private java.util.List<java.lang.String> |
customImportOrderRules
List of order declaration customizing by user.
|
private static java.util.regex.Pattern |
GROUP_SEPARATOR_PATTERN
Pattern used to separate groups of imports.
|
private java.util.List<CustomImportOrderCheck.ImportDetails> |
importToGroupList
Contains objects with import attributes.
|
static java.lang.String |
MSG_LEX
A key is pointing to the warning message text in "messages.properties"
file.
|
static java.lang.String |
MSG_LINE_SEPARATOR
A key is pointing to the warning message text in "messages.properties"
file.
|
static java.lang.String |
MSG_NONGROUP_EXPECTED
A key is pointing to the warning message text in "messages.properties"
file.
|
static java.lang.String |
MSG_NONGROUP_IMPORT
A key is pointing to the warning message text in "messages.properties"
file.
|
static java.lang.String |
MSG_ORDER
A key is pointing to the warning message text in "messages.properties"
file.
|
private static java.lang.String |
NON_GROUP_RULE_GROUP
NON_GROUP group name.
|
static java.lang.String |
SAME_PACKAGE_RULE_GROUP
SAME_PACKAGE group name.
|
private java.lang.String |
samePackageDomainsRegExp
RegExp for SAME_PACKAGE group imports.
|
private int |
samePackageMatchingDepth
Number of first domains for SAME_PACKAGE group.
|
private boolean |
separateLineBetweenGroups
Force empty line separator between import groups.
|
private boolean |
sortImportsInGroupAlphabetically
Force grouping alphabetically, in ASCII order.
|
static java.lang.String |
SPECIAL_IMPORTS_RULE_GROUP
SPECIAL_IMPORTS group name.
|
private java.util.regex.Pattern |
specialImportsRegExp
RegExp for SPECIAL_IMPORTS group imports.
|
static java.lang.String |
STANDARD_JAVA_PACKAGE_RULE_GROUP
STANDARD_JAVA_PACKAGE group name.
|
private java.util.regex.Pattern |
standardPackageRegExp
RegExp for STANDARD_JAVA_PACKAGE group imports.
|
static java.lang.String |
STATIC_RULE_GROUP
STATIC group name.
|
static java.lang.String |
THIRD_PARTY_PACKAGE_RULE_GROUP
THIRD_PARTY_PACKAGE group name.
|
private java.util.regex.Pattern |
thirdPartyPackageRegExp
RegExp for THIRD_PARTY_PACKAGE group imports.
|
Constructor and Description |
---|
CustomImportOrderCheck() |
Modifier and Type | Method and Description |
---|---|
private void |
addRulesToList(java.lang.String ruleStr)
Parses ordering rule and adds it to the list with rules.
|
void |
beginTree(DetailAST rootAST)
Called before the starting to process a tree.
|
private static int |
compareImports(java.lang.String import1,
java.lang.String import2)
Checks compare two import paths.
|
private static java.lang.String |
createSamePackageRegexp(int firstPackageDomainsCount,
DetailAST packageNode)
Creates samePackageDomainsRegExp of the first package domains.
|
private static CustomImportOrderCheck.RuleMatchForImport |
findBetterPatternMatch(java.lang.String importPath,
java.lang.String group,
java.util.regex.Pattern regExp,
CustomImportOrderCheck.RuleMatchForImport currentBestMatch)
Tries to find better matching regular expression:
longer matching substring wins; in case of the same length,
lower position of matching substring wins.
|
private void |
finishImportList()
Examine the order of all the imports and log any violations.
|
void |
finishTree(DetailAST rootAST)
Called after finished processing a tree.
|
int[] |
getAcceptableTokens()
The configurable token set.
|
private int |
getCountOfEmptyLinesBefore(int lineNo)
Counts empty lines before given.
|
int[] |
getDefaultTokens()
Returns the default token a check is interested in.
|
private static java.lang.String |
getFirstDomainsFromIdent(int firstPackageDomainsCount,
java.lang.String packageFullPath)
Extracts defined amount of domains from the left side of package/import identifier.
|
private static java.lang.String |
getFullImportIdent(DetailAST token)
Forms import full path.
|
private java.lang.String |
getImportGroup(boolean isStatic,
java.lang.String importPath)
Get import valid group.
|
private java.lang.String |
getNextImportGroup(int currentGroupNumber)
Get next import group.
|
int[] |
getRequiredTokens()
The tokens that this check must be registered for.
|
private boolean |
hasAnyImportInCurrentGroup(java.lang.String currentGroup)
Checks if current group contains any import.
|
private void |
logWrongImportGroupOrder(int currentImportLine,
java.lang.String importGroup,
java.lang.String currentGroupNumber,
java.lang.String fullImportIdent)
Log wrong import group order.
|
void |
setCustomImportOrderRules(java.lang.String inputCustomImportOrder)
Sets a custom import order from the rules in the string format specified
by user.
|
void |
setSeparateLineBetweenGroups(boolean value)
Sets separateLineBetweenGroups specified by user.
|
void |
setSortImportsInGroupAlphabetically(boolean value)
Sets sortImportsInGroupAlphabetically specified by user.
|
void |
setSpecialImportsRegExp(java.util.regex.Pattern regexp)
Sets specialImportsRegExp specified by user.
|
void |
setStandardPackageRegExp(java.util.regex.Pattern regexp)
Sets standardRegExp specified by user.
|
void |
setThirdPartyPackageRegExp(java.util.regex.Pattern regexp)
Sets thirdPartyRegExp specified by user.
|
void |
visitToken(DetailAST ast)
Called to process a token.
|
destroy, getClassLoader, getFileContents, getLine, getLines, getTabWidth, getTokenNames, init, isCommentNodesRequired, leaveToken, log, log, setClassLoader, setFileContents, setMessages, setTabWidth, setTokens
getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, log, setId, setSeverity
configure, contextualize, finishLocalSetup, getConfiguration, setupChild
public static final java.lang.String MSG_LINE_SEPARATOR
public static final java.lang.String MSG_LEX
public static final java.lang.String MSG_NONGROUP_IMPORT
public static final java.lang.String MSG_NONGROUP_EXPECTED
public static final java.lang.String MSG_ORDER
public static final java.lang.String STATIC_RULE_GROUP
public static final java.lang.String SAME_PACKAGE_RULE_GROUP
public static final java.lang.String THIRD_PARTY_PACKAGE_RULE_GROUP
public static final java.lang.String STANDARD_JAVA_PACKAGE_RULE_GROUP
public static final java.lang.String SPECIAL_IMPORTS_RULE_GROUP
private static final java.lang.String NON_GROUP_RULE_GROUP
private static final java.util.regex.Pattern GROUP_SEPARATOR_PATTERN
private final java.util.List<java.lang.String> customImportOrderRules
private final java.util.List<CustomImportOrderCheck.ImportDetails> importToGroupList
private java.lang.String samePackageDomainsRegExp
private java.util.regex.Pattern standardPackageRegExp
private java.util.regex.Pattern thirdPartyPackageRegExp
private java.util.regex.Pattern specialImportsRegExp
private boolean separateLineBetweenGroups
private boolean sortImportsInGroupAlphabetically
private int samePackageMatchingDepth
public final void setStandardPackageRegExp(java.util.regex.Pattern regexp)
regexp
- user value.public final void setThirdPartyPackageRegExp(java.util.regex.Pattern regexp)
regexp
- user value.public final void setSpecialImportsRegExp(java.util.regex.Pattern regexp)
regexp
- user value.public final void setSeparateLineBetweenGroups(boolean value)
value
- user value.public final void setSortImportsInGroupAlphabetically(boolean value)
value
- user value.public final void setCustomImportOrderRules(java.lang.String inputCustomImportOrder)
inputCustomImportOrder
- user value.public int[] getDefaultTokens()
AbstractCheck
getDefaultTokens
in class AbstractCheck
TokenTypes
public int[] getAcceptableTokens()
AbstractCheck
getAcceptableTokens
in class AbstractCheck
TokenTypes
public int[] getRequiredTokens()
AbstractCheck
getRequiredTokens
in class AbstractCheck
TokenTypes
public void beginTree(DetailAST rootAST)
AbstractCheck
beginTree
in class AbstractCheck
rootAST
- the root of the treepublic void visitToken(DetailAST ast)
AbstractCheck
visitToken
in class AbstractCheck
ast
- the token to processpublic void finishTree(DetailAST rootAST)
AbstractCheck
finishTree
in class AbstractCheck
rootAST
- the root of the treeprivate void finishImportList()
private void logWrongImportGroupOrder(int currentImportLine, java.lang.String importGroup, java.lang.String currentGroupNumber, java.lang.String fullImportIdent)
currentImportLine
- line number of current import current import.importGroup
- import group.currentGroupNumber
- current group number we are checking.fullImportIdent
- full import name.private java.lang.String getNextImportGroup(int currentGroupNumber)
currentGroupNumber
- current group number.private boolean hasAnyImportInCurrentGroup(java.lang.String currentGroup)
currentGroup
- current group.private java.lang.String getImportGroup(boolean isStatic, java.lang.String importPath)
isStatic
- is static import.importPath
- full import path.private static CustomImportOrderCheck.RuleMatchForImport findBetterPatternMatch(java.lang.String importPath, java.lang.String group, java.util.regex.Pattern regExp, CustomImportOrderCheck.RuleMatchForImport currentBestMatch)
importPath
- Full import identifiergroup
- Import group we are trying to assign the importregExp
- Regular expression for import groupcurrentBestMatch
- object with currently best matchprivate static int compareImports(java.lang.String import1, java.lang.String import2)
import1
- current import.import2
- previous import.private int getCountOfEmptyLinesBefore(int lineNo)
lineNo
- Line number of current import.private static java.lang.String getFullImportIdent(DetailAST token)
token
- current token.private void addRulesToList(java.lang.String ruleStr)
ruleStr
- String with rule.private static java.lang.String createSamePackageRegexp(int firstPackageDomainsCount, DetailAST packageNode)
firstPackageDomainsCount
- number of first package domains.packageNode
- package node.private static java.lang.String getFirstDomainsFromIdent(int firstPackageDomainsCount, java.lang.String packageFullPath)
firstPackageDomainsCount
- number of first package domains.packageFullPath
- full identifier containing path to package or imported object.