Description

Rule Description

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.

Notes

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.

Properties

Examples

To configure the check :

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder"/>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;
import org.apache.commons.io.FileUtils;
import static java.util.Collections.*;
import java.time.*;
import static java.io.File.separator;
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
        

To configure the check so that it checks in the order (static imports,standard java packages,third party package):

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="customImportOrderRules"
        value="STATIC, STANDARD_JAVA_PACKAGE, THIRD_PARTY_PACKAGE"/>
    </module>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;
import static java.util.Collections.*;

import java.time.*;
import javax.net.*;
import static java.io.File.separator; // violation, 'wrong order'

import org.apache.commons.io.FileUtils;
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
        

To configure the check such that only java packages are included in standard java packages

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="customImportOrderRules"
        value="STATIC, STANDARD_JAVA_PACKAGE, THIRD_PARTY_PACKAGE"/>
      <property name="standardPackageRegExp" value="^java\."/>
    </module>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.util.Collections.*;
import static java.io.File.separator;

import java.time.*;
import javax.net.*; // violation, 'should be separated'

import org.apache.commons.io.FileUtils; // violation, 'Extra separation'
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
        

To configure the check to include only "com" packages as third party group imports:

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="customImportOrderRules"
        value="STATIC, STANDARD_JAVA_PACKAGE, SPECIAL_IMPORTS, THIRD_PARTY_PACKAGE"/>
      <property name="thirdPartyPackageRegExp" value="^com\."/>
    </module>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.util.Collections.*;
import static java.io.File.separator;

import java.time.*;
import javax.net.*;

import org.apache.commons.io.FileUtils; // violation, 'should be placed at the end'
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck; // violation, 'should be separated'
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
        

To configure the check to force some packages in special import group:

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="customImportOrderRules"
        value="STATIC, SPECIAL_IMPORTS, STANDARD_JAVA_PACKAGE"/>
      <property name="specialImportsRegExp" value="^org\."/>
    </module>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.util.Collections.*;
import static java.io.File.separator;

import org.apache.commons.lang3.StringUtils;

import java.time.*;
import javax.net.*;

import org.apache.commons.io.FileUtils; // violation, 'wrong order'
        

To configure the check such that empty line separator between two groups is enabled:

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="customImportOrderRules"
        value="STATIC, STANDARD_JAVA_PACKAGE, SPECIAL_IMPORTS, THIRD_PARTY_PACKAGE"/>
      <property name="specialImportsRegExp" value="^org\."/>
      <property name="thirdPartyPackageRegExp" value="^com\."/>
      <property name="separateLineBetweenGroups" value="true"/>
    </module>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.util.Collections.*;
import static java.io.File.separator;

import java.time.*;
import javax.net.*;
import org.apache.commons.io.FileUtils; // violation, 'should be separated'
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck; // violation, 'should be separated'
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
        

To configure the check such that import groups are forced to be sorted alphabetically:

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="customImportOrderRules"
        value="STATIC, STANDARD_JAVA_PACKAGE, SPECIAL_IMPORTS, THIRD_PARTY_PACKAGE"/>
      <property name="specialImportsRegExp" value="^org\."/>
      <property name="thirdPartyPackageRegExp" value="^com\."/>
      <property name="separateLineBetweenGroups" value="false"/>
      <property name="sortImportsInGroupAlphabetically" value="true"/>
    </module>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.util.Collections.*;
import static java.io.File.separator; // violation, 'Wrong lexicographical'

import java.time.*;
import javax.net.*;
import org.apache.commons.io.FileUtils;
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
        

To configure the check so that it matches default Eclipse formatter configuration (tested on Kepler and Luna releases):

• group of static imports is on the top
• groups of non-static imports: "java" and "javax" packages first, then "org" and then all other imports
• imports will be sorted in the groups
• groups are separated by single blank line

Notes:

• "com" package is not mentioned on configuration, because it is ignored by Eclipse Kepler and Luna (looks like Eclipse defect)
• configuration below doesn't work in all 100% cases due to inconsistent behavior prior to Mars release, but covers most scenarios

<module name="Checker">
  <module name="TreeWalker">
    <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>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.util.Collections.*;
import static java.io.File.separator; // violation, 'Wrong lexicographical'

import java.time.*;
import javax.net.*;
import org.apache.commons.io.FileUtils; // violation, 'should be separated'

import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
        

To configure the check so that it matches default Eclipse formatter configuration (tested on Mars release):

• group of static imports is on the top
• groups of non-static imports: "java" and "javax" packages first, then "org" and "com", then all other imports as one group
• imports will be sorted in the groups
• groups are separated by one blank line

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="customImportOrderRules"
        value="STATIC, STANDARD_JAVA_PACKAGE, SPECIAL_IMPORTS, THIRD_PARTY_PACKAGE"/>
      <property name="specialImportsRegExp" value="^org\."/>
      <property name="thirdPartyPackageRegExp" value="^com\."/>
      <property name="sortImportsInGroupAlphabetically" value="true"/>
      <property name="separateLineBetweenGroups" value="true"/>
    </module>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.io.File.separator;
import static java.util.Collections.*;

import java.time.*;
import javax.net.*;

import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck; // violation, 'wrong order'
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck; // violation, 'wrong order'

import org.apache.commons.io.FileUtils;
        

To configure the check so that it matches default IntelliJ IDEA formatter configuration (tested on v14):

• group of static imports is on the bottom
• groups of non-static imports: all imports except of "javax" and "java", then "javax" and "java"
• imports will be sorted in the groups
• groups are separated by one blank line

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="Checker">
  <module name="TreeWalker">
    <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>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.io.File.separator;
import static java.util.Collections.*;

import java.time.*; // violation, should be in standard package group

import javax.net.*; // violation, should be in special import group

import org.apache.commons.io.FileUtils; // violation, should be in THIRD PARTY PACKAGE GROUP

import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck; // violation, 'wrong order'
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck; // violation, 'wrong order'
        

To configure the check so that it matches default NetBeans formatter configuration (tested on v8):

• groups of non-static imports are not defined, all imports will be sorted as a one group
• static imports are not separated, they will be sorted along with other imports

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder"/>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.io.File.separator;
import static java.util.Collections.*;
import java.time.*;
import javax.net.*;
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;

import org.apache.commons.io.FileUtils; // violation, 'Extra separation'
        

To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use thirdPartyPackageRegExp and standardPackageRegExp options.

<module name="Checker">
  <module name="TreeWalker">
    <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>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.io.File.separator;
import static java.util.Collections.*;
import java.time.*; // violation, 'wrong order'
import javax.net.*; // violation, 'wrong order'

import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;

import org.apache.commons.io.FileUtils;
        

Also, this check can be configured to force empty line separator between import groups. For example.

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="separateLineBetweenGroups" value="true"/>
    </module>
  </module>
</module>
        

Example:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import static java.io.File.separator;
import static java.util.Collections.*;
import java.time.*;
import javax.net.*;
import com.puppycrawl.tools.checkstyle.checks.imports.CustomImportOrderCheck;
import com.puppycrawl.tools.checkstyle.checks.imports.ImportOrderCheck;
import org.apache.commons.io.FileUtils;
        

It is possible to enforce ASCII sort order of imports in groups using the following configuration:

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="sortImportsInGroupAlphabetically" value="true"/>
    </module>
  </module>
</module>
        

Example of ASCII order:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import java.awt.Dialog;
import java.awt.Window;
import java.awt.color.ColorSpace;
import java.awt.Frame; // violation, in ASCII order all uppercase comes before lowercase letters
        

To force checking imports sequence such as:

package com.puppycrawl.tools.checkstyle.checks.imports.customimportorder;

import com.google.common.annotations.GwtCompatible;
import com.google.common.annotations.Beta;
import com.google.common.annotations.VisibleForTesting;
import org.apache.commons.io.FileUtils;

import static java.util.Collections.emptyList;

import com.google.common.annotations.GwtCompatible; // violation, 'wrong order'

import java.lang.String;
        

configure as follows:

<module name="Checker">
  <module name="TreeWalker">
    <module name="CustomImportOrder">
      <property name="customImportOrderRules"
        value="SAME_PACKAGE(3), THIRD_PARTY_PACKAGE, STATIC, SPECIAL_IMPORTS"/>
      <property name="specialImportsRegExp" value="^java\.lang\.String$"/>
    </module>
  </module>
</module>
        

Example of Usage

• Google Style
• Checkstyle Style

Violation Messages

• 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

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.imports

Parent Module

TreeWalker