You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by nd...@apache.org on 2009/04/24 04:23:50 UTC
svn commit: r768128 [2/2] - in
/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util:
jar/ zip/
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) {