RFR: 8347348: Clarify that the HTTP server in jdk.httpserver module is not a full featured server

[Ethan McCue]

On Thu, 9 Jan 2025 13:06:55 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

> Can I please get a review of this doc-only change which clarifies the purpose of the HTTP server that's provided in the JDK's `jdk.httpserver` module? This should help avoid any confusion on the purpose of the server.

Hi,

This doc change does not make sense.

> The API, SPI and the server implementation in this module is intended
> for simple usages like local testing, development, and debugging.
> Accordingly, the design and implementation of the server is explicitly
> minimal so as to avoid confusion with a full-featured and high
> performance HTTP server.

I understand that this was originally added for JAX-RS[1] and then eventually with `jwebserver` it was a neat coincidence that it was already there and it became useful for that tool. That tool being intended for a "learning purpose" and the effort required to make an http server that makes everyone happy being so high - it makes sense to then view the whole server api as being for that purpose.

But, its not. The point of an SPI is that alternative implementations can be provided. There is nothing about the API that fundamentally restricts it to local testing, development, and debugging. Adding that to the docs devalues efforts to make decent implementations.

Also, "local testing, development, and debugging" is pretty ill-defined. Both in terms of lifecycle (for what exact things are you allowed to use the server?) and in terms of **what that means for a consumer**. Like, something made for "local dev" might break under random circumstances so long as that occurrence isn't noticed often. To what extent does this mean that the underlying implementation will be left broken for the use case of being a publicly available http server? If you use it for the presumably valid purpose of "development" - when do you then stop using it?

And being minimal "so as to avoid confusion with a full-featured and high performance HTTP server." has echoes of "we trained him wrong, as a joke." Being minimal to avoid being confused with being full featured is an interesting statement. And minimality has nothing intrinsic to do with performance, so its strange to say that by being minimal you are signaling anything about that.

Also - define minimal? Where exactly is the line? There are more minimal http servers out there. 

[1]: https://mail.openjdk.org/pipermail/core-libs-dev/2024-January/118266.html

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

PR Comment: https://git.openjdk.org/jdk/pull/23004#issuecomment-2580212752