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

[robert engels]

On Wed, 1 May 2024 21:12:05 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 two additional commits since the last revision:
> 
>  - Merge remote-tracking branch 'robaho/HttpExchange-api-change' into HttpExchange-api-change
>    
>    # Conflicts:
>    #	src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java
>  - update api changes based on comments

> My reasoning is as follows
> 
> * Once we add something, we can't remove it. Even if we deprecate it, it will still be there
> * The ideal API, in my head, is something like the following
> 
> ```java
> exchange.sendResponseHeaders(200, ResponseLength.unknown());
> exchange.sendResponseHeaders(200, ResponseLength.known(0));
> exchange.sendResponseHeaders(200, ResponseLength.known(body.length));
> 
> exchange.sendResponse(200, Body.of("Hello, world"));
> ```
> 
>  * That API, specifically `Body.of`, would be more naturally tempting to use.
> * If we have `ResponseLength.unknown()` and `ResponseLength.known(0)` as options, the constants are redundant
> * The constants do not address the case of "you get an arbitrarily sized bit of data, send it". People still need to do `thing.length == 0 ? -1 : thing.length` checks.
> * Why would we add something that could be deprecated if we just found the time to reach consensus on the direction of the API?

My thoughts are those api methods are not as good as:


sendResponseUnknown(int code)
sendResponseFixed()
sendResponseNoContent()


To your point about getting developers to read, why make everyone go one level deeper?


You could also have,


sendResponse(int code,Body object)


that could delegate to the proper header methods, and send the Body. Technically, the additional response header methods are not needed only this one with a proper Body interface.

That would be ideal in my opinion.

I was trying to go down that route, but then some people complained that the changes were too involved, needed extended review, etc. so the CONSTANTS were chosen under the idea that it does make things more readable now, with little downside for later. Maybe the real issue, is that it takes too much effort to make fairly trivial (and analogous to existing ones) api changes?

Anyway, this seems to be right back where it started, so I will let the powers that be decide what to do, but I get the feeling it will be nothing. Not that that isn't often the best option - but I don't think that's the case here.

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

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