2004-02-05 Michael Koch <konqueror@gmx.de>

	* java/util/zip/Deflater.java,
	java/util/zip/DeflaterOutputStream.java,
	java/util/zip/GZIPInputStream.java:
	Reformated and javadoc comments merged from classpath.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@77319 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 200 insertions, 57 deletions

diff --git a/libjava/java/util/zip/Deflater.java b/libjava/java/util/zip/Deflater.java
index 52c569a412a..333555f0ac3 100644
--- a/libjava/java/util/zip/Deflater.java
+++ b/libjava/java/util/zip/Deflater.java
@@ -1,5 +1,5 @@
 /* Deflater.java - Compress a data stream
-   Copyright (C) 1999, 2000 Free Software Foundation, Inc.
+   Copyright (C) 1999, 2000, 2001, 2004 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,13 +40,15 @@ package java.util.zip;
 import gnu.gcj.RawData;
 
 /**
+ * This is the Deflater class.  The deflater class compresses input
+ * with the deflate algorithm described in RFC 1951.  It has several
+ * compression levels and three different strategies described below.
+ * 
+ * This class is <i>not</i> thread safe.  This is inherent in the API, due
+ * to the split of deflate and setInput.
+ * 
+ * @author Jochen Hoenicke
  * @author Tom Tromey
- * @date May 17, 1999
- */
-
-/* Written using on-line Java Platform 1.2 API Specification
- * and JCL book.
- * Believed complete and correct.
  */
 public class Deflater
 {
@@ -91,95 +93,236 @@ public class Deflater
    */
   public static final int DEFLATED = 8;
 
-  public int deflate (byte[] buf)
-  {
-    return deflate (buf, 0, buf.length);
-  }
+  /** Compression level. */
+  private int level;
 
-  public native int deflate (byte[] buf, int off, int len);
-  private native void init (int level, boolean noHeader);
-  private native void update ();
+  /** Compression strategy. */
+  private int strategy;
+
+  /** The zlib stream. */
+  private RawData zstream;
 
-  public Deflater ()
+  /** True if finished. */
+  private boolean is_finished;
+
+  /** `Flush' flag to pass to next call to deflate. */
+  private int flush_flag;
+
+  /**
+   * Creates a new deflater with default compression level.
+   */
+  public Deflater()
   {
-    this (DEFAULT_COMPRESSION, false);
+    this(DEFAULT_COMPRESSION, false);
   }
 
-  public Deflater (int lvl)
+  /**
+   * Creates a new deflater with given compression level.
+   * @param lvl the compression level, a value between NO_COMPRESSION
+   * and BEST_COMPRESSION, or DEFAULT_COMPRESSION.  
+   * @exception IllegalArgumentException if lvl is out of range.
+   */
+  public Deflater(int lvl)
   {
-    this (lvl, false);
+    this(lvl, false);
   }
 
-  public Deflater (int lvl, boolean noHeader)
+  /**
+   * Creates a new deflater with given compression level.
+   * @param lvl the compression level, a value between NO_COMPRESSION
+   * and BEST_COMPRESSION.  
+   * @param nowrap true, iff we should suppress the deflate header at the
+   * beginning and the adler checksum at the end of the output.  This is
+   * useful for the GZIP format.
+   * @exception IllegalArgumentException if lvl is out of range.
+   */
+  public Deflater(int lvl, boolean noHeader)
   {
     this.strategy = DEFAULT_STRATEGY;
-    init (lvl, noHeader);
-    setLevel (lvl);
+    init(lvl, noHeader);
+    setLevel(lvl);
   }
 
-  public native void end ();
+  private native void init(int level, boolean noHeader);
+  
+  private native void update();
 
-  protected void finalize ()
-  {
-    end ();
-  }
+  /** 
+   * Resets the deflater.  The deflater acts afterwards as if it was
+   * just created with the same compression level and strategy as it
+   * had before.  
+   */
+  public native void reset();
+  
+  /**
+   * Frees all objects allocated by the compressor.  There's no
+   * reason to call this, since you can just rely on garbage
+   * collection.  Exists only for compatibility against 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 deflater instead.
+   */
+  public native void end();
 
-  public native void finish ();
+  /** 
+   * Gets the current adler checksum of the data that was processed so
+   * far.
+   */
+  public native int getAdler();
 
-  public synchronized boolean finished ()
+  /** 
+   * Gets the number of input bytes processed so far.
+   */
+  public native int getTotalIn();
+
+  /** 
+   * Gets the number of output bytes so far.
+   */
+  public native int getTotalOut();
+
+  /** 
+   * Finalizes this object.
+   */
+  protected void finalize()
   {
-    return is_finished;
+    end();
   }
 
-  public native int getAdler ();
-  public native int getTotalIn ();
-  public native int getTotalOut ();
-  public native boolean needsInput ();
-  public native void reset ();
+  /** 
+   * Finishes the deflater with the current input block.  It is an error
+   * to give more input after this method was called.  This method must
+   * be called to force all bytes to be flushed.
+   */
+  public native void finish();
 
-  public void setDictionary (byte[] buf)
+  /** 
+   * Returns true iff the stream was finished and no more output bytes
+   * are available.
+   */
+  public synchronized boolean finished()
   {
-    setDictionary (buf, 0, buf.length);
+    return is_finished;
   }
 
-  public native void setDictionary (byte[] buf, int off, int len);
+  /**
+   * Returns true, if the input buffer is empty.
+   * You should then call setInput(). <br>
+   *
+   * <em>NOTE</em>: This method can also return true when the stream
+   * was finished.  
+   */
+  public native boolean needsInput();
 
-  public void setInput (byte[] buf)
+  /**
+   * Sets the data which should be compressed next.  This should be only
+   * called when needsInput indicates that more input is needed.
+   * If you call setInput when needsInput() returns false, the
+   * previous input that is still pending will be thrown away.
+   * The given byte array should not be changed, before needsInput() returns
+   * true again.
+   * This call is equivalent to <code>setInput(input, 0, input.length)</code>.
+   * @param input the buffer containing the input data.
+   * @exception IllegalStateException if the buffer was finished() or ended().
+   */
+  public void setInput(byte[] input)
   {
-    setInput (buf, 0, buf.length);
+    setInput(input, 0, input.length);
   }
 
-  public native void setInput (byte[] buf, int off, int len);
+  /**
+   * Sets the data which should be compressed next.  This should be
+   * only called when needsInput indicates that more input is needed.
+   * The given byte array should not be changed, before needsInput() returns
+   * true again.
+   * @param input the buffer containing the input data.
+   * @param off the start of the data.
+   * @param len the length of the data.  
+   * @exception IllegalStateException if the buffer was finished() or ended()
+   * or if previous input is still pending.
+   */
+  public native void setInput(byte[] input, int off, int len);
 
-  public synchronized void setLevel (int lvl)
+  /** 
+   * Sets the compression level.  There is no guarantee of the exact
+   * position of the change, but if you call this when needsInput is
+   * true the change of compression level will occur somewhere near
+   * before the end of the so far given input.  
+   * @param lvl the new compression level.
+   */
+  public synchronized void setLevel(int lvl)
   {
     if (lvl != -1 && (lvl < 0 || lvl > 9))
-      throw new IllegalArgumentException ();
+      throw new IllegalArgumentException();
     level = (lvl == -1) ? 6 : lvl;
-    update ();
+    update();
   }
 
-  public synchronized void setStrategy (int stgy)
+  /** 
+   * Sets the compression strategy. Strategy is one of
+   * DEFAULT_STRATEGY, HUFFMAN_ONLY and FILTERED.  For the exact
+   * position where the strategy is changed, the same as for
+   * setLevel() applies.
+   * @param stgy the new compression strategy.
+   */
+  public synchronized void setStrategy(int stgy)
   {
     if (stgy != DEFAULT_STRATEGY && stgy != FILTERED
 	&& stgy != HUFFMAN_ONLY)
-      throw new IllegalArgumentException ();
+      throw new IllegalArgumentException();
     strategy = stgy;
-    update ();
+    update();
   }
 
-  // Compression level.
-  private int level;
-
-  // Compression strategy.
-  private int strategy;
+  /**
+   * Deflates the current input block to the given array.  It returns 
+   * the number of bytes compressed, or 0 if either 
+   * needsInput() or finished() returns true or length is zero.
+   * @param output the buffer where to write the compressed data.
+   */
+  public int deflate(byte[] output)
+  {
+    return deflate(output, 0, output.length);
+  }
 
-  // The zlib stream.
-  private RawData zstream;
+  /**
+   * Deflates the current input block to the given array.  It returns 
+   * the number of bytes compressed, or 0 if either 
+   * needsInput() or finished() returns true or length is zero.
+   * @param output the buffer where to write the compressed data.
+   * @param offset the offset into the output array.
+   * @param length the maximum number of bytes that may be written.
+   * @exception IllegalStateException if end() was called.
+   * @exception IndexOutOfBoundsException if offset and/or length
+   * don't match the array length.  
+   */
+  public native int deflate(byte[] output, int off, int len);
 
-  // True if finished.
-  private boolean is_finished;
+  /**
+   * Sets the dictionary which should be used in the deflate process.
+   * This call is equivalent to <code>setDictionary(dict, 0,
+   * dict.length)</code>.  
+   * @param dict the dictionary.  
+   * @exception IllegalStateException if setInput () or deflate ()
+   * were already called or another dictionary was already set.  
+   */
+  public void setDictionary(byte[] dict)
+  {
+    setDictionary(dict, 0, dict.length);
+  }
 
-  // `Flush' flag to pass to next call to deflate.
-  private int flush_flag;
+  /**
+   * Sets the dictionary which should be used in the deflate process.
+   * The dictionary should be a byte array containing strings that are
+   * likely to occur in the data which should be compressed.  The
+   * dictionary is not stored in the compressed output, only a
+   * checksum.  To decompress the output you need to supply the same
+   * dictionary again.
+   * @param dict the dictionary.
+   * @param offset an offset into the dictionary.
+   * @param length the length of the dictionary.
+   * @exception IllegalStateException if setInput () or deflate () were
+   * already called or another dictionary was already set.
+   */
+  public native void setDictionary(byte[] buf, int off, int len);
 }