1*ba8755cbSAndroid Build Coastguard Worker<?xml version="1.0"?> 2*ba8755cbSAndroid Build Coastguard Worker<!-- 3*ba8755cbSAndroid Build Coastguard Worker 4*ba8755cbSAndroid Build Coastguard Worker Licensed to the Apache Software Foundation (ASF) under one or more 5*ba8755cbSAndroid Build Coastguard Worker contributor license agreements. See the NOTICE file distributed with 6*ba8755cbSAndroid Build Coastguard Worker this work for additional information regarding copyright ownership. 7*ba8755cbSAndroid Build Coastguard Worker The ASF licenses this file to You under the Apache License, Version 2.0 8*ba8755cbSAndroid Build Coastguard Worker (the "License"); you may not use this file except in compliance with 9*ba8755cbSAndroid Build Coastguard Worker the License. You may obtain a copy of the License at 10*ba8755cbSAndroid Build Coastguard Worker 11*ba8755cbSAndroid Build Coastguard Worker http://www.apache.org/licenses/LICENSE-2.0 12*ba8755cbSAndroid Build Coastguard Worker 13*ba8755cbSAndroid Build Coastguard Worker Unless required by applicable law or agreed to in writing, software 14*ba8755cbSAndroid Build Coastguard Worker distributed under the License is distributed on an "AS IS" BASIS, 15*ba8755cbSAndroid Build Coastguard Worker WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16*ba8755cbSAndroid Build Coastguard Worker See the License for the specific language governing permissions and 17*ba8755cbSAndroid Build Coastguard Worker limitations under the License. 18*ba8755cbSAndroid Build Coastguard Worker 19*ba8755cbSAndroid Build Coastguard Worker--> 20*ba8755cbSAndroid Build Coastguard Worker<document> 21*ba8755cbSAndroid Build Coastguard Worker <properties> 22*ba8755cbSAndroid Build Coastguard Worker <title>Commons Compress ZIP package</title> 23*ba8755cbSAndroid Build Coastguard Worker <author email="[email protected]">Commons Documentation Team</author> 24*ba8755cbSAndroid Build Coastguard Worker </properties> 25*ba8755cbSAndroid Build Coastguard Worker <body> 26*ba8755cbSAndroid Build Coastguard Worker <section name="The ZIP package"> 27*ba8755cbSAndroid Build Coastguard Worker 28*ba8755cbSAndroid Build Coastguard Worker <p>The ZIP package provides features not found 29*ba8755cbSAndroid Build Coastguard Worker in <code>java.util.zip</code>:</p> 30*ba8755cbSAndroid Build Coastguard Worker 31*ba8755cbSAndroid Build Coastguard Worker <ul> 32*ba8755cbSAndroid Build Coastguard Worker <li>Support for encodings other than UTF-8 for filenames and 33*ba8755cbSAndroid Build Coastguard Worker comments. Starting with Java7 this is supported 34*ba8755cbSAndroid Build Coastguard Worker by <code>java.util.zip</code> as well.</li> 35*ba8755cbSAndroid Build Coastguard Worker <li>Access to internal and external attributes (which are used 36*ba8755cbSAndroid Build Coastguard Worker to store Unix permission by some zip implementations).</li> 37*ba8755cbSAndroid Build Coastguard Worker <li>Structured support for extra fields.</li> 38*ba8755cbSAndroid Build Coastguard Worker </ul> 39*ba8755cbSAndroid Build Coastguard Worker 40*ba8755cbSAndroid Build Coastguard Worker <p>In addition to the information stored 41*ba8755cbSAndroid Build Coastguard Worker in <code>ArchiveEntry</code> a <code>ZipArchiveEntry</code> 42*ba8755cbSAndroid Build Coastguard Worker stores internal and external attributes as well as extra 43*ba8755cbSAndroid Build Coastguard Worker fields which may contain information like Unix permissions, 44*ba8755cbSAndroid Build Coastguard Worker information about the platform they've been created on, their 45*ba8755cbSAndroid Build Coastguard Worker last modification time and an optional comment.</p> 46*ba8755cbSAndroid Build Coastguard Worker 47*ba8755cbSAndroid Build Coastguard Worker <subsection name="ZipArchiveInputStream vs ZipFile"> 48*ba8755cbSAndroid Build Coastguard Worker 49*ba8755cbSAndroid Build Coastguard Worker <p>ZIP archives store a archive entries in sequence and 50*ba8755cbSAndroid Build Coastguard Worker contain a registry of all entries at the very end of the 51*ba8755cbSAndroid Build Coastguard Worker archive. It is acceptable for an archive to contain several 52*ba8755cbSAndroid Build Coastguard Worker entries of the same name and have the registry (called the 53*ba8755cbSAndroid Build Coastguard Worker central directory) decide which entry is actually to be used 54*ba8755cbSAndroid Build Coastguard Worker (if any).</p> 55*ba8755cbSAndroid Build Coastguard Worker 56*ba8755cbSAndroid Build Coastguard Worker <p>In addition the ZIP format stores certain information only 57*ba8755cbSAndroid Build Coastguard Worker inside the central directory but not together with the entry 58*ba8755cbSAndroid Build Coastguard Worker itself, this is:</p> 59*ba8755cbSAndroid Build Coastguard Worker 60*ba8755cbSAndroid Build Coastguard Worker <ul> 61*ba8755cbSAndroid Build Coastguard Worker <li>internal and external attributes</li> 62*ba8755cbSAndroid Build Coastguard Worker <li>different or additional extra fields</li> 63*ba8755cbSAndroid Build Coastguard Worker </ul> 64*ba8755cbSAndroid Build Coastguard Worker 65*ba8755cbSAndroid Build Coastguard Worker <p>This means the ZIP format cannot really be parsed 66*ba8755cbSAndroid Build Coastguard Worker correctly while reading a non-seekable stream, which is what 67*ba8755cbSAndroid Build Coastguard Worker <code>ZipArchiveInputStream</code> is forced to do. As a 68*ba8755cbSAndroid Build Coastguard Worker result <code>ZipArchiveInputStream</code></p> 69*ba8755cbSAndroid Build Coastguard Worker <ul> 70*ba8755cbSAndroid Build Coastguard Worker <li>may return entries that are not part of the central 71*ba8755cbSAndroid Build Coastguard Worker directory at all and shouldn't be considered part of the 72*ba8755cbSAndroid Build Coastguard Worker archive.</li> 73*ba8755cbSAndroid Build Coastguard Worker <li>may return several entries with the same name.</li> 74*ba8755cbSAndroid Build Coastguard Worker <li>will not return internal or external attributes.</li> 75*ba8755cbSAndroid Build Coastguard Worker <li>may return incomplete extra field data.</li> 76*ba8755cbSAndroid Build Coastguard Worker <li>may return unknown sizes and CRC values for entries 77*ba8755cbSAndroid Build Coastguard Worker until the next entry has been reached if the archive uses 78*ba8755cbSAndroid Build Coastguard Worker the data descriptor feature (see below).</li> 79*ba8755cbSAndroid Build Coastguard Worker </ul> 80*ba8755cbSAndroid Build Coastguard Worker 81*ba8755cbSAndroid Build Coastguard Worker <p><code>ZipArchiveInputStream</code> shares these limitations 82*ba8755cbSAndroid Build Coastguard Worker with <code>java.util.zip.ZipInputStream</code>.</p> 83*ba8755cbSAndroid Build Coastguard Worker 84*ba8755cbSAndroid Build Coastguard Worker <p><code>ZipFile</code> is able to read the central directory 85*ba8755cbSAndroid Build Coastguard Worker first and provide correct and complete information on any 86*ba8755cbSAndroid Build Coastguard Worker ZIP archive.</p> 87*ba8755cbSAndroid Build Coastguard Worker 88*ba8755cbSAndroid Build Coastguard Worker <p>ZIP archives know a feature called the data descriptor 89*ba8755cbSAndroid Build Coastguard Worker which is a way to store an entry's length after the entry's 90*ba8755cbSAndroid Build Coastguard Worker data. This can only work reliably if the size information 91*ba8755cbSAndroid Build Coastguard Worker can be taken from the central directory or the data itself 92*ba8755cbSAndroid Build Coastguard Worker can signal it is complete, which is true for data that is 93*ba8755cbSAndroid Build Coastguard Worker compressed using the DEFLATED compression algorithm.</p> 94*ba8755cbSAndroid Build Coastguard Worker 95*ba8755cbSAndroid Build Coastguard Worker <p><code>ZipFile</code> has access to the central directory 96*ba8755cbSAndroid Build Coastguard Worker and can extract entries using the data descriptor reliably. 97*ba8755cbSAndroid Build Coastguard Worker The same is true for <code>ZipArchiveInputStream</code> as 98*ba8755cbSAndroid Build Coastguard Worker long as the entry is DEFLATED. For STORED 99*ba8755cbSAndroid Build Coastguard Worker entries <code>ZipArchiveInputStream</code> can try to read 100*ba8755cbSAndroid Build Coastguard Worker ahead until it finds the next entry, but this approach is 101*ba8755cbSAndroid Build Coastguard Worker not safe and has to be enabled by a constructor argument 102*ba8755cbSAndroid Build Coastguard Worker explicitly.</p> 103*ba8755cbSAndroid Build Coastguard Worker 104*ba8755cbSAndroid Build Coastguard Worker <p>If possible, you should always prefer <code>ZipFile</code> 105*ba8755cbSAndroid Build Coastguard Worker over <code>ZipArchiveInputStream</code>.</p> 106*ba8755cbSAndroid Build Coastguard Worker 107*ba8755cbSAndroid Build Coastguard Worker <p><code>ZipFile</code> requires a 108*ba8755cbSAndroid Build Coastguard Worker <code>SeekableByteChannel</code> that will be obtained 109*ba8755cbSAndroid Build Coastguard Worker transparently when reading from a file. The class 110*ba8755cbSAndroid Build Coastguard Worker <code>org.apache.commons.compress.utils.SeekableInMemoryByteChannel</code> 111*ba8755cbSAndroid Build Coastguard Worker allows you to read from an in-memory archive.</p> 112*ba8755cbSAndroid Build Coastguard Worker 113*ba8755cbSAndroid Build Coastguard Worker </subsection> 114*ba8755cbSAndroid Build Coastguard Worker 115*ba8755cbSAndroid Build Coastguard Worker <subsection name="ZipArchiveOutputStream" id="ZipArchiveOutputStream"> 116*ba8755cbSAndroid Build Coastguard Worker <p><code>ZipArchiveOutputStream</code> has three constructors, 117*ba8755cbSAndroid Build Coastguard Worker one of them uses a <code>File</code> argument, one a 118*ba8755cbSAndroid Build Coastguard Worker <code>SeekableByteChannel</code> and the last uses an 119*ba8755cbSAndroid Build Coastguard Worker <code>OutputStream</code>. The <code>File</code> version will 120*ba8755cbSAndroid Build Coastguard Worker try to use <code>SeekableByteChannel</code> and fall back to 121*ba8755cbSAndroid Build Coastguard Worker using a <code>FileOutputStream</code> internally if that 122*ba8755cbSAndroid Build Coastguard Worker fails.</p> 123*ba8755cbSAndroid Build Coastguard Worker 124*ba8755cbSAndroid Build Coastguard Worker <p>If <code>ZipArchiveOutputStream</code> can 125*ba8755cbSAndroid Build Coastguard Worker use <code>SeekableByteChannel</code> it can employ some 126*ba8755cbSAndroid Build Coastguard Worker optimizations that lead to smaller archives. It also makes 127*ba8755cbSAndroid Build Coastguard Worker it possible to add uncompressed (<code>setMethod</code> used 128*ba8755cbSAndroid Build Coastguard Worker with <code>STORED</code>) entries of unknown size when 129*ba8755cbSAndroid Build Coastguard Worker calling <code>putArchiveEntry</code> - this is not allowed 130*ba8755cbSAndroid Build Coastguard Worker if <code>ZipArchiveOutputStream</code> has to use 131*ba8755cbSAndroid Build Coastguard Worker an <code>OutputStream</code>.</p> 132*ba8755cbSAndroid Build Coastguard Worker 133*ba8755cbSAndroid Build Coastguard Worker <p>If you know you are writing to a file, you should always 134*ba8755cbSAndroid Build Coastguard Worker prefer the <code>File</code>- or 135*ba8755cbSAndroid Build Coastguard Worker <code>SeekableByteChannel</code>-arg constructors. The class 136*ba8755cbSAndroid Build Coastguard Worker <code>org.apache.commons.compress.utils.SeekableInMemoryByteChannel</code> 137*ba8755cbSAndroid Build Coastguard Worker allows you to write to an in-memory archive.</p> 138*ba8755cbSAndroid Build Coastguard Worker 139*ba8755cbSAndroid Build Coastguard Worker </subsection> 140*ba8755cbSAndroid Build Coastguard Worker 141*ba8755cbSAndroid Build Coastguard Worker <subsection name="Extra Fields"> 142*ba8755cbSAndroid Build Coastguard Worker 143*ba8755cbSAndroid Build Coastguard Worker <p>Inside a ZIP archive, additional data can be attached to 144*ba8755cbSAndroid Build Coastguard Worker each entry. The <code>java.util.zip.ZipEntry</code> class 145*ba8755cbSAndroid Build Coastguard Worker provides access to this via the <code>get/setExtra</code> 146*ba8755cbSAndroid Build Coastguard Worker methods as arrays of <code>byte</code>s.</p> 147*ba8755cbSAndroid Build Coastguard Worker 148*ba8755cbSAndroid Build Coastguard Worker <p>Actually the extra data is supposed to be more structured 149*ba8755cbSAndroid Build Coastguard Worker than that and Compress' ZIP package provides access to the 150*ba8755cbSAndroid Build Coastguard Worker structured data as <code>ExtraField</code> instances. Only 151*ba8755cbSAndroid Build Coastguard Worker a subset of all defined extra field formats is supported by 152*ba8755cbSAndroid Build Coastguard Worker the package, any other extra field will be stored 153*ba8755cbSAndroid Build Coastguard Worker as <code>UnrecognizedExtraField</code>.</p> 154*ba8755cbSAndroid Build Coastguard Worker 155*ba8755cbSAndroid Build Coastguard Worker <p>Prior to version 1.1 of this library trying to read an 156*ba8755cbSAndroid Build Coastguard Worker archive with extra fields that didn't follow the recommended 157*ba8755cbSAndroid Build Coastguard Worker structure for those fields would cause Compress to throw an 158*ba8755cbSAndroid Build Coastguard Worker exception. Starting with version 1.1 these extra fields 159*ba8755cbSAndroid Build Coastguard Worker will now be read 160*ba8755cbSAndroid Build Coastguard Worker as <code>UnparseableExtraFieldData</code>.</p> 161*ba8755cbSAndroid Build Coastguard Worker 162*ba8755cbSAndroid Build Coastguard Worker </subsection> 163*ba8755cbSAndroid Build Coastguard Worker 164*ba8755cbSAndroid Build Coastguard Worker <subsection name="Encoding" id="encoding"> 165*ba8755cbSAndroid Build Coastguard Worker 166*ba8755cbSAndroid Build Coastguard Worker <p>Traditionally the ZIP archive format uses CodePage 437 as 167*ba8755cbSAndroid Build Coastguard Worker encoding for file name, which is not sufficient for many 168*ba8755cbSAndroid Build Coastguard Worker international character sets.</p> 169*ba8755cbSAndroid Build Coastguard Worker 170*ba8755cbSAndroid Build Coastguard Worker <p>Over time different archivers have chosen different ways to 171*ba8755cbSAndroid Build Coastguard Worker work around the limitation - the <code>java.util.zip</code> 172*ba8755cbSAndroid Build Coastguard Worker packages simply uses UTF-8 as its encoding for example.</p> 173*ba8755cbSAndroid Build Coastguard Worker 174*ba8755cbSAndroid Build Coastguard Worker <p>Ant has been offering the encoding attribute of the zip and 175*ba8755cbSAndroid Build Coastguard Worker unzip task as a way to explicitly specify the encoding to 176*ba8755cbSAndroid Build Coastguard Worker use (or expect) since Ant 1.4. It defaults to the 177*ba8755cbSAndroid Build Coastguard Worker platform's default encoding for zip and UTF-8 for jar and 178*ba8755cbSAndroid Build Coastguard Worker other jar-like tasks (war, ear, ...) as well as the unzip 179*ba8755cbSAndroid Build Coastguard Worker family of tasks.</p> 180*ba8755cbSAndroid Build Coastguard Worker 181*ba8755cbSAndroid Build Coastguard Worker <p>More recent versions of the ZIP specification introduce 182*ba8755cbSAndroid Build Coastguard Worker something called the "language encoding flag" 183*ba8755cbSAndroid Build Coastguard Worker which can be used to signal that a file name has been 184*ba8755cbSAndroid Build Coastguard Worker encoded using UTF-8. All ZIP-archives written by Compress 185*ba8755cbSAndroid Build Coastguard Worker will set this flag, if the encoding has been set to UTF-8. 186*ba8755cbSAndroid Build Coastguard Worker Our interoperability tests with existing archivers didn't 187*ba8755cbSAndroid Build Coastguard Worker show any ill effects (in fact, most archivers ignore the 188*ba8755cbSAndroid Build Coastguard Worker flag to date), but you can turn off the "language encoding 189*ba8755cbSAndroid Build Coastguard Worker flag" by setting the attribute 190*ba8755cbSAndroid Build Coastguard Worker <code>useLanguageEncodingFlag</code> to <code>false</code> on the 191*ba8755cbSAndroid Build Coastguard Worker <code>ZipArchiveOutputStream</code> if you should encounter 192*ba8755cbSAndroid Build Coastguard Worker problems.</p> 193*ba8755cbSAndroid Build Coastguard Worker 194*ba8755cbSAndroid Build Coastguard Worker <p>The <code>ZipFile</code> 195*ba8755cbSAndroid Build Coastguard Worker and <code>ZipArchiveInputStream</code> classes will 196*ba8755cbSAndroid Build Coastguard Worker recognize the language encoding flag and ignore the encoding 197*ba8755cbSAndroid Build Coastguard Worker set in the constructor if it has been found.</p> 198*ba8755cbSAndroid Build Coastguard Worker 199*ba8755cbSAndroid Build Coastguard Worker <p>The InfoZIP developers have introduced new ZIP extra fields 200*ba8755cbSAndroid Build Coastguard Worker that can be used to add an additional UTF-8 encoded file 201*ba8755cbSAndroid Build Coastguard Worker name to the entry's metadata. Most archivers ignore these 202*ba8755cbSAndroid Build Coastguard Worker extra fields. <code>ZipArchiveOutputStream</code> supports 203*ba8755cbSAndroid Build Coastguard Worker an option <code>createUnicodeExtraFields</code> which makes 204*ba8755cbSAndroid Build Coastguard Worker it write these extra fields either for all entries 205*ba8755cbSAndroid Build Coastguard Worker ("always") or only those whose name cannot be encoded using 206*ba8755cbSAndroid Build Coastguard Worker the specified encoding (not-encodeable), it defaults to 207*ba8755cbSAndroid Build Coastguard Worker "never" since the extra fields create bigger archives.</p> 208*ba8755cbSAndroid Build Coastguard Worker 209*ba8755cbSAndroid Build Coastguard Worker <p>The fallbackToUTF8 attribute 210*ba8755cbSAndroid Build Coastguard Worker of <code>ZipArchiveOutputStream</code> can be used to create 211*ba8755cbSAndroid Build Coastguard Worker archives that use the specified encoding in the majority of 212*ba8755cbSAndroid Build Coastguard Worker cases but UTF-8 and the language encoding flag for filenames 213*ba8755cbSAndroid Build Coastguard Worker that cannot be encoded using the specified encoding.</p> 214*ba8755cbSAndroid Build Coastguard Worker 215*ba8755cbSAndroid Build Coastguard Worker <p>The <code>ZipFile</code> 216*ba8755cbSAndroid Build Coastguard Worker and <code>ZipArchiveInputStream</code> classes recognize the 217*ba8755cbSAndroid Build Coastguard Worker Unicode extra fields by default and read the file name 218*ba8755cbSAndroid Build Coastguard Worker information from them, unless you set the constructor parameter 219*ba8755cbSAndroid Build Coastguard Worker <code>scanForUnicodeExtraFields</code> to false.</p> 220*ba8755cbSAndroid Build Coastguard Worker 221*ba8755cbSAndroid Build Coastguard Worker <h4>Recommendations for Interoperability</h4> 222*ba8755cbSAndroid Build Coastguard Worker 223*ba8755cbSAndroid Build Coastguard Worker <p>The optimal setting of flags depends on the archivers you 224*ba8755cbSAndroid Build Coastguard Worker expect as consumers/producers of the ZIP archives. Below 225*ba8755cbSAndroid Build Coastguard Worker are some test results which may be superseded with later 226*ba8755cbSAndroid Build Coastguard Worker versions of each tool.</p> 227*ba8755cbSAndroid Build Coastguard Worker 228*ba8755cbSAndroid Build Coastguard Worker <ul> 229*ba8755cbSAndroid Build Coastguard Worker <li>The java.util.zip package used by the jar executable or 230*ba8755cbSAndroid Build Coastguard Worker to read jars from your CLASSPATH reads and writes UTF-8 231*ba8755cbSAndroid Build Coastguard Worker names, it doesn't set or recognize any flags or Unicode 232*ba8755cbSAndroid Build Coastguard Worker extra fields.</li> 233*ba8755cbSAndroid Build Coastguard Worker 234*ba8755cbSAndroid Build Coastguard Worker <li>Starting with Java7 <code>java.util.zip</code> writes 235*ba8755cbSAndroid Build Coastguard Worker UTF-8 by default and uses the language encoding flag. It 236*ba8755cbSAndroid Build Coastguard Worker is possible to specify a different encoding when 237*ba8755cbSAndroid Build Coastguard Worker reading/writing ZIPs via new constructors. The package 238*ba8755cbSAndroid Build Coastguard Worker now recognizes the language encoding flag when reading and 239*ba8755cbSAndroid Build Coastguard Worker ignores the Unicode extra fields.</li> 240*ba8755cbSAndroid Build Coastguard Worker 241*ba8755cbSAndroid Build Coastguard Worker <li>7Zip writes CodePage 437 by default but uses UTF-8 and 242*ba8755cbSAndroid Build Coastguard Worker the language encoding flag when writing entries that 243*ba8755cbSAndroid Build Coastguard Worker cannot be encoded as CodePage 437 (similar to the zip task 244*ba8755cbSAndroid Build Coastguard Worker with fallbacktoUTF8 set to true). It recognizes the 245*ba8755cbSAndroid Build Coastguard Worker language encoding flag when reading and ignores the 246*ba8755cbSAndroid Build Coastguard Worker Unicode extra fields.</li> 247*ba8755cbSAndroid Build Coastguard Worker 248*ba8755cbSAndroid Build Coastguard Worker <li>WinZIP writes CodePage 437 and uses Unicode extra fields 249*ba8755cbSAndroid Build Coastguard Worker by default. It recognizes the Unicode extra field and the 250*ba8755cbSAndroid Build Coastguard Worker language encoding flag when reading.</li> 251*ba8755cbSAndroid Build Coastguard Worker 252*ba8755cbSAndroid Build Coastguard Worker <li>Windows' "compressed folder" feature doesn't recognize 253*ba8755cbSAndroid Build Coastguard Worker any flag or extra field and creates archives using the 254*ba8755cbSAndroid Build Coastguard Worker platforms default encoding - and expects archives to be in 255*ba8755cbSAndroid Build Coastguard Worker that encoding when reading them.</li> 256*ba8755cbSAndroid Build Coastguard Worker 257*ba8755cbSAndroid Build Coastguard Worker <li>InfoZIP based tools can recognize and write both, it is 258*ba8755cbSAndroid Build Coastguard Worker a compile time option and depends on the platform so your 259*ba8755cbSAndroid Build Coastguard Worker mileage may vary.</li> 260*ba8755cbSAndroid Build Coastguard Worker 261*ba8755cbSAndroid Build Coastguard Worker <li>PKWARE zip tools recognize both and prefer the language 262*ba8755cbSAndroid Build Coastguard Worker encoding flag. They create archives using CodePage 437 if 263*ba8755cbSAndroid Build Coastguard Worker possible and UTF-8 plus the language encoding flag for 264*ba8755cbSAndroid Build Coastguard Worker file names that cannot be encoded as CodePage 437.</li> 265*ba8755cbSAndroid Build Coastguard Worker </ul> 266*ba8755cbSAndroid Build Coastguard Worker 267*ba8755cbSAndroid Build Coastguard Worker <p>So, what to do?</p> 268*ba8755cbSAndroid Build Coastguard Worker 269*ba8755cbSAndroid Build Coastguard Worker <p>If you are creating jars, then java.util.zip is your main 270*ba8755cbSAndroid Build Coastguard Worker consumer. We recommend you set the encoding to UTF-8 and 271*ba8755cbSAndroid Build Coastguard Worker keep the language encoding flag enabled. The flag won't 272*ba8755cbSAndroid Build Coastguard Worker help or hurt java.util.zip prior to Java7 but archivers that 273*ba8755cbSAndroid Build Coastguard Worker support it will show the correct file names.</p> 274*ba8755cbSAndroid Build Coastguard Worker 275*ba8755cbSAndroid Build Coastguard Worker <p>For maximum interop it is probably best to set the encoding 276*ba8755cbSAndroid Build Coastguard Worker to UTF-8, enable the language encoding flag and create 277*ba8755cbSAndroid Build Coastguard Worker Unicode extra fields when writing ZIPs. Such archives 278*ba8755cbSAndroid Build Coastguard Worker should be extracted correctly by java.util.zip, 7Zip, 279*ba8755cbSAndroid Build Coastguard Worker WinZIP, PKWARE tools and most likely InfoZIP tools. They 280*ba8755cbSAndroid Build Coastguard Worker will be unusable with Windows' "compressed folders" feature 281*ba8755cbSAndroid Build Coastguard Worker and bigger than archives without the Unicode extra fields, 282*ba8755cbSAndroid Build Coastguard Worker though.</p> 283*ba8755cbSAndroid Build Coastguard Worker 284*ba8755cbSAndroid Build Coastguard Worker <p>If Windows' "compressed folders" is your primary consumer, 285*ba8755cbSAndroid Build Coastguard Worker then your best option is to explicitly set the encoding to 286*ba8755cbSAndroid Build Coastguard Worker the target platform. You may want to enable creation of 287*ba8755cbSAndroid Build Coastguard Worker Unicode extra fields so the tools that support them will 288*ba8755cbSAndroid Build Coastguard Worker extract the file names correctly.</p> 289*ba8755cbSAndroid Build Coastguard Worker </subsection> 290*ba8755cbSAndroid Build Coastguard Worker 291*ba8755cbSAndroid Build Coastguard Worker <subsection name="Encryption and Alternative Compression Algorithms" 292*ba8755cbSAndroid Build Coastguard Worker id="encryption"> 293*ba8755cbSAndroid Build Coastguard Worker 294*ba8755cbSAndroid Build Coastguard Worker <p>In most cases entries of an archive are not encrypted and 295*ba8755cbSAndroid Build Coastguard Worker are either not compressed at all or use the DEFLATE 296*ba8755cbSAndroid Build Coastguard Worker algorithm, Commons Compress' ZIP archiver will handle them 297*ba8755cbSAndroid Build Coastguard Worker just fine. As of version 1.7, Commons Compress can also 298*ba8755cbSAndroid Build Coastguard Worker decompress entries compressed with the legacy SHRINK and 299*ba8755cbSAndroid Build Coastguard Worker IMPLODE algorithms of PKZIP 1.x. Version 1.11 of Commons 300*ba8755cbSAndroid Build Coastguard Worker Compress adds read-only support for BZIP2. Version 1.16 adds 301*ba8755cbSAndroid Build Coastguard Worker read-only support for DEFLATE64 - also known as "enhanced DEFLATE".</p> 302*ba8755cbSAndroid Build Coastguard Worker 303*ba8755cbSAndroid Build Coastguard Worker <p>The ZIP specification allows for various other compression 304*ba8755cbSAndroid Build Coastguard Worker algorithms and also supports several different ways of 305*ba8755cbSAndroid Build Coastguard Worker encrypting archive contents. Neither of those methods is 306*ba8755cbSAndroid Build Coastguard Worker currently supported by Commons Compress and any such entry can 307*ba8755cbSAndroid Build Coastguard Worker not be extracted by the archiving code.</p> 308*ba8755cbSAndroid Build Coastguard Worker 309*ba8755cbSAndroid Build Coastguard Worker <p><code>ZipFile</code>'s and 310*ba8755cbSAndroid Build Coastguard Worker <code>ZipArchiveInputStream</code>'s 311*ba8755cbSAndroid Build Coastguard Worker <code>canReadEntryData</code> methods will return false for 312*ba8755cbSAndroid Build Coastguard Worker encrypted entries or entries using an unsupported encryption 313*ba8755cbSAndroid Build Coastguard Worker mechanism. Using this method it is possible to at least 314*ba8755cbSAndroid Build Coastguard Worker detect and skip the entries that can not be extracted.</p> 315*ba8755cbSAndroid Build Coastguard Worker 316*ba8755cbSAndroid Build Coastguard Worker <table> 317*ba8755cbSAndroid Build Coastguard Worker <thead> 318*ba8755cbSAndroid Build Coastguard Worker <tr> 319*ba8755cbSAndroid Build Coastguard Worker <th>Version of Apache Commons Compress</th> 320*ba8755cbSAndroid Build Coastguard Worker <th>Supported Compression Methods</th> 321*ba8755cbSAndroid Build Coastguard Worker <th>Supported Encryption Methods</th> 322*ba8755cbSAndroid Build Coastguard Worker </tr> 323*ba8755cbSAndroid Build Coastguard Worker </thead> 324*ba8755cbSAndroid Build Coastguard Worker <tbody> 325*ba8755cbSAndroid Build Coastguard Worker <tr> 326*ba8755cbSAndroid Build Coastguard Worker <td>1.0 to 1.6</td> 327*ba8755cbSAndroid Build Coastguard Worker <td>STORED, DEFLATE</td> 328*ba8755cbSAndroid Build Coastguard Worker <td>-</td> 329*ba8755cbSAndroid Build Coastguard Worker </tr> 330*ba8755cbSAndroid Build Coastguard Worker <tr> 331*ba8755cbSAndroid Build Coastguard Worker <td>1.7 to 1.10</td> 332*ba8755cbSAndroid Build Coastguard Worker <td>STORED, DEFLATE, SHRINK, IMPLODE</td> 333*ba8755cbSAndroid Build Coastguard Worker <td>-</td> 334*ba8755cbSAndroid Build Coastguard Worker </tr> 335*ba8755cbSAndroid Build Coastguard Worker <tr> 336*ba8755cbSAndroid Build Coastguard Worker <td>1.11 to 1.15</td> 337*ba8755cbSAndroid Build Coastguard Worker <td>STORED, DEFLATE, SHRINK, IMPLODE, BZIP2</td> 338*ba8755cbSAndroid Build Coastguard Worker <td>-</td> 339*ba8755cbSAndroid Build Coastguard Worker </tr> 340*ba8755cbSAndroid Build Coastguard Worker <tr> 341*ba8755cbSAndroid Build Coastguard Worker <td>1.16 and later</td> 342*ba8755cbSAndroid Build Coastguard Worker <td>STORED, DEFLATE, SHRINK, IMPLODE, BZIP2, DEFLATE64 343*ba8755cbSAndroid Build Coastguard Worker (enhanced deflate)</td> 344*ba8755cbSAndroid Build Coastguard Worker <td>-</td> 345*ba8755cbSAndroid Build Coastguard Worker </tr> 346*ba8755cbSAndroid Build Coastguard Worker </tbody> 347*ba8755cbSAndroid Build Coastguard Worker </table> 348*ba8755cbSAndroid Build Coastguard Worker 349*ba8755cbSAndroid Build Coastguard Worker </subsection> 350*ba8755cbSAndroid Build Coastguard Worker 351*ba8755cbSAndroid Build Coastguard Worker <subsection name="Zip64 Support" id="zip64"> 352*ba8755cbSAndroid Build Coastguard Worker <p>The traditional ZIP format is limited to archive sizes of 353*ba8755cbSAndroid Build Coastguard Worker four gibibyte (actually 2<sup>32</sup> - 1 bytes ≈ 354*ba8755cbSAndroid Build Coastguard Worker 4.3 GB) and 65635 entries, where each individual entry is 355*ba8755cbSAndroid Build Coastguard Worker limited to four gibibyte as well. These limits seemed 356*ba8755cbSAndroid Build Coastguard Worker excessive in the 1980s.</p> 357*ba8755cbSAndroid Build Coastguard Worker 358*ba8755cbSAndroid Build Coastguard Worker <p>Version 4.5 of the ZIP specification introduced the so 359*ba8755cbSAndroid Build Coastguard Worker called "Zip64 extensions" to push those limitations for 360*ba8755cbSAndroid Build Coastguard Worker compressed or uncompressed sizes of up to 16 exbibyte 361*ba8755cbSAndroid Build Coastguard Worker (actually 2<sup>64</sup> - 1 bytes ≈ 18.5 EB, i.e 362*ba8755cbSAndroid Build Coastguard Worker 18.5 x 10<sup>18</sup> bytes) in archives that themselves 363*ba8755cbSAndroid Build Coastguard Worker can take up to 16 exbibyte containing more than 364*ba8755cbSAndroid Build Coastguard Worker 18 x 10<sup>18</sup> entries.</p> 365*ba8755cbSAndroid Build Coastguard Worker 366*ba8755cbSAndroid Build Coastguard Worker <p>Apache Commons Compress 1.2 and earlier do not support 367*ba8755cbSAndroid Build Coastguard Worker Zip64 extensions at all.</p> 368*ba8755cbSAndroid Build Coastguard Worker 369*ba8755cbSAndroid Build Coastguard Worker <p>Starting with Apache Commons Compress 370*ba8755cbSAndroid Build Coastguard Worker 1.3 <code>ZipArchiveInputStream</code> 371*ba8755cbSAndroid Build Coastguard Worker and <code>ZipFile</code> transparently support Zip64 372*ba8755cbSAndroid Build Coastguard Worker extensions. By default <code>ZipArchiveOutputStream</code> 373*ba8755cbSAndroid Build Coastguard Worker supports them transparently as well (i.e. it adds Zip64 374*ba8755cbSAndroid Build Coastguard Worker extensions if needed and doesn't use them for 375*ba8755cbSAndroid Build Coastguard Worker entries/archives that don't need them) if the compressed and 376*ba8755cbSAndroid Build Coastguard Worker uncompressed sizes of the entry are known 377*ba8755cbSAndroid Build Coastguard Worker when <code>putArchiveEntry</code> is called 378*ba8755cbSAndroid Build Coastguard Worker or <code>ZipArchiveOutputStream</code> 379*ba8755cbSAndroid Build Coastguard Worker uses <code>SeekableByteChannel</code> 380*ba8755cbSAndroid Build Coastguard Worker (see <a href="#ZipArchiveOutputStream">above</a>). If only 381*ba8755cbSAndroid Build Coastguard Worker the uncompressed size is 382*ba8755cbSAndroid Build Coastguard Worker known <code>ZipArchiveOutputStream</code> will assume the 383*ba8755cbSAndroid Build Coastguard Worker compressed size will not be bigger than the uncompressed 384*ba8755cbSAndroid Build Coastguard Worker size.</p> 385*ba8755cbSAndroid Build Coastguard Worker 386*ba8755cbSAndroid Build Coastguard Worker <p><code>ZipArchiveOutputStream</code>'s 387*ba8755cbSAndroid Build Coastguard Worker <code>setUseZip64</code> can be used to control the behavior. 388*ba8755cbSAndroid Build Coastguard Worker <code>Zip64Mode.AsNeeded</code> is the default behavior 389*ba8755cbSAndroid Build Coastguard Worker described in the previous paragraph.</p> 390*ba8755cbSAndroid Build Coastguard Worker 391*ba8755cbSAndroid Build Coastguard Worker <p>If <code>ZipArchiveOutputStream</code> is writing to a 392*ba8755cbSAndroid Build Coastguard Worker non-seekable stream it has to decide whether to use Zip64 393*ba8755cbSAndroid Build Coastguard Worker extensions or not before it starts wrtiting the entry data. 394*ba8755cbSAndroid Build Coastguard Worker This means that if the size of the entry is unknown 395*ba8755cbSAndroid Build Coastguard Worker when <code>putArchiveEntry</code> is called it doesn't have 396*ba8755cbSAndroid Build Coastguard Worker anything to base the decision on. By default it will not 397*ba8755cbSAndroid Build Coastguard Worker use Zip64 extensions in order to create archives that can be 398*ba8755cbSAndroid Build Coastguard Worker extracted by older archivers (it will later throw an 399*ba8755cbSAndroid Build Coastguard Worker exception in <code>closeEntry</code> if it detects Zip64 400*ba8755cbSAndroid Build Coastguard Worker extensions had been needed). It is possible to 401*ba8755cbSAndroid Build Coastguard Worker instruct <code>ZipArchiveOutputStream</code> to always 402*ba8755cbSAndroid Build Coastguard Worker create Zip64 extensions by using 403*ba8755cbSAndroid Build Coastguard Worker the <code>setUseZip64</code> with an argument 404*ba8755cbSAndroid Build Coastguard Worker of <code>Zip64Mode.Always</code>; use this if you are 405*ba8755cbSAndroid Build Coastguard Worker writing entries of unknown size to a stream and expect some 406*ba8755cbSAndroid Build Coastguard Worker of them to be too big to fit into the traditional 407*ba8755cbSAndroid Build Coastguard Worker limits.</p> 408*ba8755cbSAndroid Build Coastguard Worker 409*ba8755cbSAndroid Build Coastguard Worker <p><code>Zip64Mode.Always</code> creates archives that use 410*ba8755cbSAndroid Build Coastguard Worker Zip64 extensions for all entries, even those that don't 411*ba8755cbSAndroid Build Coastguard Worker require them. Such archives will be slightly bigger than 412*ba8755cbSAndroid Build Coastguard Worker archives created with one of the other modes and not be 413*ba8755cbSAndroid Build Coastguard Worker readable by unarchivers that don't support Zip64 414*ba8755cbSAndroid Build Coastguard Worker extensions.</p> 415*ba8755cbSAndroid Build Coastguard Worker 416*ba8755cbSAndroid Build Coastguard Worker <p><code>Zip64Mode.Never</code> will not use any Zip64 417*ba8755cbSAndroid Build Coastguard Worker extensions at all and may lead to 418*ba8755cbSAndroid Build Coastguard Worker a <code>Zip64RequiredException</code> to be thrown 419*ba8755cbSAndroid Build Coastguard Worker if <code>ZipArchiveOutputStream</code> detects that one of 420*ba8755cbSAndroid Build Coastguard Worker the format's limits is exceeded. Archives created in this 421*ba8755cbSAndroid Build Coastguard Worker mode will be readable by all unarchivers; they may be 422*ba8755cbSAndroid Build Coastguard Worker slightly smaller than archives created 423*ba8755cbSAndroid Build Coastguard Worker with <code>SeekableByteChannel</code> 424*ba8755cbSAndroid Build Coastguard Worker in <code>Zip64Mode.AsNeeded</code> mode if some of the 425*ba8755cbSAndroid Build Coastguard Worker entries had unknown sizes.</p> 426*ba8755cbSAndroid Build Coastguard Worker 427*ba8755cbSAndroid Build Coastguard Worker <p>The <code>java.util.zip</code> package and the 428*ba8755cbSAndroid Build Coastguard Worker <code>jar</code> command of Java5 and earlier can not read 429*ba8755cbSAndroid Build Coastguard Worker Zip64 extensions and will fail if the archive contains any. 430*ba8755cbSAndroid Build Coastguard Worker So if you intend to create archives that Java5 can consume 431*ba8755cbSAndroid Build Coastguard Worker you must set the mode to <code>Zip64Mode.Never</code></p> 432*ba8755cbSAndroid Build Coastguard Worker 433*ba8755cbSAndroid Build Coastguard Worker <h4>Known Limitations</h4> 434*ba8755cbSAndroid Build Coastguard Worker 435*ba8755cbSAndroid Build Coastguard Worker <p>Some of the theoretical limits of the format are not 436*ba8755cbSAndroid Build Coastguard Worker reached because Apache Commons Compress' own API 437*ba8755cbSAndroid Build Coastguard Worker (<code>ArchiveEntry</code>'s size information uses 438*ba8755cbSAndroid Build Coastguard Worker a <code>long</code>) or its usage of Java collections 439*ba8755cbSAndroid Build Coastguard Worker or <code>SeekableByteChannel</code> internally. The table 440*ba8755cbSAndroid Build Coastguard Worker below shows the theoretical limits supported by Apache 441*ba8755cbSAndroid Build Coastguard Worker Commons Compress. In practice it is very likely that you'd 442*ba8755cbSAndroid Build Coastguard Worker run out of memory or your file system won't allow files that 443*ba8755cbSAndroid Build Coastguard Worker big long before you reach either limit.</p> 444*ba8755cbSAndroid Build Coastguard Worker 445*ba8755cbSAndroid Build Coastguard Worker <table> 446*ba8755cbSAndroid Build Coastguard Worker <thead> 447*ba8755cbSAndroid Build Coastguard Worker <tr> 448*ba8755cbSAndroid Build Coastguard Worker <th/> 449*ba8755cbSAndroid Build Coastguard Worker <th>Max. Size of Archive</th> 450*ba8755cbSAndroid Build Coastguard Worker <th>Max. Compressed/Uncompressed Size of Entry</th> 451*ba8755cbSAndroid Build Coastguard Worker <th>Max. Number of Entries</th> 452*ba8755cbSAndroid Build Coastguard Worker </tr> 453*ba8755cbSAndroid Build Coastguard Worker </thead> 454*ba8755cbSAndroid Build Coastguard Worker <tbody> 455*ba8755cbSAndroid Build Coastguard Worker <tr> 456*ba8755cbSAndroid Build Coastguard Worker <td>ZIP Format Without Zip 64 Extensions</td> 457*ba8755cbSAndroid Build Coastguard Worker <td>2<sup>32</sup> - 1 bytes ≈ 4.3 GB</td> 458*ba8755cbSAndroid Build Coastguard Worker <td>2<sup>32</sup> - 1 bytes ≈ 4.3 GB</td> 459*ba8755cbSAndroid Build Coastguard Worker <td>65535</td> 460*ba8755cbSAndroid Build Coastguard Worker </tr> 461*ba8755cbSAndroid Build Coastguard Worker <tr> 462*ba8755cbSAndroid Build Coastguard Worker <td>ZIP Format using Zip 64 Extensions</td> 463*ba8755cbSAndroid Build Coastguard Worker <td>2<sup>64</sup> - 1 bytes ≈ 18.5 EB</td> 464*ba8755cbSAndroid Build Coastguard Worker <td>2<sup>64</sup> - 1 bytes ≈ 18.5 EB</td> 465*ba8755cbSAndroid Build Coastguard Worker <td>2<sup>64</sup> - 1 ≈ 18.5 x 10<sup>18</sup></td> 466*ba8755cbSAndroid Build Coastguard Worker </tr> 467*ba8755cbSAndroid Build Coastguard Worker <tr> 468*ba8755cbSAndroid Build Coastguard Worker <td>Commons Compress 1.2 and earlier</td> 469*ba8755cbSAndroid Build Coastguard Worker <td>unlimited in <code>ZipArchiveInputStream</code> 470*ba8755cbSAndroid Build Coastguard Worker and <code>ZipArchiveOutputStream</code> and 471*ba8755cbSAndroid Build Coastguard Worker 2<sup>32</sup> - 1 bytes ≈ 4.3 GB 472*ba8755cbSAndroid Build Coastguard Worker in <code>ZipFile</code>.</td> 473*ba8755cbSAndroid Build Coastguard Worker <td>2<sup>32</sup> - 1 bytes ≈ 4.3 GB</td> 474*ba8755cbSAndroid Build Coastguard Worker <td>unlimited in <code>ZipArchiveInputStream</code>, 475*ba8755cbSAndroid Build Coastguard Worker 65535 in <code>ZipArchiveOutputStream</code> 476*ba8755cbSAndroid Build Coastguard Worker and <code>ZipFile</code>.</td> 477*ba8755cbSAndroid Build Coastguard Worker </tr> 478*ba8755cbSAndroid Build Coastguard Worker <tr> 479*ba8755cbSAndroid Build Coastguard Worker <td>Commons Compress 1.3 and later</td> 480*ba8755cbSAndroid Build Coastguard Worker <td>unlimited in <code>ZipArchiveInputStream</code> 481*ba8755cbSAndroid Build Coastguard Worker and <code>ZipArchiveOutputStream</code> and 482*ba8755cbSAndroid Build Coastguard Worker 2<sup>63</sup> - 1 bytes ≈ 9.2 EB 483*ba8755cbSAndroid Build Coastguard Worker in <code>ZipFile</code>.</td> 484*ba8755cbSAndroid Build Coastguard Worker <td>2<sup>63</sup> - 1 bytes ≈ 9.2 EB</td> 485*ba8755cbSAndroid Build Coastguard Worker <td>unlimited in <code>ZipArchiveInputStream</code>, 486*ba8755cbSAndroid Build Coastguard Worker 2<sup>31</sup> - 1 ≈ 2.1 billion 487*ba8755cbSAndroid Build Coastguard Worker in <code>ZipArchiveOutputStream</code> 488*ba8755cbSAndroid Build Coastguard Worker and <code>ZipFile</code>.</td> 489*ba8755cbSAndroid Build Coastguard Worker </tr> 490*ba8755cbSAndroid Build Coastguard Worker </tbody> 491*ba8755cbSAndroid Build Coastguard Worker </table> 492*ba8755cbSAndroid Build Coastguard Worker 493*ba8755cbSAndroid Build Coastguard Worker <h4>Known Interoperability Problems</h4> 494*ba8755cbSAndroid Build Coastguard Worker 495*ba8755cbSAndroid Build Coastguard Worker <p>The <code>java.util.zip</code> package of OpenJDK7 supports 496*ba8755cbSAndroid Build Coastguard Worker Zip 64 extensions but its <code>ZipInputStream</code> and 497*ba8755cbSAndroid Build Coastguard Worker <code>ZipFile</code> classes will be unable to extract 498*ba8755cbSAndroid Build Coastguard Worker archives created with Commons Compress 1.3's 499*ba8755cbSAndroid Build Coastguard Worker <code>ZipArchiveOutputStream</code> if the archive contains 500*ba8755cbSAndroid Build Coastguard Worker entries that use the data descriptor, are smaller than 4 GiB 501*ba8755cbSAndroid Build Coastguard Worker and have Zip 64 extensions enabled. I.e. the classes in 502*ba8755cbSAndroid Build Coastguard Worker OpenJDK currently only support archives that use Zip 64 503*ba8755cbSAndroid Build Coastguard Worker extensions only when they are actually needed. These classes 504*ba8755cbSAndroid Build Coastguard Worker are used to load JAR files and are the base for the 505*ba8755cbSAndroid Build Coastguard Worker <code>jar</code> command line utility as well.</p> 506*ba8755cbSAndroid Build Coastguard Worker </subsection> 507*ba8755cbSAndroid Build Coastguard Worker 508*ba8755cbSAndroid Build Coastguard Worker <subsection name="Consuming Archives Completely"> 509*ba8755cbSAndroid Build Coastguard Worker 510*ba8755cbSAndroid Build Coastguard Worker <p>Prior to version 1.5 <code>ZipArchiveInputStream</code> 511*ba8755cbSAndroid Build Coastguard Worker would return null from <code>getNextEntry</code> or 512*ba8755cbSAndroid Build Coastguard Worker <code>getNextZipEntry</code> as soon as the first central 513*ba8755cbSAndroid Build Coastguard Worker directory header of the archive was found, leaving the whole 514*ba8755cbSAndroid Build Coastguard Worker central directory itself unread inside the stream. Starting 515*ba8755cbSAndroid Build Coastguard Worker with version 1.5 <code>ZipArchiveInputStream</code> will try 516*ba8755cbSAndroid Build Coastguard Worker to read the archive up to and including the "end of central 517*ba8755cbSAndroid Build Coastguard Worker directory" record effectively consuming the archive 518*ba8755cbSAndroid Build Coastguard Worker completely.</p> 519*ba8755cbSAndroid Build Coastguard Worker 520*ba8755cbSAndroid Build Coastguard Worker </subsection> 521*ba8755cbSAndroid Build Coastguard Worker 522*ba8755cbSAndroid Build Coastguard Worker <subsection name="Symbolic Links" id="symlinks"> 523*ba8755cbSAndroid Build Coastguard Worker 524*ba8755cbSAndroid Build Coastguard Worker <p>Starting with Compress 1.5 <code>ZipArchiveEntry</code> 525*ba8755cbSAndroid Build Coastguard Worker recognizes Unix Symbolic Link entries written by InfoZIP's 526*ba8755cbSAndroid Build Coastguard Worker zip.</p> 527*ba8755cbSAndroid Build Coastguard Worker 528*ba8755cbSAndroid Build Coastguard Worker <p>The <code>ZipFile</code> class contains a convenience 529*ba8755cbSAndroid Build Coastguard Worker method to read the link name of an entry. Basically all it 530*ba8755cbSAndroid Build Coastguard Worker does is read the contents of the entry and convert it to 531*ba8755cbSAndroid Build Coastguard Worker a string using the given file name encoding of the 532*ba8755cbSAndroid Build Coastguard Worker archive.</p> 533*ba8755cbSAndroid Build Coastguard Worker 534*ba8755cbSAndroid Build Coastguard Worker </subsection> 535*ba8755cbSAndroid Build Coastguard Worker 536*ba8755cbSAndroid Build Coastguard Worker <subsection name="Parallel zip creation" id="parallel"> 537*ba8755cbSAndroid Build Coastguard Worker 538*ba8755cbSAndroid Build Coastguard Worker <p>Starting with Compress 1.10 there is now built-in support for 539*ba8755cbSAndroid Build Coastguard Worker parallel creation of zip archives</p> 540*ba8755cbSAndroid Build Coastguard Worker 541*ba8755cbSAndroid Build Coastguard Worker <p>Multiple threads can write 542*ba8755cbSAndroid Build Coastguard Worker to their own <code>ScatterZipOutputStream</code> 543*ba8755cbSAndroid Build Coastguard Worker instance that is backed to file or to some user-implemented form of 544*ba8755cbSAndroid Build Coastguard Worker storage (implementing <code>ScatterGatherBackingStore</code>).</p> 545*ba8755cbSAndroid Build Coastguard Worker 546*ba8755cbSAndroid Build Coastguard Worker <p>When the threads finish, they can join these streams together 547*ba8755cbSAndroid Build Coastguard Worker to a complete zip file using the <code>writeTo</code> method 548*ba8755cbSAndroid Build Coastguard Worker that will write a single <code>ScatterOutputStream</code> to a target 549*ba8755cbSAndroid Build Coastguard Worker <code>ZipArchiveOutputStream</code>.</p> 550*ba8755cbSAndroid Build Coastguard Worker 551*ba8755cbSAndroid Build Coastguard Worker <p>To assist this process, clients can use 552*ba8755cbSAndroid Build Coastguard Worker <code>ParallelScatterZipCreator</code> that will handle threads 553*ba8755cbSAndroid Build Coastguard Worker pools and correct memory model consistency so the client 554*ba8755cbSAndroid Build Coastguard Worker can avoid these issues. Please note that when writing well-formed 555*ba8755cbSAndroid Build Coastguard Worker Zip files this way, it is usually necessary to keep a 556*ba8755cbSAndroid Build Coastguard Worker separate <code>ScatterZipOutputStream</code> that receives all directories 557*ba8755cbSAndroid Build Coastguard Worker and writes this to the target <code>ZipArchiveOutputStream</code> before 558*ba8755cbSAndroid Build Coastguard Worker the ones created through <code>ParallelScatterZipCreator</code>. This is the responsibility of the client.</p> 559*ba8755cbSAndroid Build Coastguard Worker 560*ba8755cbSAndroid Build Coastguard Worker <p>There is no guarantee of order of the entries when writing a Zip 561*ba8755cbSAndroid Build Coastguard Worker file with <code>ParallelScatterZipCreator</code>.</p> 562*ba8755cbSAndroid Build Coastguard Worker 563*ba8755cbSAndroid Build Coastguard Worker See the examples section for a code sample demonstrating how to make a zip file. 564*ba8755cbSAndroid Build Coastguard Worker </subsection> 565*ba8755cbSAndroid Build Coastguard Worker 566*ba8755cbSAndroid Build Coastguard Worker </section> 567*ba8755cbSAndroid Build Coastguard Worker </body> 568*ba8755cbSAndroid Build Coastguard Worker</document> 569