Package com.puppycrawl.tools.checkstyle.checks.imports

Class CustomImportOrderCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable
    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 contain some imports that have particular meaning for the user.

    Rules are configured as a comma-separated ordered list.

    Note: '###' group separator is deprecated (in favor of a comma-separated list), but is currently supported for backward compatibility.

    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:

    1. STATIC has top priority
    2. SAME_PACKAGE has second priority
    3. 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.
    4. THIRD_PARTY has the least priority

    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 than "Check" position.

    • Property customImportOrderRules - Specify ordered list of import groups. Type is java.lang.String[]. Default value is "".
    • Property separateLineBetweenGroups - Force empty line separator between import groups. Type is boolean. Default value is true.
    • Property sortImportsInGroupAlphabetically - Force grouping alphabetically, in ASCII sort order. Type is boolean. Default value is false.
    • Property specialImportsRegExp - Specify RegExp for SPECIAL_IMPORTS group imports. Type is java.util.regex.Pattern. Default value is "^$".
    • Property standardPackageRegExp - Specify RegExp for STANDARD_JAVA_PACKAGE group imports. Type is java.util.regex.Pattern. Default value is "^(java|javax)\.".
    • Property thirdPartyPackageRegExp - Specify RegExp for THIRD_PARTY_PACKAGE group imports. Type is java.util.regex.Pattern. Default value is ".*".

    Parent is com.puppycrawl.tools.checkstyle.TreeWalker

    Violation Message Keys:

    • custom.import.order
    • custom.import.order.lex
    • custom.import.order.line.separator
    • custom.import.order.nonGroup.expected
    • custom.import.order.nonGroup.import
    • custom.import.order.separated.internally
    Since:
    5.8