← Back to branch summary

~ubuntu-branches/ubuntu/saucy/libcommons-compress-java/saucy-proposed

« back to all changes in this revision

Viewing changes to src/site/xdoc/zip.xml

  • Committer: Bazaar Package Importer
  • Author(s): Torsten Werner
  • Date: 2011-08-07 01:56:15 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20110807015615-cvbmhuv10g12fpz1
Tags: 1.2-1
* New upstream release
* Clean up Depends and Suggests fields.
* Switch to source format 3.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/site/xdoc/zip.xml
30
30
 
31
31
      <ul>
32
32
        <li>Support for encodings other than UTF-8 for filenames and
33
 
          comments.</li>
 
33
          comments.  Starting with Java7 this is supported
 
34
          by <code>java.util.zip</code> as well.</li>
34
35
        <li>Access to internal and external attributes (which are used
35
36
          to store Unix permission by some zip implementations).</li>
36
37
        <li>Structured support for extra fields.</li>
81
82
          first and provide correct and complete information on any
82
83
          ZIP archive.</p>
83
84
 
 
85
        <p>ZIP archives know a feature called the data descriptor
 
86
          which is a way to store an entry's length after the entry's
 
87
          data.  This can only work reliably if the size information
 
88
          can be taken from the central directory or the data itself
 
89
          can signal it is complete, which is true for data that is
 
90
          compressed using the DEFLATED compression algorithm.</p>
 
91
 
 
92
        <p><code>ZipFile</code> has access to the central directory
 
93
          and can extract entries using the data descriptor reliably.
 
94
          The same is true for <code>ZipArchiveInputStream</code> as
 
95
          long as the entry is DEFLATED.  For STORED
 
96
          entries <code>ZipArchiveInputStream</code> can try to read
 
97
          ahead until it finds the next entry, but this approach is
 
98
          not safe and has to be enabled by a constructor argument
 
99
          explicitly.</p>
 
100
 
84
101
        <p>If possible, you should always prefer <code>ZipFile</code>
85
102
          over <code>ZipArchiveInputStream</code>.</p>
 
103
 
86
104
      </subsection>
87
105
 
88
106
      <subsection name="Extra Fields">
99
117
          the package, any other extra field will be stored
100
118
          as <code>UnrecognizedExtraField</code>.</p>
101
119
 
 
120
        <p>Prior to version 1.1 of this library trying to read an
 
121
          archive with extra fields that didn't follow the recommended
 
122
          structure for those fields would cause Compress to throw an
 
123
          exception.  Starting with version 1.1 these extra fields
 
124
          will now be read
 
125
          as <code>UnparseableExtraFieldData</code>.</p>
 
126
 
102
127
      </subsection>
103
128
 
104
129
      <subsection name="Encoding" id="encoding">
171
196
            names, it doesn't set or recognize any flags or Unicode
172
197
            extra fields.</li>
173
198
 
 
199
          <li>Starting with Java7 <code>java.util.zip</code> writes
 
200
            UTF-8 by default and uses the language encoding flag.  It
 
201
            is possible to specify a different encoding when
 
202
            reading/writing ZIPs via new constructors.  The package
 
203
            now recognizes the language encoding flag when reading and
 
204
            ignores the Unicode extra fields.</li>
 
205
 
174
206
          <li>7Zip writes CodePage 437 by default but uses UTF-8 and
175
207
            the language encoding flag when writing entries that
176
208
            cannot be encoded as CodePage 437 (similar to the zip task
202
234
        <p>If you are creating jars, then java.util.zip is your main
203
235
          consumer.  We recommend you set the encoding to UTF-8 and
204
236
          keep the language encoding flag enabled.  The flag won't
205
 
          help or hurt java.util.zip but archivers that support it
206
 
          will show the correct file names.</p>
 
237
          help or hurt java.util.zip prior to Java7 but archivers that
 
238
          support it will show the correct file names.</p>
207
239
 
208
240
        <p>For maximum interop it is probably best to set the encoding
209
241
          to UTF-8, enable the language encoding flag and create
221
253
          extract the file names correctly.</p>
222
254
      </subsection>
223
255
 
 
256
      <subsection name="Encryption and Alternative Compression Algorithms"
 
257
                  id="encryption">
 
258
        
 
259
        <p>In most cases entries of an archive are not encrypted and
 
260
        are either not compressed at all or use the DEFLATED
 
261
        algorithm, Commons Compress' ZIP archiver will handle them
 
262
        just fine.</p>
 
263
 
 
264
        <p>The ZIP specification allows for various other compression
 
265
        algorithms and also supports several different ways of
 
266
        encrypting archive contents.  Neither of those methods is
 
267
        currently supported by Commons Compress and any such entry can
 
268
        not be extracted by the archiving code.</p>
 
269
 
 
270
        <p><code>ZipFile</code>'s and
 
271
        <code>ZipArchiveInputStream</code>'s
 
272
        <code>canReadEntryData</code> methods will return false for
 
273
        encrypted entries or entries using an unsupported encryption
 
274
        mechanism.  Using this method it is possible to at least
 
275
        detect and skip the entries that can not be extracted.</p>
 
276
 
 
277
      </subsection>
224
278
    </section>
225
279
  </body>
226
280
</document>