Summary

The API documentation of setChunkedStreamingMode() in HttpURLConnection has inaccurate information with respect to the chunklen parameter, used to specify the total chunk length of each individual HTTP chunk.

Problem

The api description of thechunklen parameter for setChunkedStreamingMode() specifies that if a value (in bytes) is passed that is less than or equal to zero, a default chunk length value will be used. This is not the case and in fact if a value less than or equal to 5 is passed, a default value is instead used. The documentation is also not clear on the fact that this parameter is inclusive of the entire length of the HTTP chunk. This includes a hexdecimal string specifying chunk length which at a minimum is 1 byte in length, two CRLF strings being 2 bytes in length each and a payload length of at least 1 byte.

Solution

The documentation now indicates that if a value of 5 bytes or less is used when specifying chunk length, a higher default value is used instead. It also further highlights that the chunklen parameter specifies the total length of the HTTP chunk including the chunk size header, CRLF characters and payload length.

Specification

Given is an inline diff showing the changes.

diff --git a/src/java.base/share/classes/java/net/HttpURLConnection.java b/src/java.base/share/classes/java/net/HttpURLConnection.java
index dba500f017d2..7ac41329d6b8 100644
--- a/src/java.base/share/classes/java/net/HttpURLConnection.java
+++ b/src/java.base/share/classes/java/net/HttpURLConnection.java
@@ -277,9 +277,11 @@ public void setFixedLengthStreamingMode(long contentLength) {
      * <p>
      * This method must be called before the URLConnection is connected.
      *
-     * @param   chunklen The number of bytes to write in each chunk.
-     *          If chunklen is less than or equal to zero, a default
-     *          value will be used.
+     * @param   chunklen The number of bytes to be written in each chunk,
+     *          including a chunk size header as a hexadecimal string
+     *          (minimum of 1 byte), two CRLF's (4 bytes) and a minimum
+     *          payload length of 1 byte. If chunklen is less than or equal
+     *          to 5, a higher default value will be used.
      *
      * @throws  IllegalStateException if URLConnection is already connected
      *          or if a different streaming mode is already enabled.