Deflater enhancements

[Xueming Shen]

The 100 in sample really means a "big enough" buffer here for simple use case, not
necessarily means a "fixed size' buffer. Sure there is always room for doc improvement,
especially given this is the API has been there for decade.

Deflater/Inflater.end() is for explicitly/proactively release of the memory resource
held by the deflater/inflater, it does not have impact to the deflating/inflating result.
the end() will be invoked by the finalizer.

It might be reasonable to simply have a pair of static utility methods

byte[] Deflater.deflate(byte[]);
byte[] Inflater.deflate(byte[]);

For the casual/simple/easy use scenario.

Sherman

On 10/08/2013 03:24 AM, Stephen Colebourne wrote:
> I've been trying to use Deflater today and found it rather tricky. Two
> thoughts...
>
> 1) The class level Javadoc specifies a fixed size byte array of 100.
> http://download.java.net/jdk8/docs/api/java/util/zip/Deflater.html
>
> > From what I can tell from other searching and basic common sense, this
> cannot be right as the output size could well be bigger than 100.
> However, there is no real information in the Deflater class as to how
> the class is supposed to be used. I don't believe that kind of broken
> example is helpful.
>
> The best I found was
> http://java.dzone.com/articles/how-compress-and-uncompress
> which proposed a loop:
> Deflater deflater = new Deflater();
> deflater.setInput(data);
> ByteArrayOutputStream outputStream = new ByteArrayOutputStream(data.length);
> deflater.finish();
> byte[] buffer = new byte[1024];
> while (!deflater.finished()) {
>   int count = deflater.deflate(buffer); // returns the generated code... index
>   outputStream.write(buffer, 0, count);
> }
> outputStream.close();
> byte[] output = outputStream.toByteArray();
>
> Neither example call deflater.end(), which I believe to be a mistake as well.
>
> Is my analysis correct? Should I raise a bug for better documentation?
> (this appears to affect Inflater as well)
>
> 2) Even with the Javadoc change, the API is still far too complex.
>
> As a user, all I want is something like:
>   byte[] compressed = Deflater.deflate(input, options...)
> and similar for Inflater.
>
> (I actually want to compress a String, and an override to handle that
> would be useful as well)
>
> Any thoughts on adding a convenience method to make the API a lot
> easier? Can I raise a bug for that?
>
> Stephen