commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject [commons-compress] 02/02: COMPRESS-477 document split archive support
Date Mon, 30 Dec 2019 05:57:31 GMT
This is an automated email from the ASF dual-hosted git repository.

bodewig pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-compress.git

commit 57664d9170aa153020488771eaee77f1c1550182
Author: Stefan Bodewig <bodewig@apache.org>
AuthorDate: Mon Dec 30 06:56:17 2019 +0100

    COMPRESS-477 document split archive support
    
    see #86 and #84
---
 src/changes/changes.xml       |  4 ++++
 src/site/xdoc/index.xml       |  1 +
 src/site/xdoc/limitations.xml |  8 ++++++-
 src/site/xdoc/zip.xml         | 53 ++++++++++++++++++++++++++++++++++++++++---
 4 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index ec4b18a..a4a3728 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -74,6 +74,10 @@ The <action> type attribute can be add,update,fix,remove.
               due-to="Peter Alfred Lee">
         Added random access support to SevenZFile.
       </action>
+      <action issue="COMPRESS-477" type="update" date="2019-12-15"
+              due-to="Peter Alfred Lee">
+        Added support for split ZIP archives.
+      </action>
     </release>
     <release version="1.19" date="2019-08-27"
              description="Release 1.19
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
index 8b57f03..9a7cddf 100644
--- a/src/site/xdoc/index.xml
+++ b/src/site/xdoc/index.xml
@@ -62,6 +62,7 @@
             <ul>
               <li><code>SevenZFile</code> now supports random
               access.</li>
+              <li>The zip package now supports split archives.</li>
             </ul>
           </subsection>
         </section>
diff --git a/src/site/xdoc/limitations.xml b/src/site/xdoc/limitations.xml
index ada85ab..4c8f6d4 100644
--- a/src/site/xdoc/limitations.xml
+++ b/src/site/xdoc/limitations.xml
@@ -204,7 +204,13 @@
          <li>only a subset of compression methods are supported,
          including the most common STORED and DEFLATEd.  IMPLODE,
          SHRINK, DEFLATE64 and BZIP2 support is read-only.</li>
-         <li>no support for encryption or multi-volume archives</li>
+         <li>no support for encryption</li>
+         <li> or multi-volume archives prior to Compress 1.20</li>
+         <li>It is currently not possible to write split archives with
+         more than 64k segments. When creating split archives with more
+         than 100 segments you will need to adjust the file names as
+         <code>ZipArchiveOutputStream</code> assumes extensions will be
+         three characters long.</li>
          <li>In versions prior to Compress 1.6
          <code>ZipArchiveEntries</code> read from an archive will
          contain non-zero millisecond values when using Java 8 or later rather
diff --git a/src/site/xdoc/zip.xml b/src/site/xdoc/zip.xml
index 2653431..29ea971 100644
--- a/src/site/xdoc/zip.xml
+++ b/src/site/xdoc/zip.xml
@@ -122,10 +122,19 @@
       </subsection>
 
       <subsection name="ZipArchiveOutputStream" id="ZipArchiveOutputStream">
-        <p><code>ZipArchiveOutputStream</code> has three constructors,
-        one of them uses a <code>File</code> argument, one a
+        <p><code>ZipArchiveOutputStream</code> has four constructors,
+        two of them uses a <code>File</code> argument, one a
         <code>SeekableByteChannel</code> and the last uses an
-        <code>OutputStream</code>.  The <code>File</code> version
will
+        <code>OutputStream</code>.</p>
+
+        <p>The constructor accepting a <code>File</code> and a size is
+        used exclusively for creating a split ZIP archive and is
+        described in th next section. For the remainder of this
+        section this constructor is equivalent to the one using the
+        <code>OutputStream</code> argument and thus it is not possible
+        to add uncompressed entries of unknown size.</p>
+
+        <p>Of the remaining three constructors the <code>File</code> version
will
         try to use <code>SeekableByteChannel</code> and fall back to
         using a <code>FileOutputStream</code> internally if that
         fails.</p>
@@ -147,6 +156,44 @@
 
       </subsection>
 
+      <subsection name="Multi Volume Archives">
+        <p>The ZIP format knows so called split and spanned
+        archives. Spanned archives cross several removable media and
+        are not supported by Commons Compress.</p>
+
+        <p>Split archives consist of multiple files that reside in the
+        same directory with the same base name (the file name without
+        the file extension). The last file of the the archive has the
+        extension <code>zip</code> the remaining files conventionally
+        use extensions <code>z01</code>, <code>z02</code> and so
+        on. Support for splitted archives has been added with Compress
+        1.20.</p>
+
+        <p>If you want to create a split ZIP archive you use the
+        constructor of <code>ZipArchiveOutputStream</code> that
+        accepts a <code>File</code> argument and a size. The size
+        determines the maximum size of a split segment - the size must
+        be between 64kB and 4GB. While creating the archive, this will
+        create several files fillowing the naming convention described
+        above. The name of the <code>File</code> argument used inside
+        of the constructor must use the extension
+        <code>zip</code>.</p>
+
+        <p>It is currently not possible to write split archives with
+        more than 64k segments. When creating split archives with more
+        than 100 segments you will need to adjust the file names as
+        <code>ZipArchiveOutputStream</code> assumes extensions will be
+        three characters long.</p>
+
+        <p>If you want to read a split archive you must create a
+        <code>ZipSplitReadOnlySeekableByteChannel</code> from the
+        parts. Both <code>ZipFile</code> and
+        <code>ZipArchiveInputStream</code> support reading streams of
+        this type, in the case of <code>ZipArchiveInputStream</code>
+        you need to use a constructor where you can set
+        <code>skipSplitSig</code> to true.</p>
+      </subsection>
+
       <subsection name="Extra Fields">
 
         <p>Inside a ZIP archive, additional data can be attached to


Mime
View raw message