Author: bodewig
Date: Tue Aug 9 06:25:18 2011
New Revision: 1155223
URL: http://svn.apache.org/viewvc?rev=1155223&view=rev
Log:
Document UseZip64-API of ZipArchiveOutputStream that I intend to implement
Added:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64Mode.java
(with props)
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64RequiredException.java
(with props)
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveOutputStream.java
commons/proper/compress/trunk/src/test/java/org/apache/commons/compress/AbstractTestCase.java
Added:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64Mode.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64Mode.java?rev=1155223&view=auto
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64Mode.java
(added)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64Mode.java
Tue Aug 9 06:25:18 2011
@@ -0,0 +1,47 @@
+/*
+ * 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.
+ *
+ */
+
+package org.apache.commons.compress.archivers.zip;
+
+/**
+ * The different modes {@link ZipArchiveOutputStream} can operate in.
+ *
+ * @see ZipArchiveOutputStream#setUseZip64
+ *
+ * @since Apache Commons Compress 1.3
+ */
+public enum Zip64Mode {
+ /**
+ * Use Zip64 extensions for all entries, even if it is clear it is
+ * not required.
+ */
+ Always,
+ /**
+ * Don't use Zip64 extensions for any entries.
+ *
+ * <p>This will cause a {@link Zip64RequiredException} to be
+ * thrown if {@link ZipArchiveOutputStream} detects it needs Zip64
+ * support.</p>
+ */
+ Never,
+ /**
+ * Use Zip64 extensions for all entries where they are required,
+ * don't use them for entries that clearly don't require them.
+ */
+ AsNeeded
+}
Propchange:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64Mode.java
------------------------------------------------------------------------------
svn:eol-style = native
Added:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64RequiredException.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64RequiredException.java?rev=1155223&view=auto
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64RequiredException.java
(added)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64RequiredException.java
Tue Aug 9 06:25:18 2011
@@ -0,0 +1,36 @@
+/*
+ * 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.
+ *
+ */
+
+package org.apache.commons.compress.archivers.zip;
+
+import java.util.zip.ZipException;
+
+/**
+ * Exception thrown when attempting to write data that requires Zip64
+ * support to an archive and {@link ZipArchiveOutputStream#setUseZip64
+ * UseZip64} has been set to {@link Zip64Mode#Never Never}.
+ * @since Apache Commons Compress 1.3
+ */
+public class Zip64RequiredException extends ZipException {
+
+ private static final long serialVersionUID = 20110809L;
+
+ public Zip64RequiredException(String reason) {
+ super(reason);
+ }
+}
Propchange:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/Zip64RequiredException.java
------------------------------------------------------------------------------
svn:eol-style = native
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveOutputStream.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveOutputStream.java?rev=1155223&r1=1155222&r2=1155223&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveOutputStream.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveOutputStream.java
Tue Aug 9 06:25:18 2011
@@ -236,6 +236,8 @@ public class ZipArchiveOutputStream exte
*/
private boolean hasUsedZip64 = false;
+ private Zip64Mode zip64Mode = Zip64Mode.AsNeeded;
+
/**
* Creates a new ZIP OutputStream filtering the underlying stream.
* @param out the outputstream to zip
@@ -340,6 +342,54 @@ public class ZipArchiveOutputStream exte
fallbackToUTF8 = b;
}
+ /**
+ * Whether Zip64 extensions will be used.
+ *
+ * <p>When setting the mode to {@link Zip64Mode#Never Never},
+ * {@link #putArchiveEntry}, {@link #closeArchiveEntry}, {@link
+ * #finish} or {@link #close} may throw a {@link
+ * Zip64RequiredException} if the entry's size or the total size
+ * of the archive exceeds 4GB or there are more than 65536 entries
+ * inside the archive. Any archive created in this mode will be
+ * readable by implementations that don't support Zip64.</p>
+ *
+ * <p>When setting the mode to {@link Zip64Mode#Always Always},
+ * Zip64 extensions will be used for all entries. Any archive
+ * created in this mode may be unreadable by implementations that
+ * don't support Zip64 even if all its contents would be.</p>
+ *
+ * <p>When setting the mode to {@link Zip64Mode#AsNeeded
+ * AsNeeded}, Zip64 extensions will transparently be used for
+ * those entries that require them. This mode can only be used if
+ * the uncompressed size of the {@link ZipArchiveEntry} is known
+ * when calling {@link #putArchiveEntry} or the archive is written
+ * to a seekable output (i.e. you have used the {@link
+ * #ZipArchiveOutputStream(java.io.File) File-arg constructor}) -
+ * this mode is not valid when the output stream is not seekable
+ * and the uncompressed size is unknown when {@link
+ * #putArchiveEntry} is called.</p>
+ *
+ * <p>If no entry inside the resulting archive requires Zip64
+ * extensions then {@link Zip64Mode#Never Never} will create the
+ * smallest archive. {@link Zip64Mode#AsNeeded AsNeeded} will
+ * create a slightly bigger archive if the uncompressed size of
+ * any entry has initially been unknown and create an archive
+ * identical to {@link Zip64Mode#Never Never} otherwise. {@link
+ * Zip64Mode#Always Always} will create an archive that is at
+ * least 20 bytes per entry bigger than the one {@link
+ * Zip64Mode#Never Never} would create.</p>
+ *
+ * <p>Defaults to {@link Zip64Mode#AsNeeded AsNeeded} unless
+ * {@link #putArchiveEntry} is called with an entry of unknown
+ * size and data is written to a non-seekable stream - in this
+ * case the default is {@link Zip64Mode#Never Never}.</p>
+ *
+ * @since Apache Commons Compress 1.3
+ */
+ public void setUseZip64(Zip64Mode mode) {
+ zip64Mode = mode;
+ }
+
/** {@inheritDoc} */
@Override
public void finish() throws IOException {
Modified:
commons/proper/compress/trunk/src/test/java/org/apache/commons/compress/AbstractTestCase.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/test/java/org/apache/commons/compress/AbstractTestCase.java?rev=1155223&r1=1155222&r2=1155223&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/test/java/org/apache/commons/compress/AbstractTestCase.java
(original)
+++
commons/proper/compress/trunk/src/test/java/org/apache/commons/compress/AbstractTestCase.java
Tue Aug 9 06:25:18 2011
@@ -226,7 +226,7 @@ public abstract class AbstractTestCase e
OutputStream stream = null;
archiveList = new ArrayList<String>();
try {
- archive = File.createTempFile("empty", "." + archivename);
+ archive =File.createTempFile("empty", "." + archivename);
stream = new FileOutputStream(archive);
out = factory.createArchiveOutputStream(archivename, stream);
// Use short file name so does not cause problems for ar
