Checkstyle 5.5

##### About

- Checkstyle
- Release Notes

##### Documentation

- Configuration
  - Property Types
- Running
  - Ant Task
  - Command Line
- Available Checks
- Standard Checks
  - Annotations
  - Block Checks
  - Class Design
  - Coding
  - Duplicate Code
  - Headers
  - Imports
  - Javadoc Comments
  - Metrics
  - Miscellaneous
  - Modifiers
  - Naming Conventions
  - Regexp
  - Size Violations
  - Whitespace
- Extending Checkstyle
  - Writing checks
  - Writing filters
  - Writing listeners

##### Developers

- Javadoc
- Project Page
- Contributing

##### Project Documentation

- Project Information
- Project Reports

## AvoidStarImport

### Description

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.

### Properties

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. | list of strings | `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`

### Example

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:

    <module name="AvoidStarImport">
       <property name="excludes" value="java.io,java.net,java.lang.Math"/>
       <property name="allowClassImports" value="false"/>
       <property name="allowStaticMemberImports" value="false"/>
    </module>

### Package

com.puppycrawl.tools.checkstyle.checks.imports

### Parent Module

TreeWalker

## AvoidStaticImport

### Description

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).

### Properties

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`.

list of strings

`empty list`

### Example

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:

             <module name="AvoidStaticImport">
               <property name="excludes" value="java.lang.System.out,java.lang.Math.*"/>
             </module>

### Package

com.puppycrawl.tools.checkstyle.checks.imports

### Parent Module

TreeWalker

## IllegalImport

### Description

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 100% Pure Java. To reject other packages, set property `illegalPkgs` to a list of the illegal packages.

### Properties

name | description | type | default value
--- | --- | --- | ---
illegalPkgs | packages to reject | list of strings | `sun`

### Examples

To configure the check:

    <module name="IllegalImport"/>

To configure the check so that it rejects packages `java.io.*` and `java.sql.*`:

    <module name="IllegalImport">
        <property name="illegalPkgs" value="java.io, java.sql"/>
    </module>

### Package

com.puppycrawl.tools.checkstyle.checks.imports

### Parent Module

TreeWalker

## RedundantImport

### Description

Checks for redundant import statements. An import statement is considered redundant if:

- It is a duplicate of another import. This is, when a class is imported more than once.
- The class imported is from the `java.lang` package, e.g. importing `java.lang.String`.
- The class imported is from the same package.

### Example

To configure the check:

    <module name="RedundantImport"/>

### Package

com.puppycrawl.tools.checkstyle.checks.imports

### Parent Module

TreeWalker

## UnusedImports

### Description

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:

- It is not referenced in the file. The algorithm does not support wild-card imports like `import java.io.*;`. Most IDE's provide very sophisticated checks for imports that handle wild-card imports.
- It is a duplicate of another import. This is when a class is imported more than once.
- The class imported is from the `java.lang` package. For example importing `java.lang.String`.
- The class imported is from the same package.
- Optionally: it is referenced in Javadoc comments. This check is off by default, as it is considered bad practice to introduce a compile time dependency for documentation purposes only. As an example, the import `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:

    import java.awt.Component;
    class FooBar {
        private Object Component; // IMHO bad practise
        ...
    }

### Properties

name | description | type | default value
--- | --- | --- | ---
processJavadoc | whether to process Javadoc | boolean | `false`

### Example

To configure the check:

    <module name="UnusedImports"/>

### Package

com.puppycrawl.tools.checkstyle.checks.imports

### Parent Module

TreeWalker

## ImportOrder

### Description

Checks the ordering/grouping of imports. Features are:

- groups imports: ensures that groups of imports come in a specific order (e.g., java. comes first, javax. comes second, then everything else)
- adds a separation between groups : ensures that a blank line sit between each group
- sorts imports inside each group: ensures that imports within each group are in lexicographic order
- sorts according to case: ensures that the comparison between imports is case sensitive
- groups static imports: ensures the relative order between regular imports and static imports (see import orders)

### Properties

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/`) | list of strings | `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 | Boolean | false
caseSensitive | whether string comparision should be case sensitive or not | Boolean | true

### Example

To configure the check so that it requires that:

- "java" and "javax" packages together first, then "org" and then all other imports
- imports will be sorted in the groups
- groups are separated by, at least, one blank line
- static imports are above each local groups

    <module name="ImportOrder">
        <property name="groups" value="/^javax?\./,org"/>
        <property name="ordered" value="true"/>
        <property name="separated" value="true"/>
        <property name="option" value="above"/>
    </module>

### Package

com.puppycrawl.tools.checkstyle.checks.imports

### Parent Module

TreeWalker

## ImportControl

### Description

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://www.puppycrawl.com/dtds/import_control_1_1.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.1//EN"
        "http://www.puppycrawl.com/dtds/import_control_1_1.dtd">

### Properties

name | description | type | default value
--- | --- | --- | ---
file | name of the file containing the import control configuration. | string | `null`
url | url of the file containing the import control configuration. | string | `null`

### Example

To configure the check using a import control file called "import-control.xml", then have the following:

    <module name="ImportControl">
        <property name="file" value="import-control.xml"/>
    </module>

In the example below, all classes beginning with an I in the package java.awt are allowed. In the package java.io only the classes File and InputStream are allowed.

    <import-control pkg="com.puppycrawl.tools.checkstyle">
        <allow class="java\.awt\.I.*" regex="true"/>
        <allow class="java\.io\.(File|InputStream)" local-only="true"
            regex="true"/>
    </import-control>

For an example import control file, look at the file called import-control.xml which is part of the Checkstyle distribution.

### Package

com.puppycrawl.tools.checkstyle.checks.imports

### Parent Module

TreeWalker