CleanImports

Description

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.

Parameters

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.

Comments

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:

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:

Options elements

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

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.

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.