2003-05-27 Michael Koch <konqueror@gmx.de>

* java/util/zip/Deflater.java
	(FILTERED): Merged documentation from classpath.
	* java/util/zip/DeflaterOutputStream.java
	(DeflaterOutputStream): Merged documentation and argument validity
	check from classpath.
	(deflate): Merged documentation from classpath.
	(finish): Likewise.
	* java/util/zip/Inflater.java
	(Inflater): Merged class documentation from classpath.
	(zstream): Reordered.
	(is_finished): Reordered.
	(dict_needed): Reordered.
	(Inflater): Reordered, merged documentation from classpath.
	(end): Likewise.
	(finalize): Merged documentation from classpath.
	(finished): Likewise.
	(getAdler): Likewise.
	(getRemaining): Likewise.
	(getTotalIn): Likewise.
	(getTotalOut): Likewise.
	(inflate): Likewise.
	(needsDictionary): Likewise.
	(needsInput): Likewise.
	(reset): Likewise.
	(setDictionary): Likewise.
	(setInput): Likewise.

From-SVN: r67185

libjava/ChangeLog

@@ -1,3 +1,32 @@
+2003-05-27  Michael Koch  <konqueror@gmx.de>
+
+	* java/util/zip/Deflater.java
+	(FILTERED): Merged documentation from classpath.
+	* java/util/zip/DeflaterOutputStream.java
+	(DeflaterOutputStream): Merged documentation and argument validity
+	check from classpath.
+	(deflate): Merged documentation from classpath.
+	(finish): Likewise.
+	* java/util/zip/Inflater.java
+	(Inflater): Merged class documentation from classpath.
+	(zstream): Reordered.
+	(is_finished): Reordered.
+	(dict_needed): Reordered.
+	(Inflater): Reordered, merged documentation from classpath.
+	(end): Likewise.
+	(finalize): Merged documentation from classpath.
+	(finished): Likewise.
+	(getAdler): Likewise.
+	(getRemaining): Likewise.
+	(getTotalIn): Likewise.
+	(getTotalOut): Likewise.
+	(inflate): Likewise.
+	(needsDictionary): Likewise.
+	(needsInput): Likewise.
+	(reset): Likewise.
+	(setDictionary): Likewise.
+	(setInput): Likewise.
+
 2003-05-27  Michael Koch  <konqueror@gmx.de>
 
 	* java/net/URLConnection.java

libjava/java/util/zip/Deflater.java

@@ -48,7 +48,6 @@ import gnu.gcj.RawData;
  * and JCL book.
  * Believed complete and correct.
  */
-
 public class Deflater
 {
   /**
@@ -73,6 +72,10 @@ public class Deflater
    * The default strategy.
    */
   public static final int DEFAULT_STRATEGY = 0;
+  /**
+   * This strategy will only allow longer string repetitions.  It is
+   * useful for random data with a small character set.
+   */
   public static final int FILTERED = 1;
 
   /** 

libjava/java/util/zip/DeflaterOutputStream.java

@@ -56,6 +56,7 @@ import java.io.IOException;
  * finishing the stream.
  *
  * @author Tom Tromey, Jochen Hoenicke
+ * @date Jan 11, 2001 
  */
 public class DeflaterOutputStream extends FilterOutputStream
 {
@@ -65,6 +66,11 @@ public class DeflaterOutputStream extends FilterOutputStream
     out.close();
   }
 
+  /**
+   * Deflates everything in the def's input buffers.  This will call
+   * <code>def.deflate()</code> until all bytes from the input buffers
+   * are processed.
+   */
   protected void deflate () throws IOException
   {
     do
@@ -76,23 +82,49 @@ public class DeflaterOutputStream extends FilterOutputStream
     while (! def.needsInput());
   }
 
+  /** 
+   * Creates a new DeflaterOutputStream with a default Deflater and
+   * default buffer size.
+   * @param out the output stream where deflated output should be written.
+   */
   public DeflaterOutputStream (OutputStream out)
   {
     this (out, new Deflater (), 512);
   }
 
+  /** 
+   * Creates a new DeflaterOutputStream with the given Deflater and
+   * default buffer size.
+   * @param out the output stream where deflated output should be written.
+   * @param defl the underlying deflater.
+   */
   public DeflaterOutputStream (OutputStream out, Deflater defl)
   {
     this (out, defl, 512);
   }
 
+  /** 
+   * Creates a new DeflaterOutputStream with the given Deflater and
+   * buffer size.
+   * @param out the output stream where deflated output should be written.
+   * @param defl the underlying deflater.
+   * @param bufsize the buffer size.
+   * @exception IllegalArgumentException if bufsize isn't positive.
+   */
   public DeflaterOutputStream(OutputStream out, Deflater defl, int bufsize)
   {
     super (out);
+    if (bufsize <= 0)
+      throw new IllegalArgumentException("bufsize <= 0");
     buf = new byte[bufsize];
     def = defl;
   }
 
+  /**
+   * Finishes the stream by calling finish() on the deflater.  This
+   * was the only way to ensure that all bytes are flushed in Sun's
+   * JDK.  
+   */
   public void finish () throws IOException
   {
     if (inbufLength > 0)

libjava/java/util/zip/Inflater.java

@@ -1,5 +1,5 @@
 /* Inflater.java - Decompress a data stream
-   Copyright (C) 1999, 2000 Free Software Foundation, Inc.
+   Copyright (C) 1999, 2000, 2001, 2003  Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,81 +39,37 @@ package java.util.zip;
 
 import gnu.gcj.RawData;
 
-/**
- * @author Tom Tromey
- * @date May 17, 1999
- */
-
 /* Written using on-line Java Platform 1.2 API Specification
  * and JCL book.
  * Believed complete and correct.
  */
 
+/**
+ * Inflater is used to decompress data that has been compressed according 
+ * to the "deflate" standard described in rfc1950.
+ *
+ * The usage is as following.  First you have to set some input with
+ * <code>setInput()</code>, then inflate() it.  If inflate doesn't
+ * inflate any bytes there may be three reasons:
+ * <ul>
+ * <li>needsInput() returns true because the input buffer is empty.
+ * You have to provide more input with <code>setInput()</code>.  
+ * NOTE: needsInput() also returns true when, the stream is finished.
+ * </li>
+ * <li>needsDictionary() returns true, you have to provide a preset 
+ *     dictionary with <code>setDictionary()</code>.</li>
+ * <li>finished() returns true, the inflater has finished.</li>
+ * </ul>
+ * Once the first output byte is produced, a dictionary will not be
+ * needed at a later stage.
+ *
+ * @author John Leuner, Jochen Hoenicke
+ * @author Tom Tromey
+ * @date May 17, 1999
+ * @since JDK 1.1
+ */
 public class Inflater
 {
-  public native void end ();
-
-  protected void finalize ()
-  {
-    end ();
-  }
-
-  public synchronized boolean finished ()
-  {
-    return is_finished;
-  }
-
-  public native int getAdler ();
-  public native int getRemaining ();
-  public native int getTotalIn ();
-  public native int getTotalOut ();
-
-  public int inflate (byte[] buf) throws DataFormatException
-  {
-    return inflate (buf, 0, buf.length);
-  }
-
-  public native int inflate (byte[] buf, int off, int len)
-    throws DataFormatException;
-
-  private native void init (boolean noHeader);
-
-  public Inflater ()
-  {
-    this (false);
-  }
-
-  public Inflater (boolean noHeader)
-  {
-    init (noHeader);
-  }
-
-  public synchronized boolean needsDictionary ()
-  {
-    return dict_needed;
-  }
-
-  public synchronized boolean needsInput ()
-  {
-    return getRemaining () == 0;
-  }
-
-  public native void reset ();
-
-  public void setDictionary (byte[] buf)
-  {
-    setDictionary (buf, 0, buf.length);
-  }
-
-  public native void setDictionary (byte[] buf, int off, int len);
-
-  public void setInput (byte[] buf)
-  {
-    setInput (buf, 0, buf.length);
-  }
-
-  public native void setInput (byte[] buf, int off, int len);
-
   // The zlib stream.
   private RawData zstream;
 
@@ -122,4 +78,192 @@ public class Inflater
 
   // True if dictionary needed.
   private boolean dict_needed;
+
+  /**
+   * Creates a new inflater.
+   */
+  public Inflater ()
+  {
+    this (false);
+  }
+
+  /**
+   * Creates a new inflater.
+   * @param nowrap true if no header and checksum field appears in the
+   * stream.  This is used for GZIPed input.  For compatibility with
+   * Sun JDK you should provide one byte of input more than needed in
+   * this case.
+   */
+  public Inflater (boolean noHeader)
+  {
+    init (noHeader);
+  }
+
+  /**
+   * Finalizes this object.
+   */
+  protected void finalize ()
+  {
+    end ();
+  }
+
+  /**
+   * Frees all objects allocated by the inflater.  There's no reason
+   * to call this, since you can just rely on garbage collection (even
+   * for the Sun implementation).  Exists only for compatibility
+   * with Sun's JDK, where the compressor allocates native memory.
+   * If you call any method (even reset) afterwards the behaviour is
+   * <i>undefined</i>.  
+   * @deprecated Just clear all references to inflater instead.
+   */
+  public native void end ();
+
+  /**
+   * Returns true, if the inflater has finished.  This means, that no
+   * input is needed and no output can be produced.
+   */
+  public synchronized boolean finished ()
+  {
+    return is_finished;
+  }
+
+  /**
+   * Gets the adler checksum.  This is either the checksum of all
+   * uncompressed bytes returned by inflate(), or if needsDictionary()
+   * returns true (and thus no output was yet produced) this is the
+   * adler checksum of the expected dictionary.
+   * @returns the adler checksum.
+   */
+  public native int getAdler ();
+  
+  /**
+   * Gets the number of unprocessed input.  Useful, if the end of the
+   * stream is reached and you want to further process the bytes after
+   * the deflate stream.  
+   * @return the number of bytes of the input which were not processed.
+   */
+  public native int getRemaining ();
+  
+  /**
+   * Gets the total number of processed compressed input bytes.
+   * @return the total number of bytes of processed input bytes.
+   */
+  public native int getTotalIn ();
+
+  /**
+   * Gets the total number of output bytes returned by inflate().
+   * @return the total number of output bytes.
+   */
+  public native int getTotalOut ();
+
+  /**
+   * Inflates the compressed stream to the output buffer.  If this
+   * returns 0, you should check, whether needsDictionary(),
+   * needsInput() or finished() returns true, to determine why no 
+   * further output is produced.
+   * @param buffer the output buffer.
+   * @return the number of bytes written to the buffer, 0 if no further
+   * output can be produced.  
+   * @exception DataFormatException if deflated stream is invalid.
+   * @exception IllegalArgumentException if buf has length 0.
+   */
+  public int inflate (byte[] buf) throws DataFormatException
+  {
+    return inflate (buf, 0, buf.length);
+  }
+
+  /**
+   * Inflates the compressed stream to the output buffer.  If this
+   * returns 0, you should check, whether needsDictionary(),
+   * needsInput() or finished() returns true, to determine why no 
+   * further output is produced.
+   * @param buffer the output buffer.
+   * @param off the offset into buffer where the output should start.
+   * @param len the maximum length of the output.
+   * @return the number of bytes written to the buffer, 0 if no further
+   * output can be produced.  
+   * @exception DataFormatException if deflated stream is invalid.
+   * @exception IndexOutOfBoundsException if the off and/or len are wrong.
+   */
+  public native int inflate (byte[] buf, int off, int len)
+    throws DataFormatException;
+
+  private native void init (boolean noHeader);
+
+  /**
+   * Returns true, if a preset dictionary is needed to inflate the input.
+   */
+  public synchronized boolean needsDictionary ()
+  {
+    return dict_needed;
+  }
+
+  /**
+   * Returns true, if the input buffer is empty.
+   * You should then call setInput(). <br>
+   *
+   * <em>NOTE</em>: This method also returns true when the stream is finished.
+   */
+  public synchronized boolean needsInput ()
+  {
+    return getRemaining () == 0;
+  }
+
+  /**
+   * Resets the inflater so that a new stream can be decompressed.  All
+   * pending input and output will be discarded.
+   */
+  public native void reset ();
+
+  /**
+   * Sets the preset dictionary.  This should only be called, if
+   * needsDictionary() returns true and it should set the same
+   * dictionary, that was used for deflating.  The getAdler()
+   * function returns the checksum of the dictionary needed.
+   * @param buffer the dictionary.
+   * @exception IllegalStateException if no dictionary is needed.
+   * @exception IllegalArgumentException if the dictionary checksum is
+   * wrong.  
+   */
+  public void setDictionary (byte[] buf)
+  {
+    setDictionary (buf, 0, buf.length);
+  }
+
+  /**
+   * Sets the preset dictionary.  This should only be called, if
+   * needsDictionary() returns true and it should set the same
+   * dictionary, that was used for deflating.  The getAdler()
+   * function returns the checksum of the dictionary needed.
+   * @param buffer the dictionary.
+   * @param off the offset into buffer where the dictionary starts.
+   * @param len the length of the dictionary.
+   * @exception IllegalStateException if no dictionary is needed.
+   * @exception IllegalArgumentException if the dictionary checksum is
+   * wrong.  
+   * @exception IndexOutOfBoundsException if the off and/or len are wrong.
+   */
+  public native void setDictionary (byte[] buf, int off, int len);
+
+  /**
+   * Sets the input.  This should only be called, if needsInput()
+   * returns true.
+   * @param buffer the input.
+   * @exception IllegalStateException if no input is needed.
+   */
+  public void setInput (byte[] buf)
+  {
+    setInput (buf, 0, buf.length);
+  }
+
+  /**
+   * Sets the input.  This should only be called, if needsInput()
+   * returns true.
+   * @param buffer the input.
+   * @param off the offset into buffer where the input starts.
+   * @param len the length of the input.  
+   * @exception IllegalStateException if no input is needed.
+   * @exception IndexOutOfBoundsException if the off and/or len are wrong.
+   */
+  public native void setInput (byte[] buf, int off, int len);
 }