<?xml version="1.0" encoding="ISO-8859-1"?>

<document xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>Imports</title>
    <author>Checkstyle Development Team</author>
  </properties>

  <body>
    <section name="AvoidStarImport">
      <subsection name="Description">
        <p>
          Checks that there are no import statements that use the * notation.
        </p>

        <p>
          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.
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>excludes</td>
            <td>
              packages where star imports are allowed. Note that this property
              is not recursive, subpackages of excluded packages are not
              automatically excluded.
            </td>
            <td><a href="property_types.html#stringSet">list of strings</a></td>
            <td><code>empty list</code></td>
          </tr>
          <tr>
            <td>allowClassImports</td>
            <td>
              whether to allow starred class imports like
              <code>import java.util.*;</code>.
            </td>
            <td><a href="property_types.html#Boolean">Boolean</a></td>
            <td><code>false</code></td>
          </tr>
          <tr>
            <td>allowStaticMemberImports</td>
            <td>
              whether to allow starred static member imports like
              <code>import static org.junit.Assert.*;</code>
            </td>
            <td><a href="property_types.html#Boolean">Boolean</a></td>
            <td><code>false</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Example">
        <p>
          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:
        </p>

        <source>
&lt;module name="AvoidStarImport"&gt;
   &lt;property name="excludes" value="java.io,java.net,java.lang.Math"/&gt;
   &lt;property name="allowClassImports" value="false"/&gt;
   &lt;property name="allowStaticMemberImports" value="false"/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p> com.puppycrawl.tools.checkstyle.checks.imports </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="AvoidStaticImport">
      <subsection name="Description">
        <p>
          Checks that there are no static import statements.
        </p>

        <p>
          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).
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>excludes</td>
            <td>
              Allows for certain classes via a star notation to be
              excluded such as <code>java.lang.Math.*</code> or specific static
              members to be excluded like <code>java.lang.System.out</code> for a variable or
              <code>java.lang.Math.random</code> for a
              method.
              <br/>
              If you exclude a starred import on a class this automatically
              excludes each member individually.
              <br/>
              For example: Excluding <code>java.lang.Math.*</code>. will allow the
              import of each static member in the Math class
              individually like <code>java.lang.Math.PI</code>.
            </td>
            <td><a href="property_types.html#stringSet">list of strings</a></td>
            <td><code>empty list</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Example">
        <p>
          An example of how to configure the check so that the <code>java.lang.System.out</code> member and all
          members from <code>java.lang.Math</code> are
          allowed:
        </p>

        <source>
         &lt;module name="AvoidStaticImport"&gt;
           &lt;property name="excludes" value="java.lang.System.out,java.lang.Math.*"/&gt;
         &lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p> com.puppycrawl.tools.checkstyle.checks.imports </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="IllegalImport">
      <subsection name="Description">
        <p>
          Checks for imports from a set of illegal packages. By default, the
          check rejects all <code>sun.*</code> packages since
          programs that contain direct calls to the <code>sun.*</code> packages are <a
          href="http://java.sun.com/products/jdk/faq/faq-sun-packages.html">not
          100% Pure Java</a>. To reject other packages, set property <code> illegalPkgs</code> to a list of the illegal packages.
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>illegalPkgs</td>
            <td>packages to reject</td>
            <td><a href="property_types.html#stringSet">list of strings</a></td>
            <td><code>sun</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p>
          To configure the check:
        </p>
        <source>
&lt;module name=&quot;IllegalImport&quot;/&gt;
        </source>

        <p>
          To configure the check so that it rejects packages <code>java.io.*</code> and <code>java.sql.*</code>:
        </p>
        <source>
&lt;module name=&quot;IllegalImport&quot;&gt;
    &lt;property name=&quot;illegalPkgs&quot; value=&quot;java.io, java.sql&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.imports
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="RedundantImport">
      <subsection name="Description">
        <p>
          Checks for redundant import statements. An import statement is
          considered redundant if:
        </p>

        <ul>
          <li>
            It is a duplicate of another import. This is, when a class is
            imported more than once.
          </li>
          <li>
            The class imported is from the <code>java.lang</code>
            package, e.g.  importing <code>java.lang.String</code>.
          </li>
          <li>
            The class imported is from the same package.
          </li>
        </ul>
      </subsection>

      <subsection name="Example">
        <p>
          To configure the check:
        </p>
        <source>
&lt;module name=&quot;RedundantImport&quot;/&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.imports
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="UnusedImports">
      <subsection name="Description">
        <p>
          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:
        </p>

        <ul>
          <li>
            It is not referenced in the file. The algorithm does not support
            wild-card imports like <code>import
            java.io.*;</code>. Most IDE's provide very sophisticated checks
            for imports that handle wild-card imports.
          </li>

          <li>
            It is a duplicate of another import. This is when a class is
            imported more than once.
          </li>

          <li>
            The class imported is from the <code>java.lang</code>
            package. For example importing <code>java.lang.String</code>.
          </li>

          <li>
            The class imported is from the same package.
          </li>
          <li>
            <b>Optionally:</b> 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 <code>java.util.Date</code> would be
            considered referenced with the Javadoc comment
            <code>{@link Date}</code>. The alternative to avoid introducing a
            compile time dependency would be to write the Javadoc comment as
            <code>{@link java.util.Date}</code>.
          </li>
        </ul>
        <p>
          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.
        </p>
        <p>
          For example, in the following case the import <code>java.awt.Component</code> will not be flagged as
          unused:
        </p>
        <source>
import java.awt.Component;
class FooBar {
    private Object Component; // IMHO bad practise
    ...
}
        </source>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>processJavadoc</td>
            <td>whether to process Javadoc</td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Example">
        <p>
          To configure the check:
        </p>
        <source>
&lt;module name=&quot;UnusedImports&quot;/&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.imports
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="ImportOrder">
      <subsection name="Description">
        <p>Checks the ordering/grouping of imports. Features are:</p>
        <ul>
          <li>groups imports: ensures that groups of imports come in a
          specific order (e.g., java. comes first, javax. comes second,
          then everything else)</li>
          <li>adds a separation between groups : ensures that a blank
          line sit between each group</li>
          <li>sorts imports inside each group: ensures that imports
          within each group are in lexicographic order</li>
          <li>sorts according to case: ensures that the comparison
          between imports is case sensitive</li>
          <li>groups static imports: ensures the relative order between
          regular imports and static imports (see
          <a href="property_types.html#importOrder">import orders</a>)</li>
         </ul>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>option</td>
            <td>policy on the relative order between regular imports and static imports</td>
            <td><a href="property_types.html#importOrder">import order</a></td>
            <td><code>under</code></td>
          </tr>
          <tr>
            <td>groups</td>
            <td>
              list of imports groups (every group identified either by a
              common prefix string, or by a regular expression enclosed
              in forward slashes (e.g. <code>/regexp/</code>)
            </td>
            <td><a href="property_types.html#stringSet">list of strings</a></td>
            <td><code>empty list</code></td>
          </tr>
          <tr>
            <td>ordered</td>
            <td>whether imports within group should be sorted</td>
            <td><a href="property_types.html#boolean">Boolean</a></td>
            <td>true</td>
          </tr>
          <tr>
            <td>separated</td>
            <td>
              whether imports groups should be separated by, at least, one
              blank line
            </td>
            <td><a href="property_types.html#boolean">Boolean</a></td>
            <td>false</td>
          </tr>
          <tr>
            <td>caseSensitive</td>
            <td>whether string comparision should be case sensitive or not</td>
            <td><a href="property_types.html#boolean">Boolean</a></td>
            <td>true</td>
          </tr>
        </table>
      </subsection>

      <subsection name="Example">
        <p>To configure the check so that it requires that:</p>
        <ul>
          <li>&quot;java&quot; and &quot;javax&quot; packages together first, then &quot;org&quot; and then all other imports</li>
          <li>imports will be sorted in the groups</li>
          <li>groups are separated by, at least, one blank line</li>
          <li>static imports are above each local groups</li>
        </ul>

        <source>
&lt;module name=&quot;ImportOrder&quot;>
    &lt;property name=&quot;groups&quot; value=&quot;/^javax?\./,org&quot;/>
    &lt;property name=&quot;ordered&quot; value=&quot;true&quot;/>
    &lt;property name=&quot;separated&quot; value=&quot;true&quot;/>
    &lt;property name=&quot;option&quot; value=&quot;above&quot;/>
&lt;/module>
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.imports
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="ImportControl">
      <subsection name="Description">
        <p>
          Controls what can be imported in each package. Useful for
          ensuring that application layering rules are not violated,
          especially on large projects.
        </p>

        <p>
          The DTD for a import control XML document is at <a
          href="http://www.puppycrawl.com/dtds/import_control_1_1.dtd">http://www.puppycrawl.com/dtds/import_control_1_1.dtd</a>. It
          contains documentation on each of the elements and attributes.
        </p>

        <p>
          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:
        </p>

        <pre>
&lt;!DOCTYPE import-control PUBLIC
    &quot;-//Puppy Crawl//DTD Import Control 1.1//EN&quot;
    &quot;http://www.puppycrawl.com/dtds/import_control_1_1.dtd&quot;&gt;
        </pre>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>file</td>
            <td>
              name of the file containing the import control configuration.
            </td>
            <td><a href="property_types.html#string">string</a></td>
            <td><code>null</code></td>
          </tr>
          <tr>
            <td>url</td>
            <td>
              url of the file containing the import control configuration.
            </td>
            <td><a href="property_types.html#string">string</a></td>
            <td><code>null</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Example">
        <p>
          To configure the check using a import control file called
          &quot;import-control.xml&quot;, then have the following:
        </p>

        <source>
&lt;module name=&quot;ImportControl&quot;>
    &lt;property name=&quot;file&quot; value=&quot;import-control.xml&quot;/>
&lt;/module>
        </source>

        <p>
          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.
        </p>

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

        <p>
          For an example import control file, look at the file called <a
          href="http://checkstyle.svn.sourceforge.net/viewvc/checkstyle/trunk/checkstyle/import-control.xml?view=markup">import-control.xml</a>
          which is part of the Checkstyle distribution.
        </p>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.imports
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>
  </body>
</document>
