Some tasks take source files and create target files. Depending on
the task, it may be quite obvious which name a target file will have
(using javac, you know there will be
.class
files for your .java
files) - in
other cases you may want to specify the target files, either to help
Ant or to get an extra bit of functionality.
While source files are usually specified as filesets, you don't specify target files directly -
instead, you tell Ant how to find the target file(s) for one source file. An
instance of org.apache.tools.ant.util.FileNameMapper
is
responsible for this. It constructs target file names based on rules
that can be parameterized with from
and to
attributes - the exact meaning of which is implementation-dependent.
These instances are defined in <mapper>
elements
with the following attributes:
Attribute | Description | Required |
type | specifies one of the built-in implementations. | Exactly one of both |
classname | specifies the implementation by class name. | |
classpath | the classpath to use when looking up
classname . |
No |
classpathref | the classpath to use, given as reference to a path defined elsewhere. | No |
from | the from attribute for the given
implementation. |
Depends on implementation. |
to | the to attribute for the given
implementation. |
Depends on implementation. |
Note that Ant will not automatically convert / or \ characters in
the to
and from
attributes to the correct
directory separator of your current platform. If you need to specify
this separator, use ${file.separator}
instead.
The classpath can be specified via a nested
<classpath>
, as well - that is,
a path-like structure.
The target file name is identical to the source file name. Both
to
and from
will be ignored.
<mapper type="identity"/>
Source file name | Target file name |
A.java |
A.java |
foo/bar/B.java |
foo/bar/B.java |
C.properties |
C.properties |
Classes/dir/dir2/A.properties |
Classes/dir/dir2/A.properties |
The target file name is identical to the source file name, with all
leading directory information stripped off. Both to
and
from
will be ignored.
<mapper type="flatten"/>
Source file name | Target file name |
A.java |
A.java |
foo/bar/B.java |
B.java |
C.properties |
C.properties |
Classes/dir/dir2/A.properties |
A.properties |
The target file name will always be the same, as defined by
to
- from
will be ignored.
<mapper type="merge" to="archive.tar"/>
Source file name | Target file name |
A.java |
archive.tar |
foo/bar/B.java |
archive.tar |
C.properties |
archive.tar |
Classes/dir/dir2/A.properties |
archive.tar |
Both to
and from
define patterns that may
contain at most one *
. For each source file that matches
the from
pattern, a target file name will be constructed
from the to
pattern by substituting the *
in
the to
pattern with the text that matches the
*
in the from
pattern. Source file names
that don't match the from
pattern will be ignored.
<mapper type="glob" from="*.java" to="*.java.bak"/>
Source file name | Target file name |
A.java |
A.java.bak |
foo/bar/B.java |
foo/bar/B.java.bak |
C.properties |
ignored |
Classes/dir/dir2/A.properties |
ignored |
<mapper type="glob" from="C*ies" to="Q*y"/>
Source file name | Target file name |
A.java |
ignored |
foo/bar/B.java |
ignored |
C.properties |
Q.property |
Classes/dir/dir2/A.properties |
Qlasses/dir/dir2/A.property |
Both to
and from
define regular
expressions. If the source file name matches the from
pattern, the target file name will be constructed from the
to
pattern, using \0
to \9
as
back-references for the full
match (\0
) or the matches of the subexpressions in
parentheses.
Source
files not matching the from
pattern will be ignored.
Note that you need to escape a dollar-sign ($
) with
another dollar-sign in Ant.
The regexp mapper needs a supporting library and an implementation
of org.apache.tools.ant.util.regexp.RegexpMatcher
that
hides the specifics of the library. Ant comes with implementations for
the java.util.regex package of JDK 1.4,
jakarta-regexp and jakarta-ORO. If you compile
from sources and plan to use one of them, make sure the libraries are
in your CLASSPATH
. For information about using gnu.regexp or gnu.rex with Ant, see this
article.
This means, you need optional.jar
from the Ant release
you are using and one of the supported regular
expression libraries. Make sure, both will be loaded from the same
classpath, that is either put them into your CLASSPATH
,
ANT_HOME/lib
directory or a nested
<classpath>
element of the mapper - you cannot have
optional.jar
in ANT_HOME/lib
and the library
in a nested <classpath>
.
Ant will choose the regular-expression library based on the following algorithm:
ant.regexp.matcherimpl
has been set, it is taken as the
name of the class implementing
org.apache.tools.ant.util.regexp.RegexpMatcher
that
should be used.<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/>
Source file name | Target file name |
A.java |
A.java.bak |
foo/bar/B.java |
foo/bar/B.java.bak |
C.properties |
ignored |
Classes/dir/dir2/A.properties |
ignored |
<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/>
Source file name | Target file name |
A.java |
ignored |
foo/bar/B.java |
foo/bar/bar-B.java |
C.properties |
ignored |
Classes/dir/dir2/A.properties |
Classes/dir/dir2/dir2-A.properties |
<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/>
Source file name | Target file name |
A.java |
java.A |
foo/bar/B.java |
java.foo/bar/B |
C.properties |
properties.C |
Classes/dir/dir2/A.properties |
properties.Classes/dir/dir2/A |
Sharing the same syntax as the glob mapper,
the package mapper replaces
directory separators found in the matched source pattern with dots in the target
pattern placeholder. This mapper is particularly useful in combination
with <uptodate>
and <junit>
output.
<mapper type="package" from="*Test.java" to="TEST-*Test.xml"/>
Source file name | Target file name |
org/apache/tools/ant/util/PackageMapperTest.java |
TEST-org.apache.tools.ant.util.PackageMapperTest.xml |
org/apache/tools/ant/util/Helper.java |
ignored |
Copyright © 2001 Apache Software Foundation. All rights Reserved.