From fc7fb9e5d71f11a85a6ae3c9a0152dfdb8ccba79 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Tue, 14 Apr 2020 23:28:43 +0200 Subject: [PATCH] Improvements to the Jetty server documentation. Removed the old Handler documentation, already replaced by the new one. Signed-off-by: Simone Bordet --- .../old_docs/handlers/chapter.adoc | 22 --- .../handlers/writing-custom-handlers.adoc | 176 ------------------ .../embedded-guide/old_docs/server.adoc | 2 - .../server/http/server-http-application.adoc | 13 +- .../http/server-http-handler-implement.adoc | 2 +- .../embedded-guide/server/server.adoc | 2 + 6 files changed, 11 insertions(+), 206 deletions(-) delete mode 100644 jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/chapter.adoc delete mode 100644 jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/writing-custom-handlers.adoc diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/chapter.adoc b/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/chapter.adoc deleted file mode 100644 index ec0b8bba510..00000000000 --- a/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/chapter.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// -// ======================================================================== -// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. -// -// This program and the accompanying materials are made available under -// the terms of the Eclipse Public License 2.0 which is available at -// https://www.eclipse.org/legal/epl-2.0 -// -// This Source Code may also be made available under the following -// Secondary Licenses when the conditions for such availability set -// forth in the Eclipse Public License, v. 2.0 are satisfied: -// the Apache License v2.0 which is available at -// https://www.apache.org/licenses/LICENSE-2.0 -// -// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 -// ======================================================================== -// - -[[jetty-handlers]] -== Handlers - -include::writing-custom-handlers.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/writing-custom-handlers.adoc b/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/writing-custom-handlers.adoc deleted file mode 100644 index 026007fe3ee..00000000000 --- a/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/writing-custom-handlers.adoc +++ /dev/null @@ -1,176 +0,0 @@ -// -// ======================================================================== -// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others. -// -// This program and the accompanying materials are made available under -// the terms of the Eclipse Public License 2.0 which is available at -// https://www.eclipse.org/legal/epl-2.0 -// -// This Source Code may also be made available under the following -// Secondary Licenses when the conditions for such availability set -// forth in the Eclipse Public License, v. 2.0 are satisfied: -// the Apache License v2.0 which is available at -// https://www.apache.org/licenses/LICENSE-2.0 -// -// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 -// ======================================================================== -// - -[[writing-custom-handlers]] -=== Writing Custom Handlers - -The Handler is the Jetty component that deals with received requests. - -Many users of Jetty never need to write a Jetty Handler, but instead use the link:{JDURL}/org/eclipse/jetty/servlet/package-summary.html[Servlet API.] -You can reuse the existing Jetty handlers for context, security, sessions and servlets without the need for extension. -However, some users might have special requirements or footprint concerns that prohibit the use of the full servlet API. -For them implementing a Jetty handler is a straight forward way to provide dynamic web content with a minimum of fuss. - -See the section on xref:basic-architecture[] to understand more about Handlers vs. Servlets. - -[[handler-api]] -==== The Handler API - -The link:{JDURL}/org/eclipse/jetty/server/Handler.html[Handler] interface provides Jetty's core of content generation or manipulation. -Classes that implement this interface are used to coordinate requests, filter requests and generate content. - -The core API of the Handler interface is: - -[source, java, subs="{sub-order}"] ----- -public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) - throws IOException, ServletException ----- - -An implementation of this method can handle a request and pass the request onto another handler (or servlet), or it can modify and/or wrap the request before passing it on. -This gives three styles of handler: - -* Coordinating Handlers - Handlers that route requests to other handlers (`HandlerCollection`, `ContextHandlerCollection`) -* Filtering Handlers - Handlers that augment a request and pass it on to other handlers (`HandlerWrapper`, `ContextHandler`, `SessionHandler`) -* Generating Handlers - Handlers that produce content (`ResourceHandler` and `ServletHandler`) - -[[target]] -===== The Target - -The target of a handler is an identifier for the resource that should handle the passed request. -This is normally the URI that is parsed from an HTTP Request. -However, in two key circumstances the target may differ from the URI of the passed request: - -* If the request has been dispatched to a named resource, such as a named servlet, the target is the name of that resource. -* If the request is being made by a call to link:http://docs.oracle.com/javaee/7/api/javax/servlet/RequestDispatcher.html[`RequestDispatcher`], the target is the URI of the included resource and is different to the URI of the actual request. - -[[request-and-response]] -===== The Request and Response - -The request and response objects used in the signature of the handle method are -link:http://docs.oracle.com/javaee/7/api/javax/servlet/ServletRequest.html[`ServletRequest`] and link:http://docs.oracle.com/javaee/7/api/javax/servlet/ServletResponse.html[`ServletResponse`]. -These are the standard APIs and are moderately restricted in what they can do to the request and response. -More often than not, access to the Jetty implementations of these classes is required: link:{JDURL}/org/eclipse/jetty/server/Request.html[`Request`] and link:{JDURL}/org/eclipse/jetty/server/Response.html[`Response`]. -However, as the request and response may be wrapped by handlers, filters and servlets, it is not possible to pass the implementation directly. -The following mantra retrieves the core implementation objects from under any wrappers: - -[source, java, subs="{sub-order}"] ----- -Request base_request = request instanceof Request ? (Request)request : HttpConnection.getCurrentConnection().getHttpChannel().getRequest(); -Response base_response = response instanceof Response ? (Response)response : HttpConnection.getCurrentConnection().getHttpChannel().getResponse(); ----- - -Notice that if the handler passes the request on to another handler, it should use the Request/Response objects passed in, and not the base objects. -This is to preserve any wrapping done by up stream handlers. - -[[dispatch]] -===== The Dispatch - -The dispatch argument indicates the state of the handling of the call and may be: - -* `REQUEST == 1` - An original request received from a connector. -* `FORWARD == 2` - A request being forwarded by a RequestDispatcher. -* `INCLUDE == 4` - A request being included by a RequestDispatcher. -* `ERROR == 8` - A request being forwarded to a error handler by the container. - -These mostly have significance for servlet and related handlers. -For example, the security handler only applies authentication and authorization to REQUEST dispatches. - -[[handling-requests]] -==== Handling Requests - -A Handler may handle a request by: - -* xref:generating-response[] -* xref:filtering-request-or-response[] -* xref:passing-request-and-response[] - -[[generating-response]] -===== Generating a Response - -The link:{JDURL}/org/eclipse/jetty/embedded/OneHandler.html[`OneHandler`] embedded example shows how a simple handler can generate a response. - -You can use the standard servlet response API, which will typically set some status, content headers and then write out the content: - -[source, java, subs="{sub-order}"] ----- - response.setContentType("text/html"); - response.setStatus(HttpServletResponse.SC_OK); - response.getWriter().println("

Hello OneHandler

"); ----- - -It is also very important that a handler indicate that it has completed handling the request and that the request should not be passed to other handlers: - -[source, java, subs="{sub-order}"] ----- - Request base_request = (request instanceof Request) ? (Request)request:HttpConnection.getCurrentConnection().getHttpChannel().getRequest(); - base_request.setHandled(true); ----- - -[[filtering-request-or-response]] -===== Filtering the Request and/or Response - -Once the base request or response object is obtained, you can modify it. -Typically you would make modifications to accomplish: - -* Breaking the URI into contextPath, servletPath and pathInfo components. -* Associating a resource base with a request for static content. -* Associating a session with a request. -* Associating a security principal with a request. -* Changing the URI and paths during a request dispatch forward to another resource. - -You can also update the context of the request: - -* Setting the current threads context classloader. -* Setting thread locals to identify the current `ServletContext`. - -Typically Jetty passes a modified request to another handler and undoes modifications in a finally block afterwards: - -[source, java, subs="{sub-order}"] ----- - try - { - base_request.setSession(a_session); - next_handler.handle(target,request,response,dispatch); - } - finally - { - base_request.setSession(old_session); - } ----- - -The classes that implement the link:{JDURL}/org/eclipse/jetty/server/handler/HandlerWrapper.html[`HandlerWrapper`] class are typically handler filters of this style. - -[[passing-request-and-response]] -===== Passing the Request and Response to Another Handler - -A handler might simply inspect the request and use the target, request URI or other information to select another handler to pass the request to. -These handlers typically implement the link:{JDURL}/org/eclipse/jetty/server/HandlerContainer.html[`HandlerContainer`] interface. - -Examples include: - -* link:{JDURL}/org/eclipse/jetty/server/handler/HandlerCollection.html[Class `HandlerCollection`] - -A collection of handlers, where each handler is called regardless of the state of the request. -This is typically used to pass a request to a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandlerCollection.html[`ContextHandlerCollection`,] and then the link:{JDURL}/org/eclipse/jetty/server/handler/RequestLogHandler.html[`RequestLogHandler`.] -* link:{JDURL}/org/eclipse/jetty/server/handler/HandlerList.html[`HandlerList`] - A list of handlers that are called in turn until the request state is set as handled. -* link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandlerCollection.html[`ContextHandlerCollection`] - A collection of Handlers, of which one is selected by best match for the context path. - -[[more-about-handlers]] -==== More About Handlers - -See the link:{JDURL}/[latest Jetty JavaDoc] for detailed information on each Jetty handler. diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/server.adoc b/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/server.adoc index bfd8444bab5..d8ade48b4b4 100644 --- a/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/server.adoc +++ b/jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/server.adoc @@ -21,8 +21,6 @@ include::embedding/chapter.adoc[] include::maven/chapter.adoc[] -include::clients/http/chapter.adoc[] -include::handlers/chapter.adoc[] include::websockets/intro/chapter.adoc[] include::websockets/jetty/chapter.adoc[] include::ant/chapter.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/server/http/server-http-application.adoc b/jetty-documentation/src/main/asciidoc/embedded-guide/server/http/server-http-application.adoc index c872ac8e57d..dcd6600898e 100644 --- a/jetty-documentation/src/main/asciidoc/embedded-guide/server/http/server-http-application.adoc +++ b/jetty-documentation/src/main/asciidoc/embedded-guide/server/http/server-http-application.adoc @@ -20,7 +20,7 @@ === Writing HTTP Server Applications Writing HTTP applications is typically simple, especially when using blocking APIs. -However, there are more subtle cases where it is worth clarifying what a server application should do to obtain the desired results when deployed in Jetty. +However, there are subtle cases where it is worth clarifying what a server application should do to obtain the desired results when run by Jetty. [[eg-server-http-application-1xx]] ==== Managing 1xx Responses @@ -44,12 +44,15 @@ include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=continue ---- [[jetty-102-processing]] -==== 102 Processing +===== 102 Processing -link:https://tools.ietf.org/html/rfc2518#section-10.1[RFC 2518] defined the `102 Processing` status code that can be sent "when the server has a reasonable expectation that the request will take significant time to complete. -As guidance, if a method is taking longer than 20 seconds (a reasonable, but arbitrary value) to process the server SHOULD return a `102 Processing` response". +link:https://tools.ietf.org/html/rfc2518[RFC 2518] defined the `102 Processing` status code that can be sent: -However a later update of RFC 2518, link:https://tools.ietf.org/html/rfc4918[RFC 4918], removed the `102 Processing` status code for link:https://tools.ietf.org/html/rfc4918#appendix-F.3["lack of implementation"]. +[quote,RFC 2518 section 10.1] +when the server has a reasonable expectation that the request will take significant time to complete. +As guidance, if a method is taking longer than 20 seconds (a reasonable, but arbitrary value) to process the server SHOULD return a `102 Processing` response. + +However, a later update of RFC 2518, link:https://tools.ietf.org/html/rfc4918[RFC 4918], removed the `102 Processing` status code for link:https://tools.ietf.org/html/rfc4918#appendix-F.3["lack of implementation"]. Jetty supports the `102 Processing` status code. If a request is received with the `Expect: 102-processing` header, then a filter/servlet may send a `102 Processing` response (without terminating further processing) by calling `response.sendError(102)`. diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/server/http/server-http-handler-implement.adoc b/jetty-documentation/src/main/asciidoc/embedded-guide/server/http/server-http-handler-implement.adoc index 625d206f2e0..36dc9df088d 100644 --- a/jetty-documentation/src/main/asciidoc/embedded-guide/server/http/server-http-handler-implement.adoc +++ b/jetty-documentation/src/main/asciidoc/embedded-guide/server/http/server-http-handler-implement.adoc @@ -67,5 +67,5 @@ include::../../{doc_code}/embedded/server/http/HTTPServerDocs.java[tags=handlerF Note how a filtering `Handler` extends from `HandlerWrapper` and as such needs another handler to forward the request processing to, and how the -two``Handler``s needs to be linked together to work properly. +two ``Handler``s needs to be linked together to work properly. diff --git a/jetty-documentation/src/main/asciidoc/embedded-guide/server/server.adoc b/jetty-documentation/src/main/asciidoc/embedded-guide/server/server.adoc index a8cc9ceffd2..79feeefb8da 100644 --- a/jetty-documentation/src/main/asciidoc/embedded-guide/server/server.adoc +++ b/jetty-documentation/src/main/asciidoc/embedded-guide/server/server.adoc @@ -45,6 +45,8 @@ xref:eg-server-http2[HTTP/2 libraries] * WebSocket support, for applications that want to embed a WebSocket server, via the xref:eg-server-websocket[WebSocket libraries] +// TODO: add a section on lifecycle and the component tree. + include::http/server-http.adoc[] include::http2/server-http2.adoc[] include::websocket/server-websocket.adoc[]