svn commit: r1694895 - in /commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip: ZipArchiveEntry.java ZipArchiveInputStream.java

[bo...@apache.org]

Author: bodewig
Date: Sun Aug  9 16:06:09 2015
New Revision: 1694895

URL: http://svn.apache.org/r1694895
Log:
COMPRESS-318 document ZipArchiveInputStream's limitations in the javadocs

Modified:
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java
    commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveInputStream.java

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java?rev=1694895&r1=1694894&r2=1694895&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java (original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntry.java Sun Aug  9 16:06:09 2015
@@ -216,6 +216,10 @@ public class ZipArchiveEntry extends jav
     /**
      * Retrieves the internal file attributes.
      *
+     * <p><b>Note</b>: {@link ZipArchiveInputStream} is unable to fill
+     * this field, you must use {@link ZipFile} if you want to read
+     * entries using this attribute.</p>
+     *
      * @return the internal file attributes
      */
     public int getInternalAttributes() {
@@ -232,6 +236,11 @@ public class ZipArchiveEntry extends jav
 
     /**
      * Retrieves the external file attributes.
+     *
+     * <p><b>Note</b>: {@link ZipArchiveInputStream} is unable to fill
+     * this field, you must use {@link ZipFile} if you want to read
+     * entries using this attribute.</p>
+     *
      * @return the external file attributes
      */
     public long getExternalAttributes() {
@@ -321,6 +330,12 @@ public class ZipArchiveEntry extends jav
 
     /**
      * Retrieves all extra fields that have been parsed successfully.
+     *
+     * <p><b>Note</b>: The set of extra fields may be incomplete when
+     * {@link ZipArchiveInputStream} has been used as some extra
+     * fields use the central directory to store additional
+     * information.</p>
+     *
      * @return an array of the extra fields
      */
     public ZipExtraField[] getExtraFields() {
@@ -597,6 +612,11 @@ public class ZipArchiveEntry extends jav
 
     /**
      * Gets the uncompressed size of the entry data.
+     *
+     * <p><b>Note</b>: {@link ZipArchiveInputStream} may create
+     * entries that return {@link #SIZE_UNKNOWN SIZE_UNKNOWN} as long
+     * as the entry hasn't been read completely.</p>
+     *
      * @return the entry size
      */
     @Override

Modified: commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveInputStream.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveInputStream.java?rev=1694895&r1=1694894&r2=1694895&view=diff
==============================================================================
--- commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveInputStream.java (original)
+++ commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveInputStream.java Sun Aug  9 16:06:09 2015
@@ -43,16 +43,32 @@ import static org.apache.commons.compres
 /**
  * Implements an input stream that can read Zip archives.
  *
- * <p>Note that {@link ZipArchiveEntry#getSize()} may return -1 if the
- * DEFLATE algorithm is used, as the size information is not available
- * from the header.</p>
- *
- * <p>The {@link ZipFile} class is preferred when reading from files.</p>
- *
  * <p>As of Apache Commons Compress it transparently supports Zip64
  * extensions and thus individual entries and archives larger than 4
  * GB or with more than 65536 entries.</p>
  *
+ * <p>The {@link ZipFile} class is preferred when reading from files
+ * as {@link ZipArchiveInputStream} is limited by not being able to
+ * read the central directory header before returning entries.  In
+ * particular {@link ZipArchiveInputStream}</p>
+ *
+ * <ul>
+ *
+ *  <li>may return entries that are not part of the central directory
+ *  at all and shouldn't be considered part of the archive.</li>
+ *
+ *  <li>may return several entries with the same name.</li>
+ *
+ *  <li>will not return internal or external attributes.</li>
+ *
+ *  <li>may return incomplete extra field data.</li>
+ *
+ *  <li>may return unknown sizes and CRC values for entries until the
+ *  next entry has been reached if the archive uses the data
+ *  descriptor feature.</li>
+ *
+ * </ul>
+ *
  * @see ZipFile
  * @NotThreadSafe
  */