RFR: 8331195: Improve com.sun.net.httpserver.HttpExchange usability [v3]

[Mark Sheppard]

On Fri, 26 Apr 2024 15:37:13 GMT, robert engels <duke at openjdk.org> wrote:

>> improve the HttpExchange api with documented constants and convenience methods to avoid common bugs
>
> robert engels has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java
>   
>   Co-authored-by: Michael McMahon <70538289+Michael-Mc-Mahon at users.noreply.github.com>

a bit of feedback on this from a usability perspective

The objective of the PR is to improve the usability of HttpExchange.
3 methods are proposed
sendResponseHeadersNoContent
sendResponseHeaderChunked
sendResponseHeaders

The method descriptions do not align with the semantics embedded in their names
The chunked encoding one is very misleading.

sendResponseHeadersNoContent, but this also invokes a closes on the HttpExchange,  a more appropriate name might be sendNoContentResponse(. . . )

sendResponseHeaderChunked The description implies that this method is sending a chunked response, but the method is not doing that. As such its description is not semantically correct. It returns an OutputStream but that will not guarantee sending a chunked response i.e. sending the body in a chunked transfer encoded format. As such the method is sending responses headers and should be setting the transfer-encoding header to chunked. But is is not 

Suggested name if setting TE to chunked

sendResponseHeaderWithChunkedTransferEncoding(. . .) 

A convenience method would be to setting Transfer-Encoding header and actually perform the chunked encoding of the response body as well.

sendResponseHeader — description says sends fixed length response. But the implementation is actually sending the full response i.e. headers and response body. As such an appropriate name would be sendFixedLengthResponse(…) and it is doing more than just send headers.

Having method names that convey more precise semantics would improve usability.  My current interpretation is that is not the case here.

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

PR Comment: https://git.openjdk.org/jdk/pull/18955#issuecomment-2088309870