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

[Jaikiran Pai]

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.

Hello Josiah,

> To talk more about the change specifically, it seems to imply that all implementations of the API/SPI should be intended for testing use cases. There are already [multiple fully featured implementations of the API/SPI](https://mail.openjdk.org/pipermail/core-libs-dev/2024-January/118266.html) (Jetty has one for example), so is this really the correct thing to say?
> 
> perhaps the wording can be amended to something of the effect of
> 
> > The default implementation provided by this module is intended
> > for simple usages...

The API and the SPI provided by the jdk.httpserver module have been designed to provide the basic minimal support to implement an HttpServer that is capable of handling a request response cycle over HTTP. The JDK's implementation of the HttpServer itself provides a partial implementation of HTTP/1.1.

The proposed text is meant to make it clear that it was not the goal of this module to provide a HTTP server fit for production deployment to be implemented. Nor is it a goal of this module at this time to consider adding support to the API/SPI for newer HTTP protocol versions or other protocols. Furthermore, medium or bigger sized changes to the API/SPI may not always be done even if such changes might provide a more feature rich implementation of a HttpServer. Such enhancements to the API or the SPI would likely thus be implemented by the external server implementations themselves, in their own projects.

Like you note, there are existing external implementations based on this SPI/API which provide a full feature server. This proposed text isn't meant to imply that existing API/SPI contract will be broken (in fact, nothing is being deprecated).

Ultimately, in its current form the entire jdk.httpserver module, including the API, SPI and the JDK's implementation has a very narrow focus of being a simple and minimal HTTP server that allows usages like development time testing (bringing the up a server instance, issuing a request to the server and expecting some respone) and support for tools like jwebserver. Any enhancements to the API/SPI of this module are very closely tied to such usages of the HTTP server within the JDK or for such JDK tools.

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

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