We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

Under construction Mapping File Names

During copying and manipulating with files during an IzPack installation you might want to specify, how should the target files be named depending on the source files, for instance replacing a filename suffix by a different one.

While source files are usually specified as [fileset]s, you don't specify target files directly - instead, you tell IzPack how to find the target file(s) for one source file. An instance of the FileNameMapper class 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 these

classname

specifies the implementation by class name.

classpath

the classpath to use when looking up classname.

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 IzPack 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. For the regexpmapper, \${file.separator} will not work, as on windows it is the '\' character, and this is an escape character for regular expressions, one should use the handledirsep attribute instead.

Nested Elements

The classpath can be specified via a nested <classpath>, as well - that is, a path-like structure.

Nested File Mappers can be supplied via either <mapper> elements. If nested File Mappers are specified by either means, the mapper will be implicitly configured as a composite mapper.


Built-in Mapper Types

All built-in mappers are case-sensitive.

Each of the built-in mapper implementation types is directly accessible using a specific tagname. This makes it possible for filename mappers to support attributes in addition to the generally available to and from.
The <mapper type|classname="..."> usage form remains valid for reasons of backward compatibility.

identity

The target file name is identical to the source file name. Both to and from will be ignored.

Examples:

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

flatten

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.

Examples:

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

merge

The target file name will always be the same, as defined by to - from will be ignored.

Examples:

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

glob

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.

Examples:

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

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

The globmapper mapper can take the following extra attributes.

Attribute

Description

Required

casesensitive

If this is false, the mapper will ignore case when matching the glob pattern. This attribute can be true or false, the default is true.

No

handledirsep

If this is specified, the mapper will ignore the difference between the normal directory separator characters - \\\\\
and /. This attribute can be true or false, the default is false.This attribute is useful for cross-platform build files.

No

Example:

applied on the target file name abc.java will result in the mapped name bc.java.bak and

applied on the target file name \${INSTALL_PATH}\d/emma will result in "mma".

regexp

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 or higher, 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 one of the supported regular expression libraries and the corresponding ant-[jakarta-oro, jakarta-regexp, apache-oro, apache-regexp}.jar from the Ant release you are using. 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 ant-[jakarta-oro, jakarta-regexp, apache-oro, apache-regexp].jar in ANT_HOME/lib.

Examples:

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

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

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

Source file name

Target file name

ClassLoader.class

ClassLoader.java

java/lang/ClassLoader.class

java/lang/ClassLoader.java

java\lang\ClassLoader$1.class

java\lang\ClassLoader.java

java/lang/ClassLoader$foo$1.class

java/lang/ClassLoader.java

The regexpmapper mapper can take the following extra attributes:

Attribute

Description

Required

casesensitive

If this is false, the mapper will ignore case when matching the pattern. This attribute can be true or false, the default is true.

No

handledirsep

If this is specified, the mapper will treat a \ character in a filename as a / for the purposes of matching. This attribute can be true or false, the default is false. This attribute is useful for cross-platform build files. Since ant 1.6.3.

No

An example:

will output "x is j.java.bak" and

will set hd.prop to "f\j.java".

package

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.

Example:

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

unpackage

This mapper is the inverse of the package mapper. It replaces the dots in a package name with directory separators. This is useful for matching XML formatter results against their JUnit test test cases. The mapper shares the sample syntax as the glob mapper.

Example:

Source file name

Target file name

TEST-org.acme.AcmeTest.xml

$

Unknown macro: {test.src.dir}

/org/acme/AcmeTest.java

composite

This mapper implementation can contain multiple nested mappers. File mapping is performed by passing the source filename to each nested <mapper> in turn, returning all results. The to and from attributes are ignored.

Example:

Source file name

Target file names

foo/bar/A.java

foo/bar/A.java

foo.bar.A

The composite mapper has no corresponding <mappertype> attribute.

  • No labels