Are the javadocs for java.net.http.HttpResponse.body() misleading or am I wrong?
This has caused some internal discussion, so I wanted to look for external input.
If you have ever used the newer java.net.http implementation, you probably have used the HttpResponse.body() method to retrieve the response body. It usually looks something like this:
HttpClient client = HttpHelper.client();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("<uri>"))
.POST(HttpRequest.BodyPublishers.ofString(content))
.build();
HttpResponse<String> res = client.send(request, HttpResponse.BodyHandlers.ofString());
// Can this be null?
String bodyString = res.body();
Then, looking at the javadocs for the body() method, it says:
* Returns the body. Depending on the type of {@code T}, the returned body
* may represent the body after it was read (such as {@code byte[]}, or
* {@code String}, or {@code Path}) or it may represent an object with
* which the body is read, such as an {@link java.io.InputStream}.
*
* <p> If this {@code HttpResponse} was returned from an invocation of
* {@link #previousResponse()} then this method returns {@code null}
*
* @return the body
Here is how I interpreted this: Assuming that there is no IOException thrown, the request must have gone through (even if it returned something like a HTTP 500) and we should have response body. Since we don't use the previousResponse() method, the note about null values does not apply here. The rest of the javadocs don't mention anything about null, so I implicitly assumed that it does not return null. If there is an empty body, then it returns an empty String/byte[]/whatever. The BodyHandlers javadocs don't mention anything about null return values.
But the method returns null for something like HTTP 407 Proxy Authentication Required.
So my question is: If you read the javadocs of a JDK method and it does not mention null return values, do you interpret this as that the method does not return null? Or do you still perform null checks as the javadocs also didn't mention about not returning null?
