blob: 9167598bdb2b42d28edd8de8f0b102db599c642e [file] [log] [blame]
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="style.css">
<title>Uncompressing Tasks</title>
</head>
<body>
<h2><a name="unpack">Uncompressing Tasks</a></h2>
<h3>Description</h3>
<p>For each of the supported compression formats there is a
correspondig task that uncompresses a resource. These tasks are
based on
their <a href="http://ant.apache.org/manual/CoreTasks/unpack.html">core
cousin tasks</a>.</p>
<p>If <i>dest</i> is a directory the name of the destination file is
the same as <i>src</i> (with the compression specific
extension removed if present). If <i>dest</i> is omitted, the parent
dir of <i>src</i> is taken. The file is only expanded if the source
resource is newer than the destination file, or when the destination file
does not exist.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">src</td>
<td valign="top">the file to expand.</td>
<td align="center" valign="top">Yes, or a nested resource collection.</td>
</tr>
<tr>
<td valign="top">dest</td>
<td valign="top">the destination file or directory.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">
<a name="decompressConcatenated">decompressConcatenated</a></td>
<td valign="top">Only for the formats that support files holding
multiple compressed streams (bzip2, gzip and xz).<br/>
If set to true all streams will be concatenated and treated as a
single resource. With the default value false only the first
stream is uncompressed.</td>
<td align="center" valign="top">No</td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>any <a href="http://ant.apache.org/manual/CoreTypes/resources.html">resource</a> or single element
resource collection</h4>
<p>The specified resource will be used as src.</p>
<h3><a name="bunzip2">BUnZip2</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the BZIP2
compression algorithm.</p>
<p>This task supports
the <a href="#decompressConcatenated">decompressConcatenated</a>
attribute.</p>
<h3><a name="gunzip">GUnZip</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the GZIP
compression algorithm.</p>
<p>This task supports
the <a href="#decompressConcatenated">decompressConcatenated</a>
attribute.</p>
<h3><a name="unbrotli">unbrotli</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the Brotli
compression algorithm.</p>
<p><em>Since Compress Antlib 1.5</em>
<h3><a name="undeflate">Undeflate</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the DEFLATE
compression algorithm.</p>
<p><em>Since Compress Antlib 1.5</em>
<p>This task supports the following additional attributes:</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">zlibheader</td>
<td valign="top">Whether to expect ZLIB headers. Unfortunately
it is currently not possible to detect whether zlib headers have
been used.</td>
<td valign="top" align="center">No, defaults to <code>true</code></td>
</tr>
</table>
<h3><a name="undeflate64">Undeflate64</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the DEFLATE64
compression algorithm.</p>
<p><em>Since Compress Antlib 1.6</em>
<h3><a name="unlz4">UnLZ4</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the LZ4
compression algorithm.</p>
<p><em>Since Apache Compress Antlib 1.5</em>.</p>
<p>This task supports
the <a href="#decompressConcatenated">decompressConcatenated</a>
attribute if the frame format is used.</p>
<h4>Parameters</h4>
<p>In addition to the attributes supported by all uncompressing task
this task also supports.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">framed</td>
<td valign="top">Whether the input is expected to use
the <a href="http://lz4.github.io/lz4/lz4_Frame_format.html">frame
format</a>.</td>
<td align="center" valign="top">No, defaults to true.</td>
</tr>
</table>
<h3><a name="unlzma">UnLZMA</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the LZMA
compression algorithm.</p>
<h3><a name="unpack200">Unpack200</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses
the <a href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/jar/Pack200.html">Pack200</a>
compression algorithm.</p>
<p>This task does not work on defalted archives, you need to wrap
deflated archives into <code>gunzipresource</code>s in order to use
them.
<h4>Parameters</h4>
<p>In addition to the attributes supported by all uncompressing task
this task also supports.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">pack200strategy</td>
<td valign="top">Apache Commons Compress' Pack200 streams cache
the archive data either in memory or in a temporary file.
User this attribute to control which strategy is chosen.
Valid values are "in-memory" and "temp-file".</td>
<td align="center" valign="top">No, defaults to in-memory.</td>
</tr>
</table>
<h4>Parameters specified as nested elements</h4>
<p>In addition to the nested elements supported by all uncompressing task
this task also supports.</p>
<h5>property</h5>
<p>Sets a property for the unpacker (see the Pack200 javadocs for
details).</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">key</td>
<td valign="top">Name of the property.</td>
<td align="center" valign="top">Yes.</td>
</tr>
<tr>
<td valign="top">value</td>
<td valign="top">Value of the property.</td>
<td align="center" valign="top">Yes.</td>
</tr>
</table>
<h3><a name="unsnappy">UnSnappy</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses
the <a href="https://github.com/google/snappy">Snappy</a>
compression algorithm.</p>
<p><em>Since Apache Compress Antlib 1.4</em>.</p>
<h4>Parameters</h4>
<p>In addition to the attributes supported by all uncompressing task
this task also supports.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">framed</td>
<td valign="top">Whether the input is expected to use
the <a href="https://github.com/google/snappy/blob/master/framing_format.txt">framing
format</a>.</td>
<td align="center" valign="top">No, defaults to true.</td>
</tr>
</table>
<h3><a name="unxz">UnXZ</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the XZ
compression algorithm.</p>
<p>This task supports
the <a href="#decompressConcatenated">decompressConcatenated</a>
attribute.</p>
<h3><a name="unz">UnZ</a></h3>
<p>Is an <a href="#unpack">uncompressing task</a> that uses the .Z
compression algorithm.</p>
<p><em>Since Apache Compress Antlib 1.4</em>.</p>
<h3>Examples</h3>
<blockquote><pre>
&lt;cmp:gunzip src=&quot;test.tar.gz&quot; xmlns:cmp="antlib:org.apache.ant.compress"/&gt;
</pre></blockquote>
<p>expands <i>test.tar.gz</i> to <i>test.tar</i></p>
<blockquote><pre>
&lt;cmp:bunzip2 src=&quot;test.tar.bz2&quot; xmlns:cmp="antlib:org.apache.ant.compress"/&gt;
</pre></blockquote>
<p>expands <i>test.tar.bz2</i> to <i>test.tar</i></p>
<blockquote><pre>
&lt;cmp:gunzip src=&quot;test.tar.gz&quot; dest=&quot;test2.tar&quot; xmlns:cmp="antlib:org.apache.ant.compress"/&gt;
</pre></blockquote>
<p>expands <i>test.tar.gz</i> to <i>test2.tar</i></p>
<blockquote><pre>
&lt;cmp:gunzip src=&quot;test.tar.gz&quot; dest=&quot;subdir&quot; xmlns:cmp="antlib:org.apache.ant.compress"/&gt;
</pre></blockquote>
<p>expands <i>test.tar.gz</i> to <i>subdir/test.tar</i> (assuming
subdir is a directory).</p>
<blockquote><pre>
&lt;cmp:gunzip dest=&quot;.&quot; xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;url url="http://example.org/archive.tar.gz"/&gt;
&lt;/cmp:gunzip&gt;
</pre></blockquote>
<p>downloads <i>http://example.org/archive.tar.gz</i> and expands it
to <i>archive.tar</i> in the project's basedir on the fly.</p>
<blockquote><pre>
&lt;cmp:unpack200 dest=&quot;foo.jar&quot; xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;cmp:gzipresource&gt;
&lt;file file="foo.pack.gz"/&gt;
&lt;/cmp:gzipresource&gt;
&lt;/cmp:unpack200&gt;
</pre></blockquote>
<p>Unpacks the deflated Pack200 archive <i>foo.pack.gz</i> and stores
it as <i>foo.jar</i>.</p>
<h3>Related tasks</h3>
<pre>
&lt;cmp:gunzip src="some-archive.gz" dest="some-dest-dir" xmlns:cmp="antlib:org.apache.ant.compress"/&gt;
</pre>
is identical to
<pre>
&lt;copy todir="some-dest-dir"&gt;
&lt;cmp:gzipresource xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;file file="some-archive.gz"/&gt;
&lt;/cmp:gzipresource&gt;
&lt;mapper type="glob" from="*.gz" to="*"/&gt;
&lt;/copy&gt;
</pre>
<p>The same is also true for <code>&lt;bunzip2&gt;</code> and
<code>&lt;bzip2resource&gt;</code>. <code>&lt;copy&gt;</code> offers
additional features like <a
href="http://ant.apache.org/manual/CoreTypes/filterchain.html">filtering
files</a> on the fly,
allowing a file to be mapped to multiple destinations, preserving the
last modified time or a configurable file system timestamp
granularity.</p>
</body>
</html>