RFR: 8322256: Define and document GZIPInputStream concatenated stream semantics [v2]

[Lance Andersen]

On Fri, 30 Aug 2024 11:18:41 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> I wonder if we can dig up the discussion on JDK-4691425. I can't find the CSR (or "CCC" at the time) that would have captured the reasoning for supporting this.
>
>> I wonder if we can dig up the discussion on JDK-4691425. I can't find the CSR (or "CCC" at the time) that would have captured the reasoning for supporting this.
> 
> The gnu.org docs cover this(concatenating gzip files)  as part of its [advanced usage of gzip](https://github.com/openjdk/jdk/pull/20787#issuecomment-2320873616), so I don'r think we need to do any more archeology

> @LanceAndersen @jaikiran
> 
> I have updated the API documentation in this PR inspired by the following comment from @jaikiran in Archie's PR:
> 
> [#18385 (comment)](https://github.com/openjdk/jdk/pull/18385#issuecomment-2265378324)
> 
> I aimed to keep this at a high level, avoiding any details of the GZIP file format and the parsing logic involved in the implementation:
> 
> ```
>  * <p>
>  * The {@code InputStream} passed to the constructor of this class may represent
>  * a single GZIP file or multiple consecutive GZIP files. When the end of a
>  * GZIP file is immediately followed by a new GZIP file, this class continues
>  * to decode compressed data into a single, concatenated stream of uncompressed
>  * data. Otherwise, any additional trailing bytes following a GZIP file are
>  * discarded as if the end of stream is reached
> ```
> 
> I also made a pass over the tests with my suggested improvement from the previous PR.
> 
> What do you think?

I think we are closer and this reads much better.,  I still think we can add a mention the GZIP header/trailer similar to  what we did for ZipInputStream:

> The [getNextEntry()](https://download.java.net/java/early_access/jdk23/docs/api/java.base/java/util/zip/ZipInputStream.html#getNextEntry()) method is used to read the next ZIP file entry (Local file (LOC) header record in the ZIP format)

Thank you for picking this up.  Will look at the test a bit later this morning my time after some coffee :-)

-------------

PR Comment: https://git.openjdk.org/jdk/pull/20787#issuecomment-2320951192