Cleans the import lists of a Java source file tree.

The source directory will be recursively scanned for Java source files to clean. The import sections of the Java files are cleaned up and formatted according to the supplied format. Cleaning here means that all unneeded imports are removed. The Java files must be javac-compileable with the supplied classpath. All Java files must be changeable, otherwise the file will be skipped with a warning.

It is possible to refine the set of files that are being compiled/copied. This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. With the includes or includesfile attribute you specify the files you want to have included by using patterns. The exclude or excludesfile attribute is used to specify the files you want to have excluded. This is also done with patterns. And finally with the defaultexcludes attribute, you can specify whether you want to use default exclusions or not. See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.


Attribute Description Required
srcdir location of the java files. Yes, unless nested <src> elements are present.
includes comma-separated list of patterns of files that must beincluded; all files are included when omitted. No
includesfile the name of a file that contains include patterns. No
excludes comma-separated list of patterns of files that must be excluded; no files (except default excludes) are excluded when omitted. No
excludesfile the name of a file that contains exclude patterns. No
defaultexcludes indicates whether default excludes should be used (yes | no); default excludes are used when omitted. No
classpath the classpath to use. No
classpathref the classpath to use, given as a reference to a PATH defined elsewhere. No
encoding encoding of source files. No
cleanformat The format of the generated import block (see below) No
source Value of the -source command line switch for the javac compiler, legal values are "1.3" and "1.4" - by default, no -source argument will be used at all. No

Parameters specified as nested elements

This task forms an implicit FileSet and supports all attributes of <fileset> (dir becomes srcdir) as well as the nested <include>, <exclude> and <patternset> elements.

<src>, <classpath>

CleanImport's srcdir and classpath attributes are path-like structures and can also be set via nested <src> and <classpath> elements, respectively.

Import formatting specification

The format of the import block can be specified using the nested formatting specification. The nested <cleanformat> element can have any number of <text>, <import> and <options> elements.


The <text> and <import> elements can have embedded text as well as a comment attribute. The embedded text is inserted as is, the comment attribute's string is preceded by '//' before it is inserted into the source file. The text and/or comment is inserted for every element when encountered.

Text elements

The <text> elements are used to insert text into the import block:
    <text comment="Import section"/>
    <text>This will not compile</text>

Import elements

The <import> element selects a subset of the imports. The text and/or comment of the <import> elements is only inserted if the set of imports generated for the element is non-empty. The import element can have several different forms:
    <import package="java.util"/>
    <import regexp =".*\.util\..*"/>
    <import own="on"/>
    <import javalang="on"/>
The package form will match all imports from the given package. The regexp form will match all imports that match the given regular expression (see JDK1.4 java.util.regexp). The empty form will match all imports that are not matched by any other import element in this cleanformat. The empty form need not neccesarilly occurr at the end of the cleanformat. It can occur anywhere but will still only generate import statements that are not matched by any other. The own form will match all imports from the package that the file is in. The javalang form will match all imports from the java.lang package. Ofcourse the imports from the own and java.lang package are not needed for the java compiler but they might be handy for the human reader. These last two forms allow you to generate the imports in comment:
    <import own="on" ascomment="on"/>
    <import javalang="on" ascomment="on"/>

Options elements

The <options> element can be used to set the following options:
    <options collapseAbove="2" blankLines="1" ambiguities="on"/>

The blankLines attribute specifies the number of blank lines that is inserted after each import element. The default is to insert one blank line.

The collapseAbove attribute specifies the threshold for using the dot-star import construction. If more then collapseAbove classes are imported from a certain package the classes are imported by ‘import the.pack.*’. By default no collapsing will occur, so the number is MAX_INT or just high: collapseAbove="99999". By using collapseAbove="0" all imports will be collapsed. Remember that it is not always possible to use dot-star imports because name clashes may occur when classes of different packages have the same names. CleanImports will signal these situations and insert single imports where needed, even if you specified collapseAbove="0". These so-called ambiguous imports are by default marked as such with a comment.

The ambiguities attribute can be used to leave these ambiguity comments out. By default they are on.

Default format

The default format is:
    <options collapseAbove="99999" blankLines="1" ambiguities="on"/>

Import statement replacement

The import statements initially in the file will be removed and the new import statements will be inserted. Because the newly inserted import block can contain comments through the text attributes in the <cleanformat> elements, the <cleanimports> task must also replace comments. Otherwise the comments would be added every time the task is run. The task will remove all "//" style comments between the package statement and the first "/*" comment after the last import statement. So it is not advised to use "/*" comments in the <cleanformat> elements, because it would result in an accumulation of these comments in the source files.


Tom Brus, The Netherlands,


The basic way to invoke cleanimports:

<cleanimports srcdir="${src}" classpath="xyz.jar” />

cleans the imports of all .java files under the ${src} directory. The classpath used for compilation contains xyz.jar.

With some general formatting this would be:

<cleanimports srcdir="${src}" classpath="xyz.jar”>
        <import comment="// java util imports:" package="java.util"/>
        <import comment="// java io   imports:" package=""/>
        <import comment="// java lang imports:" package="java.lang"/>

Adapt the format to your liking.

<cleanimports srcdir="${src}"

cleans the imports of .java files under the ${src} directory. The classpath used contains xyz.jar. Only files under mypackage/p1 and mypackage/p2 are used. Files in the mypackage/p1/testpackage directory are excluded.

<cleanimports srcdir="${src}:${src2}"

is the same as the previous example, with the addition of a second source path, defined by the property src2. This can also be represented using nested <src> elements as follows:

<cleanimports classpath="xyz.jar">
    <src path="${src}"/>
    <src path="${src2}"/>
    <include name="mypackage/p1/**"/>
    <include name="mypackage/p2/**"/>
    <exclude name="mypackage/p1/testpackage/**"/>
Here is an example of how a <cleanformat> can be used:
<cleanimports srcdir="${src}" classpath="xyz.jar" />
        <text     comment="// The Imports"/>
        <options  collapseAbove="3"/>
        <import   comment="// java util imports:" package="java.util"/>
        <import   comment="// other imports:"/>
        <options  collapseAbove="5"/>
        <import   comment="// swing imports:" regexp="\.swing\."/>
        <import   regexp ="^my\.pack\.(plugh|xyzzy)\."/>

Copyright © 2002-2003 Tom Brus. All rights Reserved.