From cc2cef17320f107150b7a912e1f3983c75b5f58f Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Tue, 13 Aug 2024 10:50:40 +0200 Subject: [PATCH] Fixes #12158 - Jetty12 migration help. Updated documentation with section about migration of Handler code from Jetty 11 to Jetty 12. Signed-off-by: Simone Bordet --- .../pages/migration/11-to-12.adoc | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/documentation/jetty/modules/programming-guide/pages/migration/11-to-12.adoc b/documentation/jetty/modules/programming-guide/pages/migration/11-to-12.adoc index 4e27583344b..02f92c78e3b 100644 --- a/documentation/jetty/modules/programming-guide/pages/migration/11-to-12.adoc +++ b/documentation/jetty/modules/programming-guide/pages/migration/11-to-12.adoc @@ -99,6 +99,15 @@ | `org.eclipse.jetty.websocket.api.**WebSocketPolicy**` | `org.eclipse.jetty.websocket.api.**Configurable**` |=== +== Server-Side Web Application APIs Changes + +Jetty 12 introduced redesigned server-side APIs for web applications. +In Jetty 11, these APIs were based on a mix of Jakarta Servlet APIs and Jetty Handler APIs, while in Jetty 12 they are solely based on Jetty Handler APIs. + +In Jetty 12 you can now write web applications independently of the Servlet APIs, so you can migrate Jakarta Servlets to Jetty Handlers as explained in xref:servlet-to-handler[this section]. + +If you were already using the Jetty 11 Handler APIs, you can migrate them to the Jetty 12 Handler APIs as explained in xref:api-changes-handler[this section]. + [[servlet-to-handler]] == Migrate Servlets to Jetty Handlers @@ -126,6 +135,8 @@ include::code:example$src/main/java/org/eclipse/jetty/docs/programming/migration include::code:example$src/main/java/org/eclipse/jetty/docs/programming/migration/ServletToHandlerDocs.java[tags=requestContent-source] ---- +Refer also to the `Content.Source` APIs detailed in xref:arch/io.adoc#content-source[this section]. + === Handler Response APIs [,java,indent=0] ---- @@ -150,9 +161,48 @@ include::code:example$src/main/java/org/eclipse/jetty/docs/programming/migration include::code:example$src/main/java/org/eclipse/jetty/docs/programming/migration/ServletToHandlerDocs.java[tags=responseContent-trailers] ---- +Refer also to the `Content.Sink` APIs detailed in xref:arch/io.adoc#content-sink[this section]. + [[api-changes]] == APIs Changes +[[api-changes-handler]] +=== `Handler` + +The server-side `Handler` class, and the APIs to use for request/response processing, have been redesigned in Jetty 12. + +The Jetty 11 `Handler` method: + +`Handler.handle(String target, Request jettyRequest, HttpServletRequest request, HttpServletResponse response)` + +has been changed in Jetty 12 to: + +`Handler.handle(Request request, Response response, Callback callback)` + +The Jetty 11 `target` parameter has been removed, and in Jetty 12 it has been replaced by the information present in `Request.getHttpURI()`. + +In Jetty 11, ``Handler``s would mark the fact that they handled the request, and therefore are producing a response, by calling `Request.setHandled(true)`. +In Jetty 12, this is performed by returning `true` from the `Handler.handle(\...)` method, which also requires that the `Callback` parameter must be completed, either by succeeding it or failing it. + +In Jetty 11, the `Handler.handle(\...)` method has a blocking semantic, while in Jetty 12 the `Handler.handle(\...)` method has an asynchronous semantic, thanks to the `Callback` parameter. +This means that you can return from the `Handler.handle(\...)` method _before_ the response has been sent, similarly to what you can do with the Servlet APIs when you call `HttpServletRequest.startAsync()`. +Similarly, in Jetty 11 after a call to `startAsync()` you must call `AsyncContext.complete()`, while in Jetty 12 you must complete the `Callback` parameter, either by succeeding it or failing it. + +In Jetty 11, `AbstractHandler` provides a utility class to implement `Handler`. +In Jetty 12, use `Handler.Abstract`. + +In Jetty 11, the APIs to deal with request or response HTTP headers are based on either Jetty's `HttpFields`, or the Servlet APIs. +In Jetty 12, the HTTP headers API are only based on `HttpFields`. +Please refer to the `HttpFields` link:{javadoc-url}/org/eclipse/jetty/http/HttpFields.html[javadocs] for details. + +In Jetty 11, the request content is accessed via `Request.getInputStream()` or `HttpServletRequest.getInputStream()`. +In Jetty 12, the `Request` object itself _is-a_ `Content.Source` that can be read as explained in xref:arch/io.adoc#content-source[this section]. +In Jetty 12, you can use `Content.Source.asInputStream(request)` to obtain an `InputStream` and minimize the changes to your code, but remember that `InputStream` only provides blocking APIs, while `Content.Source` provides non-blocking APIs. + +In Jetty 11, the response content is accessed via `Response.getOutputStream()` or `HttpServletResponse.getOutputStream()`. +In Jetty 12, the `Response` object itself _is-a_ `Content.Sink` that can be written as explained in xref:arch/io.adoc#content-sink[this section]. +In Jetty 12, you can use `Content.Sink.asOutputStream(response)` to obtain an `OutputStream` and minimize the changes to your code, but remember that `OutputStream` only provides blocking APIs, while `Content.Sink` provides non-blocking APIs. + === `HttpClient` The Jetty 11 `Request.onResponseContentDemanded(Response.DemandedContentListener)` API has been replaced by `Request.onResponseContentSource(Response.ContentSourceListener)` in Jetty 12. @@ -165,6 +215,8 @@ The Jetty 12 model is a "demand+pull" model: when the content is available, the For more information about the new model, see xref:arch/io.adoc#content-source[this section]. +Jetty 12 introduced the concept of low-level transport for high-level protocols, described in xref:client/io-arch.adoc#transport[this section]. + === WebSocket The Jetty WebSocket APIs have been vastly simplified, and brought in line with the style of other APIs.