Unarchiving Tasks

For each of the supported archiving formats there is a correspondig unarchiving task. These tasks are based on their core cousin tasks.

PatternSets are used to select files to extract from the archive. If no patternset is used, all files are extracted.

Resource Collections may be used to select archived files to perform unarchival upon.

You can define filename transformations by using a nested mapper element. The default mapper is the identity mapper.

File permissions will not be restored on extracted files.

Parameters

Attribute Description Required
src archive file to expand. Yes, if filesets are not used.
dest directory where to store the expanded files. Yes
overwrite Overwrite files, even if they are newer than the corresponding entries in the archive (true or false, default is true). No
failOnEmptyArchive whether trying to extract an empty archive is an error. No, defaults to false
stripAbsolutePathSpec whether Ant should remove leading '/' or '\' characters from the extracted file name before extracing it. Note that this changes the entry's name before applying include/exclude patterns and before using the nested mappers (if any). No, defaults to false
skipUnreadableEntries Sometimes archives may contain entries that use features not (yet) supported by Apache Commons Compress, encryption for example. Trying to expand such an archive will normally lead to an error. Sometimes Commons Compress can signal it doesn't know how to handle an entry and if you set skipUnreadableEntries to true, the Compress Antlib will simply skip those entries, avoiding the error.
since Compress Antlib 1.1		 No, defaults to false

Un7z

Since Apache Compress Antlib 1.3.

An unarchiving task for 7z archives.

As of version 1.3 of the Compress Antlib this task can only work on file based resources.

UnAr

An unarchiving task for AR archives.

Traditionally the AR format doesn't allow file names longer than 16 characters. There are two variants that circumvent this limitation in different ways, the GNU/SRV4 and the BSD variant; both of which are transparently supported since Commons Compress 1.3.

UnArj

Since Apache Compress Antlib 1.3.

An unarchiving task for arj archives.

In addition to the parameters above, the unarj tasks supports the following attributes:

Attribute Description Required
encoding The character encoding that has been used for filenames inside the arj file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.
Defaults native-encoding which is the magic value for the platform's default character encoding.
since Compress Antlib 1.3		 No

UnCpio

An unarchiving task for CPIO archives.

In addition to the parameters above, the uncpio tasks supports the following attributes:

Attribute Description Required
encoding The character encoding that has been used for filenames inside the cpio file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.
Defaults native-encoding which is the magic value for the platform's default character encoding.
since Compress Antlib 1.3		 No

UnDump

Since Apache Compress Antlib 1.1.

An unarchiving task for Unix dump archives.

In addition to the parameters above, the undump tasks supports the following attributes:

Attribute Description Required
encoding The character encoding that has been used for filenames inside the dump file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.
Defaults native-encoding which is the magic value for the platform's default character encoding.
since Compress Antlib 1.3		 No

UnTar

An unarchiving task for TAR archives.

In addition to the parameters above, the untar tasks supports the following attributes:

Attribute Description Required
encoding The character encoding that has been used for filenames inside the tar file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.
Defaults native-encoding which is the magic value for the platform's default character encoding.
since Compress Antlib 1.2		 No

UnZip

An unarchiving task for ZIP archives.

Please note that different ZIP tools handle timestamps differently when it comes to applying timezone offset calculations of files. Some ZIP libraries will store the timestamps as they've been read from the filesystem while others will modify the timestamps both when reading and writing the files to make all timestamps use the same timezone. A ZIP archive created by one library may extract files with "wrong timestamps" when extracted by another library.

Apache Commons Compress' ZIP classes use the same algorithm as the InfoZIP tools and zlib (timestamps get adjusted), Windows' "compressed folders" function and WinZIP don't change the timestamps. This means that using the unzip task on files created by Windows' compressed folders function may create files with timestamps that are "wrong", the same is true if you use Windows' functions to extract an Ant generated ZIP archive.

Unlike its counterpart in Ant's core this Antlib's task can also extract archives that are not file system resources.

In addition to the parameters above, the unzip tasks supports the following attributes:

Attribute Description Required
encoding The character encoding that has been used for filenames inside the zip file. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.
Defaults to "UTF8", use the magic value native-encoding for the platform's default character encoding.
See also the discussion in the zip task page		 No
scanForUnicodeExtraFields If the archive contains uncode extra fields then use them to set the file names, ignoring the specified encoding.
See also the discussion in the zip task page		 No, defaults to true

Examples

<cmp:unzip src="${tomcat_src}/tools-src.zip"
    dest="${tools.home}"
    xmlns:cmp="antlib:org.apache.ant.compress"/>


<cmp:gunzip src="tools.tar.gz" xmlns:cmp="antlib:org.apache.ant.compress"/>
<cmp:untar src="tools.tar" dest="${tools.home}"
    xmlns:cmp="antlib:org.apache.ant.compress"/>

<cmp:unzip src="${tomcat_src}/tools-src.zip"
       xmlns:cmp="antlib:org.apache.ant.compress"
       dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
</cmp:unzip>


<cmp:unzip dest="${tools.home} xmlns:cmp="antlib:org.apache.ant.compress"">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
    <fileset dir=".">
        <include name="**/*.zip"/>
        <exclude name="**/tmp*.zip"/>
    </fileset>
</cmp:unzip>


<cmp:unzip src="apache-ant-bin.zip"
    dest="${tools.home}"
    xmlns:cmp="antlib:org.apache.ant.compress">
    <patternset>
        <include name="apache-ant/lib/ant.jar"/>
    </patternset>
    <mapper type="flatten"/>
</cmp:unzip>

<cmp:unzip src="${ant.home}/lib/ant.jar"
    dest="..." xmlns:cmp="antlib:org.apache.ant.compress">
  <patternset>
    <include name="images/"/>
  </patternset>
</cmp:unzip>

This extracts all images from ant.jar which are stored in the images directory of the Jar (or somewhere under it). While extracting the directory structure (images) will be taken.

<cmp:unzip src="${ant.home}/lib/ant.jar"
    dest="..." xmlns:cmp="antlib:org.apache.ant.compress">
  <patternset>
    <include name="**/ant_logo_large.gif"/>
    <include name="**/LICENSE.txt"/>
  </patternset>
</cmp:unzip>

This extracts the two files ant_logo_large.gif and LICENSE.txt from the ant.jar. More exactly: it extracts all files with these names from anywhere in the source file. While extracting the directory structure will be taken.

Related tasks

<cmp:unzip src="some-archive" dest="some-dir" xmlns:cmp="antlib:org.apache.ant.compress">
  <patternset>
    <include name="some-pattern"/>
  </patternset>
  <mapper type="some-mapper"/>
</cmp:unzip>
is identical to 
<copy todir="some-dir" preservelastmodified="true">
  <cmp:zipfileset src="some-archive" xmlns:cmp="antlib:org.apache.ant.compress">
    <patternset>
      <include name="some-pattern"/>
    </patternset>
  </cmp:zipfileset>
  <mapper type="some-mapper"/>
</copy>

The same is also true for <untar> and <tarfileset>. <copy> offers additional features like filtering files on the fly, allowing a file to be mapped to multiple destinations or a configurable file system timestamp granularity.

<cmp:zip destfile="new.jar" xmlns:cmp="antlib:org.apache.ant.compress">
  <cmp:zipfileset src="old.jar">
    <exclude name="do/not/include/this/class"/>
  </cmp:zipfileset>
</cmp:zip>

"Deletes" files from a zipfile.