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 |
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.
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.
<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 are used to insert text into the import block:
<text comment="Import section"/>
<text>This will not compile</text>
<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/>
<import own="on"/>
<import javalang="on"/>
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> 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.
<cleanformat>
<options collapseAbove="99999" blankLines="1" ambiguities="on"/>
<import/>
</cleanformat>
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, cleanimports@tombrus.nl.
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”>
<cleanformat>
<import comment="// java util imports:" package="java.util"/>
<import comment="// java io imports:" package="java.io"/>
<import comment="// java lang imports:" package="java.lang"/>
</cleanformat>
</cleanimports>
Adapt the format to your liking.
<cleanimports srcdir="${src}"
includes="mypackage/p1/**,mypackage/p2/**"
excludes="mypackage/p1/testpackage/**"
classpath="xyz.jar"
/>
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}"
includes="mypackage/p1/**,mypackage/p2/**"
excludes="mypackage/p1/testpackage/**"
classpath="xyz.jar"
/>
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/**"/>
</cleanimports>
<cleanformat> can be used:
<cleanimports srcdir="${src}" classpath="xyz.jar" />
<cleanformat>
<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)\."/>
</cleanformat>
</cleanimports>
Copyright © 2002-2003 Tom Brus. All rights Reserved.