harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ndbe...@apache.org
Subject svn commit: r768128 [2/2] - in /harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util: jar/ zip/
Date Fri, 24 Apr 2009 02:23:50 GMT
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Deflater.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Deflater.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Deflater.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Deflater.java Fri Apr 24 02:23:48 2009
@@ -20,36 +20,60 @@
 import org.apache.harmony.luni.platform.OSResourcesMonitor;
 
 /**
- * The Deflater class is used to compress bytes using the DEFLATE compression
- * algorithm. Deflation is performed by the ZLIB compression library.
- * 
+ * This class compresses data using the <i>DEFLATE</i> algorithm (see <a
+ * href="http://www.gzip.org/algorithm.txt">specification</a>).
+ * <p>
+ * Basically this class is part of the API to the stream based ZLIB compression
+ * library and is used as such by {@code DeflaterOutputStream} and its
+ * descendants.
+ * <p>
+ * The typical usage of a {@code Deflater} instance outside this package
+ * consists of a specific call to one of its constructors before being passed to
+ * an instance of {@code DeflaterOutputStream}.
+ *
  * @see DeflaterOutputStream
  * @see Inflater
  */
 public class Deflater {
 
-    /** Constant value representing the best available compression level. */
+    /**
+     * Upper bound for the compression level range.
+     */
     public static final int BEST_COMPRESSION = 9;
 
-    /** Constant value representing the fastest available compression level. */
+    /**
+     * Lower bound for compression level range.
+     */
     public static final int BEST_SPEED = 1;
 
-    /** Constant value representing the default compression level. */
+    /**
+     * Usage of the default compression level.
+     */
     public static final int DEFAULT_COMPRESSION = -1;
 
-    /** Constant value representing the default compression strategy. */
+    /**
+     * Default value for compression strategy.
+     */
     public static final int DEFAULT_STRATEGY = 0;
 
-    /** Constant value representing the deflate compression strategy. */
+    /**
+     * Default value for compression method.
+     */
     public static final int DEFLATED = 8;
 
-    /** Constant value representing the filtered compression strategy. */
+    /**
+     * Possible value for compression strategy.
+     */
     public static final int FILTERED = 1;
 
-    /** Constant value representing the Huffman compression strategy. */
+    /**
+     * Possible value for compression strategy.
+     */
     public static final int HUFFMAN_ONLY = 2;
 
-    /** Constant value representing the no compression strategy. */
+    /**
+     * Possible value for compression level.
+     */
     public static final int NO_COMPRESSION = 0;
 
     private static final int Z_NO_FLUSH = 0;
@@ -84,35 +108,38 @@
     private int inLength;
 
     /**
-     * Constructs a new Deflater instance with default compression level and
-     * strategy.
+     * Constructs a new {@code Deflater} instance with default compression
+     * level. The strategy can be specified with {@link #setStrategy}, only. A
+     * header is added to the output by default; use constructor {@code
+     * Deflater(level, boolean)} if you need to omit the header.
      */
     public Deflater() {
         this(DEFAULT_COMPRESSION, false);
     }
 
     /**
-     * Constructs a new Deflater instance with compression level level and
-     * default compression strategy. THe compression level provided must be
-     * between 0 and 9.
+     * Constructs a new {@code Deflater} instance with a specific compression
+     * level. The strategy can be specified with {@code setStrategy}, only. A
+     * header is added to the output by default; use
+     * {@code Deflater(level, boolean)} if you need to omit the header.
      * 
      * @param level
-     *            the compression level to use
+     *            the compression level in the range between 0 and 9.
      */
     public Deflater(int level) {
         this(level, false);
     }
 
     /**
-     * Constructs a new Deflater instance with compression level level and
-     * default compression strategy. If the noHeader parameter is specified then
-     * no ZLIB header will be written as part of the compressed output. The
-     * compression level specified must be between 0 and 9.
+     * Constructs a new {@code Deflater} instance with a specific compression
+     * level. If noHeader is passed as true no ZLib header is added to the
+     * output. In a ZIP archive every entry (compressed file) comes with such a
+     * header. The strategy can be specified with the setStrategy method, only.
      * 
      * @param level
-     *            the compression level to use
+     *            the compression level in the range between 0 and 9.
      * @param noHeader
-     *            if true do not write the ZLIB header
+     *            {@code true} indicates that no ZLIB header should be written.
      */
     public Deflater(int level, boolean noHeader) {
         super();
@@ -125,31 +152,29 @@
     }
 
     /**
-     * Deflates data into the supplied buffer
+     * Deflates the data (previously passed to {@code setInput}) into the
+     * supplied buffer.
      * 
      * @param buf
-     *            buffer to store compressed data
-     * 
-     * @return number of bytes of compressed data stored
-     * 
+     *            buffer to write compressed data to.
+     * @return number of bytes of compressed data written to {@code buf}.
+     * @see #deflate(byte[], int, int)
      */
     public int deflate(byte[] buf) {
         return deflate(buf, 0, buf.length);
     }
 
     /**
-     * Deflates data into the supplied buffer using the region from off to
-     * nbytes - 1.
+     * Deflates data (previously passed to {@code setInput}) into a specific
+     * region within the supplied buffer.
      * 
      * @param buf
-     *            buffer to store compressed data
+     *            the buffer to write compressed data to.
      * @param off
-     *            offset inf buf to start storing data
+     *            the offset within {@code buf} at which to start writing to.
      * @param nbytes
-     *            number of bytes of compressed data to store in buf
-     * 
-     * @return number of bytes of compressed data stored
-     * 
+     *            maximum number of bytes of compressed data to be written.
+     * @return the number of bytes of compressed data written to {@code buf}.
      */
     public synchronized int deflate(byte[] buf, int off, int nbytes) {
         if (streamHandle == -1) {
@@ -173,10 +198,11 @@
     private synchronized native void endImpl(long handle);
 
     /**
-     * Frees all resources held onto by this Deflater. Any unused input or
-     * output is discarded. This is also called from the finalize method.
-     * 
-     * @see #finalize
+     * Frees all resources held onto by this deflating algorithm. Any unused
+     * input or output is discarded. While this method is used by {@code
+     * finalize()}, it can be called explicitly in order to free native
+     * resources before the next GC cycle. After {@code end()} was called other
+     * methods will typically throw an {@code IllegalStateException}.
      */
     public synchronized void end() {
         if (streamHandle != -1) {
@@ -192,10 +218,10 @@
     }
 
     /**
-     * Indicates to the Deflater that all uncompressed input has been provided
+     * Indicates to the {@code Deflater} that all uncompressed input has been provided
      * to it.
      * 
-     * @see #finished()
+     * @see #finished
      */
     public synchronized void finish() {
         flushParm = Z_FINISH;
@@ -205,7 +231,7 @@
      * Returns whether or not all provided data has been successfully
      * compressed.
      * 
-     * @return true if all data has been compressed, false otherwise
+     * @return true if all data has been compressed, false otherwise.
      */
     public synchronized boolean finished() {
         return finished;
@@ -216,9 +242,8 @@
      * preset dictionary is used getAdler() will return the Adler32 checksum of
      * the dictionary used.
      * 
-     * @return The Adler32 checksum of uncompressed data or preset dictionary if
-     *         used
-     * 
+     * @return the Adler32 checksum of uncompressed data or preset dictionary if
+     *         used.
      * @see #setDictionary(byte[])
      * @see #setDictionary(byte[], int, int)
      */
@@ -233,7 +258,7 @@
     private synchronized native int getAdlerImpl(long handle);
 
     /**
-     * Returns the total number of bytes of input consumed by the deflater.
+     * Returns the total number of bytes of input consumed by the {@code Deflater}.
      * 
      * @return number of bytes of input read.
      */
@@ -248,7 +273,7 @@
     private synchronized native long getTotalInImpl(long handle);
 
     /**
-     * Returns the total number of compressed bytes output by this Deflater.
+     * Returns the total number of compressed bytes output by this {@code Deflater}.
      * 
      * @return number of compressed bytes output.
      */
@@ -263,14 +288,14 @@
     private synchronized native long getTotalOutImpl(long handle);
 
     /**
-     * Indicates whether or not all bytes of uncompressed input have been
-     * consumed by the Deflater. If needsInput() answers true setInput() must be
-     * called before deflation can continue. If all bytes of uncompressed data
-     * have been provided to the Deflater finish() must be called to ensure the
-     * compressed data is output.
+     * Counterpart to setInput(). Indicates whether or not all bytes of
+     * uncompressed input have been consumed by the {@code Deflater}. If needsInput()
+     * returns true setInput() must be called before deflation can continue. If
+     * all bytes of uncompressed data have been provided to the {@code Deflater}
+     * finish() must be called to ensure the compressed data is output.
      * 
-     * @return True if input is required for deflation to continue, false
-     *         otherwise
+     * @return {@code true} if input is required for deflation to continue,
+     *         {@code false} otherwise.
      * @see #finished()
      * @see #setInput(byte[])
      * @see #setInput(byte[], int, int)
@@ -283,12 +308,12 @@
     }
 
     /**
-     * Resets the <code>Deflater</code> to accept new input without affecting
-     * any previously made settings for the compression strategy or level. This
-     * operation <i>must</i> be called after <code>finished()</code> returns
-     * <code>true</code> if the <code>Deflater</code> is to be reused.
+     * Resets the {@code Deflater} to accept new input without affecting any
+     * previously made settings for the compression strategy or level. This
+     * operation <i>must</i> be called after {@code finished()} returns
+     * {@code true} if the {@code Deflater} is to be reused.
      * 
-     * @see #finished()
+     * @see #finished
      */
     public synchronized void reset() {
         if (streamHandle == -1) {
@@ -304,30 +329,31 @@
     private synchronized native void resetImpl(long handle);
 
     /**
-     * Defines a dictionary to be used for compression by the receiver.
+     * Sets the dictionary to be used for compression by this {@code Deflater}.
+     * setDictionary() can only be called if this {@code Deflater} supports the writing
+     * of ZLIB headers. This is the default behaviour but can be overridden
+     * using {@code Deflater(int, boolean)}.
      * 
      * @param buf
-     *            the entire set of bytes comprising the dictionary
-     * @see #setDictionary(byte[], int, int)
+     *            the buffer containing the dictionary data bytes.
+     * @see Deflater#Deflater(int, boolean)
      */
     public void setDictionary(byte[] buf) {
         setDictionary(buf, 0, buf.length);
     }
 
     /**
-     * Sets the dictionary to be used for compression by this Deflater.
-     * 
-     * <code>setDictionary()</code> can only be called if this Deflater
-     * supports the writing of ZLIB headers. This is the default behaviour but
-     * can be overridden using <code>Deflater(int, boolean)</code>.
-     * 
+     * Sets the dictionary to be used for compression by this {@code Deflater}.
+     * setDictionary() can only be called if this {@code Deflater} supports the writing
+     * of ZLIB headers. This is the default behaviour but can be overridden
+     * using {@code Deflater(int, boolean)}.
+     *
      * @param buf
-     *            the byte array containing the dictionary
+     *            the buffer containing the dictionary data bytes.
      * @param off
-     *            offset into the byte array
+     *            the offset of the data.
      * @param nbytes
-     *            number of bytes comprising the dictionary
-     * 
+     *            the length of the data.
      * @see Deflater#Deflater(int, boolean)
      */
     public synchronized void setDictionary(byte[] buf, int off, int nbytes) {
@@ -347,27 +373,27 @@
             int nbytes, long handle);
 
     /**
-     * Sets the input buffer the Deflater will use to extract uncompressed bytes
+     * Sets the input buffer the {@code Deflater} will use to extract uncompressed bytes
      * for later compression.
      * 
      * @param buf
-     *            the input buffer
+     *            the buffer.
      */
     public void setInput(byte[] buf) {
         setInput(buf, 0, buf.length);
     }
 
     /**
-     * Sets the input buffer the Deflater will use to extract uncompressed bytes
+     * Sets the input buffer the {@code Deflater} will use to extract uncompressed bytes
      * for later compression. Input will be taken from the buffer region
      * starting at off and ending at nbytes - 1.
      * 
      * @param buf
-     *            the input data byte array
+     *            the buffer containing the input data bytes.
      * @param off
-     *            offset into the input bytes
+     *            the offset of the data.
      * @param nbytes
-     *            number of valid bytes in the input array
+     *            the length of the data.
      */
     public synchronized void setInput(byte[] buf, int off, int nbytes) {
         if (streamHandle == -1) {
@@ -436,12 +462,12 @@
     }
 
     /**
-     * Returns a long int of total number of bytes read by the Deflater. This
-     * method performs the same as getTotalIn except it returns a long value
+     * Returns a long int of total number of bytes read by the {@code Deflater}. This
+     * method performs the same as {@code getTotalIn} except it returns a long value
      * instead of an integer
      * 
      * @see #getTotalIn()
-     * @return bytes exactly read by deflater
+     * @return total number of bytes read by {@code Deflater}.
      */
     public synchronized long getBytesRead() {
         // Throw NPE here
@@ -452,12 +478,12 @@
     }
 
     /**
-     * Returns a long int of total number of bytes of read by the Deflater. This
-     * method performs the same as getTotalOut except it returns a long value
-     * instead of an integer
+     * Returns a long int of total number of bytes of read by the {@code Deflater}. This
+     * method performs the same as {@code getTotalOut} except it returns a long
+     * value instead of an integer
      * 
      * @see #getTotalOut()
-     * @return bytes exactly write by deflater
+     * @return bytes exactly write by {@code Deflater}
      */
     public synchronized long getBytesWritten() {
         // Throw NPE here

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java Fri Apr 24 02:23:48 2009
@@ -24,54 +24,68 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * The DeflaterOutputStream class implements a stream filter for the writing of
- * compressed data to a stream. Compression is performed by an instance of
- * Deflater.
+ * This class provides an implementation of {@code FilterOutputStream} that
+ * compresses data using the <i>DEFLATE</i> algorithm. Basically it wraps the
+ * {@code Deflater} class and takes care of the buffering.
+ *
+ * @see Deflater
  */
 public class DeflaterOutputStream extends FilterOutputStream {
     static final int BUF_SIZE = 512;
 
+    /**
+     * The buffer for the data to be written to.
+     */
     protected byte[] buf;
 
+    /**
+     * The deflater used.
+     */
     protected Deflater def;
 
     boolean done = false;
 
     /**
-     * Constructs a new DeflaterOutputStream instance using os as the underlying
-     * stream. The provided Deflater instance will be used to compress data.
+     * This constructor lets you pass the {@code Deflater} specifying the
+     * compression algorithm.
      * 
      * @param os
-     *            OutputStream to receive compressed data
+     *            is the {@code OutputStream} where to write the compressed data
+     *            to.
      * @param def
-     *            Deflater to perform compression
+     *            is the specific {@code Deflater} that is used to compress
+     *            data.
      */
     public DeflaterOutputStream(OutputStream os, Deflater def) {
         this(os, def, BUF_SIZE);
     }
 
     /**
-     * Constructs a new DeflaterOutputStream instance using os as the underlying
+     * This is the most basic constructor. You only need to pass the {@code
+     * OutputStream} to which the compressed data shall be written to. The
+     * default settings for the {@code Deflater} and internal buffer are used.
+     * In particular the {@code Deflater} produces a ZLIB header in the output
      * stream.
      * 
      * @param os
-     *            OutputStream to receive compressed data
+     *            is the OutputStream where to write the compressed data to.
      */
     public DeflaterOutputStream(OutputStream os) {
         this(os, new Deflater());
     }
 
     /**
-     * Constructs a new DeflaterOutputStream instance using os as the underlying
-     * stream. The provided Deflater instance will be used to compress data. The
-     * internal buffer for storing compressed data will be of size bsize.
+     * This constructor lets you specify both the compression algorithm as well
+     * as the internal buffer size to be used.
      * 
      * @param os
-     *            OutputStream to receive compressed data
+     *            is the {@code OutputStream} where to write the compressed data
+     *            to.
      * @param def
-     *            Deflater to perform compression
+     *            is the specific {@code Deflater} that will be used to compress
+     *            data.
      * @param bsize
-     *            size of internal compression buffer
+     *            is the size to be used for the internal buffer.
      */
     public DeflaterOutputStream(OutputStream os, Deflater def, int bsize) {
         super(os);
@@ -89,8 +103,8 @@
      * Compress the data in the input buffer and write it to the underlying
      * stream.
      * 
-     * @exception java.io.IOException
-     *                If an error occurs during deflation.
+     * @throws IOException
+     *             If an error occurs during deflation.
      */
     protected void deflate() throws IOException {
         int x = 0;
@@ -105,8 +119,9 @@
      * all underlying streams. This stream can no longer be used after close()
      * has been called.
      * 
-     * @exception java.io.IOException
-     *                If an error occurs during close.
+     * @throws IOException
+     *             If an error occurs while closing the data compression
+     *             process.
      */
     @Override
     public void close() throws IOException {
@@ -118,12 +133,11 @@
     }
 
     /**
-     * Write any unwritten data to the underlying stream. Do not close the
-     * stream. This allows subsequent Deflater's to write to the same stream.
-     * This Deflater cannot be used again.
+     * Writes any unwritten data to the underlying stream. Does not close the
+     * stream.
      * 
-     * @exception java.io.IOException
-     *                If an error occurs.
+     * @throws IOException
+     *             If an error occurs.
      */
     public void finish() throws IOException {
         if (done) {
@@ -149,17 +163,17 @@
     }
 
     /**
-     * Compress data from a buffer and write it to the underlying stream.
+     * Compresses {@code nbytes} of data from {@code buf} starting at
+     * {@code off} and writes it to the underlying stream.
      * 
      * @param buffer
-     *            Buffer of data to compress
+     *            the buffer of data to compress.
      * @param off
-     *            offset in buffer to extract data from
+     *            offset in buffer to extract data from.
      * @param nbytes
-     *            Number of bytes of data to compress and write
-     * 
-     * @exception IOException
-     *                If an error occurs during writing.
+     *            the number of bytes of data to read from the buffer.
+     * @throws IOException
+     *             If an error occurs during writing.
      */
     @Override
     public void write(byte[] buffer, int off, int nbytes) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java Fri Apr 24 02:23:48 2009
@@ -24,7 +24,9 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * The GZIPInputStream class is used to read data stored in the GZIP format.
+ * The {@code GZIPInputStream} class is used to read data stored in the GZIP
+ * format, reading and decompressing GZIP data from the underlying stream into
+ * its buffer.
  */
 public class GZIPInputStream extends InflaterInputStream {
 
@@ -36,36 +38,44 @@
 
     private static final int FNAME = 8;
 
-    /** Value of GZIP header magic number. */
+    /**
+     * The magic header for the GZIP format.
+     */
     public final static int GZIP_MAGIC = 0x8b1f;
 
+    /**
+     * The checksum algorithm used when handling uncompressed data.
+     */
     protected CRC32 crc = new CRC32();
 
+    /**
+     * Indicates the end of the input stream.
+     */
     protected boolean eos = false;
 
     /**
-     * Construct a GZIPInputStream to read from GZIP data from the underlying
-     * stream
-     * 
+     * Construct a {@code GZIPInputStream} to read from GZIP data from the
+     * underlying stream.
+     *
      * @param is
-     *            InputStream to read data from
+     *            the {@code InputStream} to read data from.
      * @throws IOException
-     *             if an IO error occurs reading the stream
+     *             if an {@code IOException} occurs.
      */
     public GZIPInputStream(InputStream is) throws IOException {
         this(is, BUF_SIZE);
     }
 
     /**
-     * Construct a GZIPInputStream to read from GZIP data from the underlying
-     * stream. Set the internal buffer size to size
+     * Construct a {@code GZIPInputStream} to read from GZIP data from the
+     * underlying stream. Set the internal buffer size to {@code size}.
      * 
      * @param is
-     *            InputStream to read data from
+     *            the {@code InputStream} to read data from.
      * @param size
-     *            Internal read buffer size
+     *            the internal read buffer size.
      * @throws IOException
-     *             if an IO exception occurs reading the stream
+     *             if an {@code IOException} occurs.
      */
     public GZIPInputStream(InputStream is, int size) throws IOException {
         super(is, new Inflater(true), size);

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java Fri Apr 24 02:23:48 2009
@@ -21,36 +21,40 @@
 import java.io.OutputStream;
 
 /**
- * The GZIPOutputStream class is used to write data to a stream in the GZIP
- * storage format.
+ * The {@code GZIPOutputStream} class is used to write data to a stream in the
+ * GZIP storage format.
  */
 public class GZIPOutputStream extends DeflaterOutputStream {
 
+    /**
+     * The checksum algorithm used when treating uncompressed data.
+     */
     protected CRC32 crc = new CRC32();
 
     /**
-     * Construct a new GZIPOutputStream to write data in GZIP format to the
-     * underlying stream.
+     * Construct a new {@code GZIPOutputStream} to write data in GZIP format to
+     * the underlying stream.
      * 
      * @param os
-     *            OutputStream to write to
+     *            the {@code OutputStream} to write data to.
      * @throws IOException
-     *             if an IO error occurs writing to the output stream
+     *             if an {@code IOException} occurs.
      */
     public GZIPOutputStream(OutputStream os) throws IOException {
         this(os, BUF_SIZE);
     }
 
     /**
-     * Construct a new GZIPOutputStream to write data in GZIP format to the
-     * underlying stream. Set the internal compression buffer to sise size.
+     * Construct a new {@code GZIPOutputStream} to write data in GZIP format to
+     * the underlying stream. Set the internal compression buffer to size
+     * {@code size}.
      * 
      * @param os
-     *            OutputStream to write to
+     *            the {@code OutputStream} to write to.
      * @param size
-     *            Internal buffer size
+     *            the internal buffer size.
      * @throws IOException
-     *             if an IO error occurs writing to the output stream
+     *             if an {@code IOException} occurs.
      */
     public GZIPOutputStream(OutputStream os, int size) throws IOException {
         super(os, new Deflater(Deflater.DEFAULT_COMPRESSION, true), size);
@@ -64,7 +68,10 @@
 
     /**
      * Indicates to the stream that all data has been written out, and any GZIP
-     * terminal data can now be output.
+     * terminal data can now be written.
+     *
+     * @throws IOException
+     *             if an {@code IOException} occurs.
      */
     @Override
     public void finish() throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Inflater.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Inflater.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Inflater.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Inflater.java Fri Apr 24 02:23:48 2009
@@ -20,11 +20,19 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * The Inflater class is used to decompress bytes using the DEFLATE compression
- * algorithm. Inflation is performed by the ZLIB compression library.
+ * This class uncompresses data that was compressed using the <i>DEFLATE</i>
+ * algorithm (see <a href="http://www.gzip.org/algorithm.txt">specification</a>).
+ * <p>
+ * Basically this class is part of the API to the stream based ZLIB compression
+ * library and is used as such by {@code InflaterInputStream} and its
+ * descendants.
+ * <p>
+ * The typical usage of a {@code Inflater} outside this package consists of a
+ * specific call to one of its constructors before being passed to an instance
+ * of {@code InflaterInputStream}.
  * 
- * @see DeflaterOutputStream
- * @see Inflater
+ * @see InflaterInputStream
+ * @see Deflater
  */
 public class Inflater {
 
@@ -52,18 +60,21 @@
     private long streamHandle = -1;
 
     /**
-     * Constructs a new Inflater instance.
+     * This constructor creates an inflater that expects a header from the input
+     * stream. Use {@code Inflater(boolean)} if the input comes without a ZLIB
+     * header.
      */
     public Inflater() {
         this(false);
     }
 
     /**
-     * Constructs a new Inflater instance. If noHeader is true the Inflater will
-     * not attempt to read a ZLIB header.
-     * 
+     * This constructor allows to create an inflater that expects no header from
+     * the input stream.
+     *
      * @param noHeader
-     *            If true, read a ZLIB header from input.
+     *            {@code true} indicates that no ZLIB header comes with the
+     *            input.
      */
     public Inflater(boolean noHeader) {
         streamHandle = createStream(noHeader);
@@ -92,22 +103,24 @@
     }
 
     /**
-     * Indicates if the Inflater has inflated the entire deflated stream. If
-     * deflated bytes remain and needsInput returns true this method will return
-     * false. This method should be called after all deflated input is supplied
-     * to the Inflater.
+     * Indicates if the {@code Inflater} has inflated the entire deflated
+     * stream. If deflated bytes remain and {@code needsInput()} returns {@code
+     * true} this method will return {@code false}. This method should be
+     * called after all deflated input is supplied to the {@code Inflater}.
      * 
-     * @return True if all input has been inflated, false otherwise
+     * @return {@code true} if all input has been inflated, {@code false}
+     *         otherwise.
      */
     public synchronized boolean finished() {
         return finished;
     }
 
     /**
-     * Returns the Adler32 checksum of either all bytes inflated, or the
+     * Returns the <i>Adler32</i> checksum of either all bytes inflated, or the
      * checksum of the preset dictionary if one has been supplied.
      * 
-     * @return The Adler32 checksum associated with this Inflater.
+     * @return The <i>Adler32</i> checksum associated with this
+     *         {@code Inflater}.
      */
     public synchronized int getAdler() {
         if (streamHandle == -1) {
@@ -119,12 +132,11 @@
     private native synchronized int getAdlerImpl(long handle);
 
     /**
-     * Returns a long int of total number of bytes of input read by the
-     * Inflater. This method performs the same as getTotalIn except it returns a
-     * long value instead of an integer
-     * 
-     * @see #getTotalIn()
-     * @return Total bytes read
+     * Returns the total number of bytes read by the {@code Inflater}. This
+     * method performs the same as {@code getTotalIn()} except that it returns a
+     * {@code long} value instead of an integer.
+     *
+     * @return the total number of bytes read.
      */
     public synchronized long getBytesRead() {
         // Throw NPE here
@@ -135,12 +147,11 @@
     }
 
     /**
-     * Returns a long int of total number of bytes of input output by the
-     * Inflater. This method performs the same as getTotalOut except it returns
-     * a long value instead of an integer
-     * 
-     * @see #getTotalOut()
-     * @return Total bytes output
+     * Returns a the total number of bytes read by the {@code Inflater}. This
+     * method performs the same as {@code getTotalOut} except it returns a
+     * {@code long} value instead of an integer.
+     *
+     * @return the total bytes written to the output buffer.
      */
     public synchronized long getBytesWritten() {
         // Throw NPE here
@@ -161,9 +172,10 @@
     }
 
     /**
-     * Returns total number of bytes of input read by the Inflater.
+     * Returns total number of bytes of input read by the {@code Inflater}. The
+     * result value is limited by {@code Integer.MAX_VALUE}.
      * 
-     * @return Total bytes read
+     * @return the total number of bytes read.
      */
     public synchronized int getTotalIn() {
         if (streamHandle == -1) {
@@ -177,9 +189,10 @@
     private synchronized native long getTotalInImpl(long handle);
 
     /**
-     * Returns total number of bytes of input output by the Inflater.
+     * Returns total number of bytes written to the output buffer by the {@code
+     * Inflater}. The result value is limited by {@code Integer.MAX_VALUE}.
      * 
-     * @return Total bytes output
+     * @return the total bytes of output data written.
      */
     public synchronized int getTotalOut() {
         if (streamHandle == -1) {
@@ -193,32 +206,33 @@
     private native synchronized long getTotalOutImpl(long handle);
 
     /**
-     * Inflates bytes from current input and stores them in buf.
+     * Inflates bytes from current input and stores them in {@code buf}.
      * 
      * @param buf
-     *            Buffer to output inflated bytes
-     * @return Number of bytes inflated
-     * @exception DataFormatException
-     *                If the underlying stream is corrupted or was not DEFLATED
-     * 
+     *            the buffer where decompressed data bytes are written.
+     * @return the number of bytes inflated.
+     * @throws DataFormatException
+     *             if the underlying stream is corrupted or was not compressed
+     *             using a {@code Deflater}.
      */
     public int inflate(byte[] buf) throws DataFormatException {
         return inflate(buf, 0, buf.length);
     }
 
     /**
-     * Inflates up to nbytes bytes from current input and stores them in buf
-     * starting at off.
+     * Inflates up to n bytes from the current input and stores them in {@code
+     * buf} starting at {@code off}.
      * 
      * @param buf
-     *            Buffer to output inflated bytes
+     *            the buffer to write inflated bytes to.
      * @param off
-     *            Offset in buffer into which to store inflated bytes
+     *            the offset in buffer where to start writing decompressed data.
      * @param nbytes
-     *            Number of inflated bytes to store
-     * @exception DataFormatException
-     *                If the underlying stream is corrupted or was not DEFLATED
-     * @return Number of bytes inflated
+     *            the number of inflated bytes to write to {@code buf}.
+     * @throws DataFormatException
+     *             if the underlying stream is corrupted or was not compressed
+     *             using a {@code Deflater}.
+     * @return the number of bytes inflated.
      */
     public synchronized int inflate(byte[] buf, int off, int nbytes)
             throws DataFormatException {
@@ -256,11 +270,12 @@
 
     /**
      * Indicates whether the input bytes were compressed with a preset
-     * dictionary. This method should be called prior to inflate() to determine
-     * if a dictionary is required. If so setDictionary() should be called with
-     * the appropriate dictionary prior to calling inflate().
+     * dictionary. This method should be called prior to {@code inflate()} to
+     * determine whether a dictionary is required. If so {@code setDictionary()}
+     * should be called with the appropriate dictionary prior to calling {@code
+     * inflate()}.
      * 
-     * @return true if a preset dictionary is required for inflation.
+     * @return {@code true} if a preset dictionary is required for inflation.
      * @see #setDictionary(byte[])
      * @see #setDictionary(byte[], int, int)
      */
@@ -269,9 +284,10 @@
     }
 
     /**
-     * Answers whether more data is required in the input buffer.
+     * Indicates that input has to be passed to the inflater.
      * 
-     * @return true if the input buffer is empty, and false otherwise.
+     * @return {@code true} if {@code setInput} has to be called before
+     *         inflation can proceed.
      * @see #setInput(byte[])
      */
     public synchronized boolean needsInput() {
@@ -279,7 +295,8 @@
     }
 
     /**
-     * Resets the Inflater.
+     * Resets the {@code Inflater}. Should be called prior to inflating a new
+     * set of data.
      */
     public synchronized void reset() {
         if (streamHandle == -1) {
@@ -294,32 +311,33 @@
     private native synchronized void resetImpl(long handle);
 
     /**
-     * Sets the preset dictionary to be used for inflation.
-     * 
-     * <code>needsDictionary()</code> can be called to determine whether the
-     * current input was deflated using a preset dictionary.
+     * Sets the preset dictionary to be used for inflation to {@code buf}.
+     * {@code needsDictionary()} can be called to determine whether the current
+     * input was deflated using a preset dictionary.
      * 
      * @param buf
-     *            The buffer containing the dictionary bytes
-     * @see #needsDictionary()
+     *            The buffer containing the dictionary bytes.
+     * @see #needsDictionary
      */
     public synchronized void setDictionary(byte[] buf) {
         setDictionary(buf, 0, buf.length);
     }
 
     /**
-     * Sets the dictionary used to inflate the given data.
-     * 
+     * Like {@code setDictionary(byte[])}, allowing to define a specific region
+     * inside {@code buf} to be used as a dictionary.
+     * <p>
      * The dictionary should be set if the {@link #inflate(byte[])} returned
      * zero bytes inflated and {@link #needsDictionary()} returns
      * <code>true</code>.
      * 
      * @param buf
-     *            the bytes containing the dictionary
+     *            the buffer containing the dictionary data bytes.
      * @param off
-     *            offset into the buffer to the start of the dictionary
+     *            the offset of the data.
      * @param nbytes
-     *            length of the dictionary, in bytes
+     *            the length of the data.
+     * @see #needsDictionary
      */
     public synchronized void setDictionary(byte[] buf, int off, int nbytes) {
         if (streamHandle == -1) {
@@ -338,11 +356,11 @@
             int nbytes, long handle);
 
     /**
-     * Sets the current input to buf. This method should only be called if
-     * needsInput() returns true.
+     * Sets the current input to to be decrompressed. This method should only be
+     * called if {@code needsInput()} returns {@code true}.
      * 
      * @param buf
-     *            input buffer
+     *            the input buffer.
      * @see #needsInput
      */
     public synchronized void setInput(byte[] buf) {
@@ -350,16 +368,17 @@
     }
 
     /**
-     * Sets the current input to the region of buf starting at off and ending at
-     * nbytes - 1. This method should only be called if needsInput() returns
-     * true.
+     * Sets the current input to the region of the input buffer starting at
+     * {@code off} and ending at {@code nbytes - 1} where data is written after
+     * decompression. This method should only be called if {@code needsInput()}
+     * returns {@code true}.
      * 
      * @param buf
-     *            input buffer
+     *            the input buffer.
      * @param off
-     *            offset to read from in buffer
+     *            the offset to read from the input buffer.
      * @param nbytes
-     *            number of bytes to read
+     *            the number of bytes to read.
      * @see #needsInput
      */
     public synchronized void setInput(byte[] buf, int off, int nbytes) {

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java Fri Apr 24 02:23:48 2009
@@ -25,18 +25,30 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * InflaterOutputStream read data which has been compressed using the DEFLATE
- * compression method.
+ * This class provides an implementation of {@code FilterInputStream} that
+ * uncompresses data that was compressed using the <i>DEFLATE</i> algorithm
+ * (see <a href="http://www.gzip.org/algorithm.txt">specification</a>).
+ * Basically it wraps the {@code Inflater} class and takes care of the
+ * buffering.
  * 
  * @see Inflater
  * @see DeflaterOutputStream
  */
 public class InflaterInputStream extends FilterInputStream {
 
+    /**
+     * The inflater used for this stream.
+     */
     protected Inflater inf;
 
+    /**
+     * The input buffer used for decompression.
+     */
     protected byte[] buf;
 
+    /**
+     * The length of the buffer.
+     */
     protected int len;
 
     boolean closed;
@@ -46,38 +58,41 @@
     static final int BUF_SIZE = 512;
 
     /**
-     * Constructs a new InflaterOutputStream on is
+     * This is the most basic constructor. You only need to pass the {@code
+     * InputStream} from which the compressed data is to be read from. Default
+     * settings for the {@code Inflater} and internal buffer are be used. In
+     * particular the Inflater expects a ZLIB header from the input stream.
      * 
      * @param is
-     *            The InputStream to read data from
+     *            the {@code InputStream} to read data from.
      */
     public InflaterInputStream(InputStream is) {
         this(is, new Inflater(), BUF_SIZE);
     }
 
     /**
-     * Constructs a new InflaterOutputStream on is, using the Inflater provided
-     * in inf.
+     * This constructor lets you pass a specifically initialized Inflater,
+     * for example one that expects no ZLIB header.
      * 
      * @param is
-     *            The InputStream to read data from
+     *            the {@code InputStream} to read data from.
      * @param inf
-     *            The Inflater to use for decompression
+     *            the specific {@code Inflater} for uncompressing data.
      */
     public InflaterInputStream(InputStream is, Inflater inf) {
         this(is, inf, BUF_SIZE);
     }
 
     /**
-     * Constructs a new InflaterOutputStream on is, using the Inflater provided
-     * in inf. The size of the inflation buffer is determined by bsize.
+     * This constructor lets you specify both the {@code Inflater} as well as
+     * the internal buffer size to be used.
      * 
      * @param is
-     *            The InputStream to read data from
+     *            the {@code InputStream} to read data from.
      * @param inf
-     *            The Inflater to use for decompression
+     *            the specific {@code Inflater} for uncompressing data.
      * @param bsize
-     *            size of the inflation buffer
+     *            the size to be used for the internal buffer.
      */
     public InflaterInputStream(InputStream is, Inflater inf, int bsize) {
         super(is);
@@ -94,9 +109,9 @@
     /**
      * Reads a single byte of decompressed data.
      * 
-     * @return byte read
+     * @return the byte read.
      * @throws IOException
-     *             If an error occurs reading
+     *             if an error occurs reading the byte.
      */
     @Override
     public int read() throws IOException {
@@ -108,18 +123,18 @@
     }
 
     /**
-     * Reads up to nbytes of decompressed data and stores it in buf starting at
-     * off.
+     * Reads up to {@code nbytes} of decompressed data and stores it in
+     * {@code buffer} starting at {@code off}.
      * 
      * @param buffer
-     *            Buffer to store into
+     *            the buffer to write data to.
      * @param off
-     *            offset in buffer to store at
+     *            offset in buffer to start writing.
      * @param nbytes
-     *            number of bytes to store
+     *            number of bytes to read.
      * @return Number of uncompressed bytes read
      * @throws IOException
-     *             If an error occurs reading
+     *             if an IOException occurs.
      */
     @Override
     public int read(byte[] buffer, int off, int nbytes) throws IOException {
@@ -177,6 +192,12 @@
         throw new ArrayIndexOutOfBoundsException();
     }
 
+    /**
+     * Fills the input buffer with data to be decompressed.
+     *
+     * @throws IOException
+     *             if an {@code IOException} occurs.
+     */
     protected void fill() throws IOException {
         if (closed) {
             throw new IOException(Messages.getString("archive.1E")); //$NON-NLS-1$
@@ -187,13 +208,13 @@
     }
 
     /**
-     * Skips up to nbytes of uncompressed data.
+     * Skips up to n bytes of uncompressed data.
      * 
      * @param nbytes
-     *            Number of bytes to skip
-     * @return Number of uncompressed bytes skipped
+     *            the number of bytes to skip.
+     * @return the number of uncompressed bytes skipped.
      * @throws IOException
-     *             If an error occurs skipping
+     *             if an error occurs skipping.
      */
     @Override
     public long skip(long nbytes) throws IOException {
@@ -215,10 +236,11 @@
     }
 
     /**
-     * Returns 0 if this stream has been closed, 1 otherwise.
+     * Returns whether data can be read from this stream.
      * 
+     * @return 0 if this stream has been closed, 1 otherwise.
      * @throws IOException
-     *             If an error occurs
+     *             If an error occurs.
      */
     @Override
     public int available() throws IOException {
@@ -233,10 +255,10 @@
     }
 
     /**
-     * Closes the stream
+     * Closes the input stream.
      * 
      * @throws IOException
-     *             If an error occurs closing the stream
+     *             If an error occurs closing the input stream.
      */
     @Override
     public void close() throws IOException {
@@ -249,13 +271,11 @@
     }
 
     /**
-     * Marks the current position in the stream.
-     * 
-     * This implementation overrides the supertype implementation to do nothing
-     * at all.
+     * Marks the current position in the stream. This implementation overrides
+     * the super type implementation to do nothing at all.
      * 
      * @param readlimit
-     *            of no use
+     *            of no use.
      */
     @Override
     public void mark(int readlimit) {
@@ -263,11 +283,10 @@
     }
 
     /**
-     * Reset the position of the stream to the last mark position.
-     * 
-     * This implementation overrides the supertype implementation and always
-     * throws an {@link IOException IOException} when called.
-     * 
+     * Reset the position of the stream to the last marked position. This
+     * implementation overrides the supertype implementation and always throws
+     * an {@link IOException IOException} when called.
+     *
      * @throws IOException
      *             if the method is called
      */
@@ -277,10 +296,10 @@
     }
 
     /**
-     * Answers whether the receiver implements mark semantics. This type does
-     * not support mark, so always responds <code>false</code>.
+     * Returns whether the receiver implements {@code mark} semantics. This type
+     * does not support {@code mark()}, so always responds {@code false}.
      * 
-     * @return false
+     * @return false, always
      */
     @Override
     public boolean markSupported() {

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipEntry.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipEntry.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipEntry.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipEntry.java Fri Apr 24 02:23:48 2009
@@ -22,10 +22,15 @@
 import java.util.GregorianCalendar;
 
 /**
- * ZipEntry represents an entry in a zip file.
+ * An instance of {@code ZipEntry} represents an entry within a <i>ZIP-archive</i>.
+ * An entry has attributes such as name (= path) or the size of its data. While
+ * an entry identifies data stored in an archive, it does not hold the data
+ * itself. For example when reading a <i>ZIP-file</i> you will first retrieve
+ * all its entries in a collection and then read the data for a specific entry
+ * through an input stream.
  * 
  * @see ZipFile
- * @see ZipInputStream
+ * @see ZipOutputStream
  */
 public class ZipEntry implements ZipConstants, Cloneable {
     String name, comment;
@@ -37,20 +42,22 @@
     byte[] extra;
 
     /**
-     * Zip entry state: Deflated
+     * Zip entry state: Deflated.
      */
     public static final int DEFLATED = 8;
 
     /**
-     * Zip entry state: Stored
+     * Zip entry state: Stored.
      */
     public static final int STORED = 0;
 
     /**
-     * Constructs a new ZipEntry with the specified name.
+     * Constructs a new {@code ZipEntry} with the specified name.
      * 
      * @param name
-     *            the name of the zip entry
+     *            the name of the ZIP entry.
+     * @throws IllegalArgumentException
+     *             if the name length is outside the range (> 0xFFFF).
      */
     public ZipEntry(String name) {
         if (name == null) {
@@ -63,76 +70,79 @@
     }
 
     /**
-     * Gets the comment for this ZipEntry.
+     * Gets the comment for this {@code ZipEntry}.
      * 
-     * @return the comment for this ZipEntry, or null if there is no comment
+     * @return the comment for this {@code ZipEntry}, or {@code null} if there
+     *         is no comment. If we're reading an archive with
+     *         {@code ZipInputStream} the comment is not available.
      */
     public String getComment() {
         return comment;
     }
 
     /**
-     * Gets the compressed size of this ZipEntry.
+     * Gets the compressed size of this {@code ZipEntry}.
      * 
      * @return the compressed size, or -1 if the compressed size has not been
-     *         set
+     *         set.
      */
     public long getCompressedSize() {
         return compressedSize;
     }
 
     /**
-     * Gets the crc for this ZipEntry.
+     * Gets the checksum for this {@code ZipEntry}.
      * 
-     * @return the crc, or -1 if the crc has not been set
+     * @return the checksum, or -1 if the checksum has not been set.
      */
     public long getCrc() {
         return crc;
     }
 
     /**
-     * Gets the extra information for this ZipEntry.
+     * Gets the extra information for this {@code ZipEntry}.
      * 
-     * @return a byte array containing the extra information, or null if there
-     *         is none
+     * @return a byte array containing the extra information, or {@code null} if
+     *         there is none.
      */
     public byte[] getExtra() {
         return extra;
     }
 
     /**
-     * Gets the compression method for this ZipEntry.
+     * Gets the compression method for this {@code ZipEntry}.
      * 
-     * @return the compression method, either DEFLATED, STORED or -1 if the
-     *         compression method has not been set
+     * @return the compression method, either {@code DEFLATED}, {@code STORED}
+     *         or -1 if the compression method has not been set.
      */
     public int getMethod() {
         return compressionMethod;
     }
 
     /**
-     * Gets the name of this ZipEntry.
+     * Gets the name of this {@code ZipEntry}.
      * 
-     * @return the entry name
+     * @return the entry name.
      */
     public String getName() {
         return name;
     }
 
     /**
-     * Gets the uncompressed size of this ZipEntry.
+     * Gets the uncompressed size of this {@code ZipEntry}.
      * 
-     * @return the uncompressed size, or -1 if the size has not been set
+     * @return the uncompressed size, or {@code -1} if the size has not been
+     *         set.
      */
     public long getSize() {
         return size;
     }
 
     /**
-     * Gets the last modification time of this ZipEntry.
+     * Gets the last modification time of this {@code ZipEntry}.
      * 
      * @return the last modification time as the number of milliseconds since
-     *         Jan. 1, 1970
+     *         Jan. 1, 1970.
      */
     public long getTime() {
         if (time != -1) {
@@ -147,20 +157,20 @@
     }
 
     /**
-     * Answers if this ZipEntry is a directory.
+     * Determine whether or not this {@code ZipEntry} is a directory.
      * 
-     * @return <code>true</code> when this ZipEntry is a directory,
-     *         <code>false<code> otherwise
+     * @return {@code true} when this {@code ZipEntry} is a directory, {@code
+     *         false} otherwise.
      */
     public boolean isDirectory() {
         return name.charAt(name.length() - 1) == '/';
     }
 
     /**
-     * Sets the comment for this ZipEntry.
+     * Sets the comment for this {@code ZipEntry}.
      * 
      * @param string
-     *            the comment
+     *            the comment for this entry.
      */
     public void setComment(String string) {
         if (string == null || string.length() <= 0xFFFF) {
@@ -171,23 +181,22 @@
     }
 
     /**
-     * Sets the compressed size for this ZipEntry.
+     * Sets the compressed size for this {@code ZipEntry}.
      * 
      * @param value
-     *            the compressed size
+     *            the compressed size (in bytes).
      */
     public void setCompressedSize(long value) {
         compressedSize = value;
     }
 
     /**
-     * Sets the crc for this ZipEntry.
+     * Sets the checksum for this {@code ZipEntry}.
      * 
      * @param value
-     *            the crc
-     * 
+     *            the checksum for this entry.
      * @throws IllegalArgumentException
-     *             if value is < 0 or > 0xFFFFFFFFL
+     *             if {@code value} is < 0 or > 0xFFFFFFFFL.
      */
     public void setCrc(long value) {
         if (value >= 0 && value <= 0xFFFFFFFFL) {
@@ -198,13 +207,12 @@
     }
 
     /**
-     * Sets the extra information for this ZipEntry.
+     * Sets the extra information for this {@code ZipEntry}.
      * 
      * @param data
-     *            a byte array containing the extra information
-     * 
+     *            a byte array containing the extra information.
      * @throws IllegalArgumentException
-     *             when the length of data is > 0xFFFF bytes
+     *             when the length of data is greater than 0xFFFF bytes.
      */
     public void setExtra(byte[] data) {
         if (data == null || data.length <= 0xFFFF) {
@@ -215,13 +223,13 @@
     }
 
     /**
-     * Sets the compression method for this ZipEntry.
+     * Sets the compression method for this {@code ZipEntry}.
      * 
      * @param value
-     *            the compression method, either DEFLATED or STORED
-     * 
+     *            the compression method, either {@code DEFLATED} or {@code
+     *            STORED}.
      * @throws IllegalArgumentException
-     *             when value is not DEFLATED or STORED
+     *             when value is not {@code DEFLATED} or {@code STORED}.
      */
     public void setMethod(int value) {
         if (value != STORED && value != DEFLATED) {
@@ -231,13 +239,12 @@
     }
 
     /**
-     * Sets the uncompressed size of this ZipEntry.
+     * Sets the uncompressed size of this {@code ZipEntry}.
      * 
      * @param value
-     *            the uncompressed size
-     * 
+     *            the uncompressed size for this entry.
      * @throws IllegalArgumentException
-     *             if value is < 0 or > 0xFFFFFFFFL
+     *             if {@code value} < 0 or {@code value} > 0xFFFFFFFFL.
      */
     public void setSize(long value) {
         if (value >= 0 && value <= 0xFFFFFFFFL) {
@@ -248,11 +255,11 @@
     }
 
     /**
-     * Sets the last modification time of this ZipEntry.
+     * Sets the modification time of this {@code ZipEntry}.
      * 
      * @param value
-     *            the last modification time as the number of milliseconds since
-     *            Jan. 1, 1970
+     *            the modification time as the number of milliseconds since Jan.
+     *            1, 1970.
      */
     public void setTime(long value) {
         GregorianCalendar cal = new GregorianCalendar();
@@ -272,9 +279,9 @@
     }
 
     /**
-     * Answers the string representation of this ZipEntry.
+     * Returns the string representation of this {@code ZipEntry}.
      * 
-     * @return the string representation of this ZipEntry
+     * @return the string representation of this {@code ZipEntry}.
      */
     @Override
     public String toString() {
@@ -297,10 +304,11 @@
     }
 
     /**
-     * Constructs a new ZipEntry using the values obtained from ze.
+     * Constructs a new {@code ZipEntry} using the values obtained from {@code
+     * ze}.
      * 
      * @param ze
-     *            ZipEntry from which to obtain values.
+     *            the {@code ZipEntry} from which to obtain values.
      */
     public ZipEntry(ZipEntry ze) {
         name = ze.name;
@@ -316,9 +324,9 @@
     }
 
     /**
-     * Returns a shallow copy of this entry
+     * Returns a shallow copy of this entry.
      * 
-     * @return a copy of this entry
+     * @return a copy of this entry.
      */
     @Override
     public Object clone() {
@@ -326,9 +334,9 @@
     }
 
     /**
-     * Returns the hashCode for this ZipEntry.
+     * Returns the hash code for this {@code ZipEntry}.
      * 
-     * @return the hashCode of the entry
+     * @return the hash code of the entry.
      */
     @Override
     public int hashCode() {

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipException.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipException.java Fri Apr 24 02:23:48 2009
@@ -20,8 +20,8 @@
 import java.io.IOException;
 
 /**
- * This runtime exception is thrown by ZipFile and ZipInputStream when the file
- * or stream is not a valid zip file.
+ * This runtime exception is thrown by {@code ZipFile} and {@code
+ * ZipInputStream} when the file or stream is not a valid ZIP file.
  * 
  * @see ZipFile
  * @see ZipInputStream
@@ -31,18 +31,18 @@
     private static final long serialVersionUID = 8000196834066748623L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code ZipException} instance.
      */
     public ZipException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
-     * 
+     * Constructs a new {@code ZipException} instance with the specified
+     * message.
+     *
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for the exception.
      */
     public ZipException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipFile.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipFile.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipFile.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipFile.java Fri Apr 24 02:23:48 2009
@@ -30,10 +30,18 @@
 import org.apache.harmony.luni.util.Util;
 
 /**
- * ZipFile is used to read zip entries and their associated data from zip files.
+ * This class provides random read access to a <i>ZIP-archive</i> file.
+ * <p>
+ * While {@code ZipInputStream} provides stream based read access to a
+ * <i>ZIP-archive</i>, this class implements more efficient (file based) access
+ * and makes use of the <i>central directory</i> within a <i>ZIP-archive</i>.
+ * <p>
+ * Use {@code ZipOutputStream} if you want to create an archive.
+ * <p>
+ * A temporary ZIP file can be marked for automatic deletion upon closing it.
  * 
- * @see ZipInputStream
  * @see ZipEntry
+ * @see ZipOutputStream
  */
 public class ZipFile implements ZipConstants {
 
@@ -49,37 +57,41 @@
         ntvinit();
     }
 
-    /** Open ZIP file for read. */
+    /**
+     * Open zip file for read.
+     */
     public static final int OPEN_READ = 1;
 
-    /** Delete ZIP file when closed. */
+    /**
+     * Delete zip file when closed.
+     */
     public static final int OPEN_DELETE = 4;
 
     /**
-     * Constructs a new ZipFile opened on the specified File.
+     * Constructs a new {@code ZipFile} with the specified file.
      * 
      * @param file
-     *            the File
+     *            the file to read from.
      * @throws ZipException
-     *             if a ZIP format exception occurs reading the file
+     *             if a ZIP error occurs.
      * @throws IOException
-     *             if an IO exception occurs reading the file
+     *             if an {@code IOException} occurs.
      */
     public ZipFile(File file) throws ZipException, IOException {
         this(file.getPath());
     }
 
     /**
-     * Constructs a new ZipFile opened on the specified file using the specified
-     * mode.
+     * Opens a file as <i>ZIP-archive</i>. "mode" must be {@code OPEN_READ} or
+     * {@code OPEN_DELETE} . The latter sets the "delete on exit" flag through a
+     * file.
      * 
      * @param file
-     *            the file
+     *            the ZIP file to read.
      * @param mode
-     *            the mode to use, either <code>OPEN_READ</code> or
-     *            <code>OPEN_READ | OPEN_DELETE</code>
+     *            the mode of the file open operation.
      * @throws IOException
-     *             if an IO exception occurs reading the file
+     *             if an {@code IOException} occurs.
      */
     public ZipFile(File file, int mode) throws IOException {
         if (mode == OPEN_READ || mode == (OPEN_READ | OPEN_DELETE)) {
@@ -99,19 +111,19 @@
     }
 
     /**
-     * Constructs a new ZipFile opened on the specified file path name.
+     * Opens a ZIP archived file.
      * 
-     * @param filename
-     *            the file path name
+     * @param name
+     *            the name of the ZIP file.
      * @throws IOException
-     *             if an IO exception occured reading the file
+     *             if an IOException occurs.
      */
-    public ZipFile(String filename) throws IOException {
+    public ZipFile(String name) throws IOException {
         SecurityManager security = System.getSecurityManager();
         if (security != null) {
-            security.checkRead(filename);
+            security.checkRead(name);
         }
-        fileName = filename;
+        fileName = name;
         openZip();
     }
 
@@ -138,10 +150,10 @@
     }
 
     /**
-     * Closes this ZipFile.
+     * Closes this ZIP file.
      * 
      * @throws IOException
-     *             if an IO exception occured closing the file
+     *             if an IOException occurs.
      */
     public synchronized void close() throws IOException {
         if (descriptor != -1 && fileName != null) {
@@ -159,21 +171,22 @@
     }
 
     /**
-     * Answers all of the ZIP entries contained in this ZipFile.
+     * Returns an enumeration of the entries. The entries are listed in the
+     * order in which they appear in the ZIP archive.
      * 
-     * @return an Enumeration of the ZIP entries
+     * @return the enumeration of the entries.
      */
     public Enumeration<? extends ZipEntry> entries() {
         return new ZFEnum<ZipEntry>();
     }
 
     /**
-     * Gets the zip entry with the specified name from this ZipFile.
+     * Gets the ZIP entry with the specified name from this {@code ZipFile}.
      * 
      * @param entryName
-     *            the name of the entry in the zip file
-     * @return a ZipEntry or null if the entry name does not exist in the zip
-     *         file
+     *            the name of the entry in the ZIP file.
+     * @return a {@code ZipEntry} or {@code null} if the entry name does not
+     *         exist in the ZIP file.
      */
     public ZipEntry getEntry(String entryName) {
         if (entryName != null) {
@@ -184,13 +197,13 @@
     }
 
     /**
-     * Answers an input stream on the data of the specified ZipEntry.
+     * Returns an input stream on the data of the specified {@code ZipEntry}.
      * 
      * @param entry
-     *            the ZipEntry
-     * @return an input stream on the ZipEntry data
+     *            the ZipEntry.
+     * @return an input stream of the data contained in the {@code ZipEntry}.
      * @throws IOException
-     *             if an IO exception occurs reading the data
+     *             if an {@code IOException} occurs.
      */
     public InputStream getInputStream(ZipEntry entry) throws IOException {
         if (descriptor == -1) {
@@ -208,9 +221,9 @@
     }
 
     /**
-     * Gets the file name of this ZipFile.
+     * Gets the file name of this {@code ZipFile}.
      * 
-     * @return the file name of this ZipFile
+     * @return the file name of this {@code ZipFile}.
      */
     public String getName() {
         return fileName;
@@ -226,9 +239,9 @@
             throws ZipException;
 
     /**
-     * Returns the number of ZipEntries in this ZipFile.
+     * Returns the number of {@code ZipEntries} in this {@code ZipFile}.
      * 
-     * @return Number of entries in this file
+     * @return the number of entries in this file.
      */
     public int size() {
         if (size != -1) {

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipInputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipInputStream.java Fri Apr 24 02:23:48 2009
@@ -28,8 +28,19 @@
 import org.apache.harmony.luni.util.Util;
 
 /**
- * ZipInputStream is an input stream for reading zip files.
- * 
+ * This class provides an implementation of {@code FilterInputStream} that
+ * uncompresses data from a <i>ZIP-archive</i> input stream.
+ * <p>
+ * A <i>ZIP-archive</i> is a collection of compressed (or uncompressed) files -
+ * the so called ZIP entries. Therefore when reading from a {@code
+ * ZipInputStream} first the entry's attributes will be retrieved with {@code
+ * getNextEntry} before its data is read.
+ * <p>
+ * While {@code InflaterInputStream} can read a compressed <i>ZIP-archive</i>
+ * entry, this extension can read uncompressed entries as well.
+ * <p>
+ * Use {@code ZipFile} if you can access the archive as a file directly.
+ *
  * @see ZipEntry
  * @see ZipFile
  */
@@ -63,10 +74,10 @@
     private char[] charBuf = new char[256];
 
     /**
-     * Constructs a new ZipInputStream on the specified input stream.
+     * Constructs a new {@code ZipInputStream} from the specified input stream.
      * 
      * @param stream
-     *            the input stream
+     *            the input stream to representing a ZIP archive.
      */
     public ZipInputStream(InputStream stream) {
         super(new PushbackInputStream(stream, BUF_SIZE), new Inflater(true));
@@ -76,7 +87,10 @@
     }
 
     /**
-     * Closes this ZipInputStream.
+     * Closes this {@code ZipInputStream}.
+     *
+     * @throws IOException
+     *             if an {@code IOException} occurs.
      */
     @Override
     public void close() throws IOException {
@@ -88,10 +102,10 @@
     }
 
     /**
-     * Closes the current zip entry and positions to read the next entry.
+     * Closes the current ZIP entry and positions to read the next entry.
      * 
      * @throws IOException
-     *             if an IO exception occurs closing the entry
+     *             if an {@code IOException} occurs.
      */
     public void closeEntry() throws IOException {
         if (zipClosed) {
@@ -145,11 +159,13 @@
     }
 
     /**
-     * Reads the next zip entry from this ZipInputStream.
+     * Reads the next entry from this {@code ZipInputStream}.
      * 
-     * @return the next entry
+     * @return the next {@code ZipEntry} contained in the input stream.
      * @throws IOException
-     *             if an IO exception occurs reading the next entry
+     *             if the stream is not positioned at the beginning of an entry
+     *             or if an other {@code IOException} occurs.
+     * @see ZipEntry
      */
     public ZipEntry getNextEntry() throws IOException {
         if (currentEntry != null) {
@@ -308,11 +324,13 @@
     }
 
     /**
-     * Skips up to the specified number of bytes in the current zip entry.
+     * Skips up to the specified number of bytes in the current ZIP entry.
      * 
      * @param value
-     *            the number of bytes to skip
-     * @return the number of bytes skipped
+     *            the number of bytes to skip.
+     * @return the number of bytes skipped.
+     * @throws IOException
+     *             if an {@code IOException} occurs.
      */
     @Override
     public long skip(long value) throws IOException {
@@ -333,9 +351,11 @@
     }
 
     /**
-     * Answers 1 if the EOF has been reached, otherwise returns 0.
+     * Returns 0 if the {@code EOF} has been reached, otherwise returns 1.
      * 
-     * @return 0 after EOF of current entry, 1 otherwise
+     * @return 0 after {@code EOF} of current entry, 1 otherwise.
+     * @throws IOException
+     *             if an IOException occurs.
      */
     @Override
     public int available() throws IOException {
@@ -357,6 +377,13 @@
         return 1;
     }
 
+    /**
+     * creates a {@link ZipEntry } with the given name.
+     *
+     * @param name
+     *            the name of the entry.
+     * @return the created {@code ZipEntry}.
+     */
     protected ZipEntry createZipEntry(String name) {
         return new ZipEntry(name);
     }

Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java Fri Apr 24 02:23:48 2009
@@ -25,19 +25,33 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * ZipOutputStream is used to write ZipEntries to the underlying stream. Output
- * from ZipOutputStream conforms to the ZipFile file format.
- * 
- * @see ZipInputStream
+ * This class provides an implementation of {@code FilterOutputStream} that
+ * compresses data entries into a <i>ZIP-archive</i> output stream.
+ * <p>
+ * {@code ZipOutputStream} is used to write {@code ZipEntries} to the underlying
+ * stream. Output from {@code ZipOutputStream} conforms to the {@code ZipFile}
+ * file format.
+ * <p>
+ * While {@code DeflaterOutputStream} can write a compressed <i>ZIP-archive</i>
+ * entry, this extension can write uncompressed entries as well. In this case
+ * special rules apply, for this purpose refer to the <a
+ * href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">file format
+ * specification</a>.
+ *
  * @see ZipEntry
+ * @see ZipFile
  */
 public class ZipOutputStream extends DeflaterOutputStream implements
         ZipConstants {
 
-    /** Method for compressed entries */
+    /**
+     * Indicates deflated entries.
+     */
     public static final int DEFLATED = 8;
 
-    /** Method for uncompressed entries */
+    /**
+     * Indicates uncompressed entries.
+     */
     public static final int STORED = 0;
 
     static final int ZIPDataDescriptorFlag = 8;
@@ -63,21 +77,22 @@
     private byte[] nameBytes;
 
     /**
-     * Constructs a new ZipOutputStream on p1
+     * Constructs a new {@code ZipOutputStream} with the specified output
+     * stream.
      * 
      * @param p1
-     *            OutputStream The InputStream to output to
+     *            the {@code OutputStream} to write the data to.
      */
     public ZipOutputStream(OutputStream p1) {
         super(p1, new Deflater(Deflater.DEFAULT_COMPRESSION, true));
     }
 
     /**
-     * Closes the current ZipEntry if any. Closes the underlying output stream.
-     * If the stream is already closed this method does nothing.
+     * Closes the current {@code ZipEntry}, if any, and the underlying output
+     * stream. If the stream is already closed this method does nothing.
      * 
-     * @exception IOException
-     *                If an error occurs closing the stream
+     * @throws IOException
+     *             If an error occurs closing the stream.
      */
     @Override
     public void close() throws IOException {
@@ -89,11 +104,11 @@
     }
 
     /**
-     * Closes the current ZipEntry. Any entry terminal data is written to the
-     * underlying stream.
+     * Closes the current {@code ZipEntry}. Any entry terminal data is written
+     * to the underlying stream.
      * 
-     * @exception IOException
-     *                If an error occurs closing the entry
+     * @throws IOException
+     *             If an error occurs closing the entry.
      */
     public void closeEntry() throws IOException {
         if (cDir == null) {
@@ -175,10 +190,10 @@
 
     /**
      * Indicates that all entries have been written to the stream. Any terminal
-     * ZipFile information is written to the underlying stream.
+     * information is written to the underlying stream.
      * 
-     * @exception IOException
-     *                If an error occurs while finishing
+     * @throws IOException
+     *             if an error occurs while terminating the stream.
      */
     @Override
     public void finish() throws IOException {
@@ -216,15 +231,15 @@
     }
 
     /**
-     * Writes entry information for ze to the underlying stream. Data associated
-     * with the entry can then be written using write(). After data is written
-     * closeEntry() must be called to complete the storing of ze on the
-     * underlying stream.
+     * Writes entry information to the underlying stream. Data associated with
+     * the entry can then be written using {@code write()}. After data is
+     * written {@code closeEntry()} must be called to complete the writing of
+     * the entry to the underlying stream.
      * 
      * @param ze
-     *            ZipEntry to store
-     * @exception IOException
-     *                If an error occurs storing the entry
+     *            the {@code ZipEntry} to store.
+     * @throws IOException
+     *             If an error occurs storing the entry.
      * @see #write
      */
     public void putNextEntry(ZipEntry ze) throws java.io.IOException {
@@ -307,10 +322,10 @@
     }
 
     /**
-     * Sets the ZipFile comment associated with the file being written.
+     * Sets the {@code ZipFile} comment associated with the file being written.
      * 
      * @param comment
-     *            the file comment
+     *            the comment associated with the file.
      */
     public void setComment(String comment) {
         if (comment.length() > 0xFFFF) {
@@ -321,10 +336,12 @@
 
     /**
      * Sets the compression level to be used for writing entry data. This level
-     * may be set on a per entry basis.
+     * may be set on a per entry basis. The level must have a value between -1
+     * and 8 according to the {@code Deflater} compression level bounds.
      * 
      * @param level
-     *            the compression level, must have a value between 0 and 10.
+     *            the compression level (ranging from -1 to 8).
+     * @see Deflater
      */
     public void setLevel(int level) {
         if (level < Deflater.DEFAULT_COMPRESSION
@@ -336,10 +353,11 @@
 
     /**
      * Sets the compression method to be used when compressing entry data.
-     * method must be one of STORED or DEFLATED.
+     * method must be one of {@code STORED} (for no compression) or {@code
+     * DEFLATED}.
      * 
      * @param method
-     *            Compression method to use
+     *            the compression method to use.
      */
     public void setMethod(int method) {
         if (method != STORED && method != DEFLATED) {



Mime
View raw message