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 the`chunklen` 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.