| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Chapter 30. Architecture</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="jetty-ref-guide.html" title="Part V. Jetty Reference Guide"><link rel="prev" href="jetty-ref-guide.html" title="Part V. Jetty Reference Guide"><link rel="next" href="jetty-classloading.html" title="Jetty Classloading"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script> |
| hljs.initHighlightingOnLoad(); |
| </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small"> |
| Version: 9.4.28-SNAPSHOT</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 30. Architecture</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jetty-ref-guide.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a> </td><th width="60%" align="center">Part V. Jetty Reference Guide<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="jetty-classloading.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at |
| <span class="website">www.webtide.com</span></a></h5><p> |
| private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... |
| scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development |
| </p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="architecture"></a>Chapter 30. Architecture</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="architecture.html#basic-architecture">Jetty Architecture</a></span></dt><dt><span class="section"><a href="jetty-classloading.html">Jetty Classloading</a></span></dt><dt><span class="section"><a href="jetty-1xx-responses.html">Managing 1xx Responses</a></span></dt><dt><span class="section"><a href="creating-custom-protocol.html">Creating a Custom Protocol</a></span></dt></dl></div><p>General items related to the architecture of jetty and how it deals with certain design decisions.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="basic-architecture"></a>Jetty Architecture</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="architecture.html#_view_from_20_000_feet">View from 20,000 feet</a></span></dt><dt><span class="section"><a href="architecture.html#_patterns">Patterns</a></span></dt><dt><span class="section"><a href="architecture.html#_connectors">Connectors</a></span></dt><dt><span class="section"><a href="architecture.html#_handlers">Handlers</a></span></dt><dt><span class="section"><a href="architecture.html#what-is-a-context">Contexts</a></span></dt><dt><span class="section"><a href="architecture.html#_web_application">Web Application</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_view_from_20_000_feet"></a>View from 20,000 feet</h3></div></div></div><p>The Jetty <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/server/Server.html" target="_top">Server</a> is the plumbing between |
| a collection of `Connector`s that accept connections and a collection of `Handler`s that |
| service requests from the connections and produce responses, with threads from a thread pool doing the work.</p><p><span class="inlinemediaobject"><img src="images/jetty-high-level-architecture.png" width="576" alt="image"></span></p><p>While the Jetty request/responses are derived from the Servlet API, the full features of the Servlet API |
| are only available if you configure the appropriate handlers. |
| For example, the session API on the request is inactive unless the request has been passed to a <code class="literal">SessionHandler</code>. |
| The concept of a Servlet itself is implemented by a <code class="literal">ServletHandler</code>. |
| If Servlets are not required, there is very little overhead in the use of the servlet request/response APIs. |
| Thus you can build a Jetty server using only connectors and handlers, without using Servlets.</p><p>The job of configuring Jetty is building a tree of connectors and handlers and providing their individual configurations. |
| As Jetty components are simply Plain Old Java Objects (POJOs), you can accomplish this assembly |
| and configuration of components by a variety of techniques:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">In code, see the examples in the Jetty Source XRef.</li><li class="listitem">Using Jetty XML, a dependency injection style in XML format.</li><li class="listitem">With your dependency injection framework of choice, Spring or XBean.</li><li class="listitem">Using Jetty WebApp and Context Deployers.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_patterns"></a>Patterns</h3></div></div></div><p>The implementation of Jetty follows some fairly standard patterns. |
| Most abstract concepts such as <code class="literal">Connector`s and `Handler`s are captured by interfaces. |
| Generic handling for those interfaces is then provided in an abstract implementation |
| such as `AbstractConnector</code> and <code class="literal">AbstractHandler</code>.</p><p><span class="inlinemediaobject"><img src="images/basic-architecture-patterns.png" width="576" alt="image"></span></p><p>The JSR77 inspired life cycle of most Jetty components is represented by the <code class="literal">LifeCycle</code> |
| interface and the <code class="literal">AbstractLifeCycle</code> implementation used as the base of many Jetty components.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_connectors"></a>Connectors</h3></div></div></div><p>A <code class="literal">Connector</code> is the component that accepts TCP connections. |
| For each accepted TCP connection, the <code class="literal">Connector</code> asks a <code class="literal">ConnectionFactory</code> to create |
| a <code class="literal">Connection</code> object that handles the network traffic on that TCP connection, parsing |
| and generating bytes for a specific protocol.</p><p>A <code class="literal">ServerConnector</code> can therefore be configured with one or more <code class="literal">ConnectionFactory</code>.</p><p>The simplest case is a single <code class="literal">ConnectionFactory</code> such as <code class="literal">HttpConnectionFactory</code>, that |
| creates <code class="literal">HttpConnection</code> objects that parse and generate bytes for the HTTP/1.1 protocol.</p><p>A more complex case can be a <code class="literal">ServerConnector</code> configured with three factories: |
| <code class="literal">ProxyConnectionFactory</code>, <code class="literal">SslConnectionFactory</code> and <code class="literal">HttpConnectionFactory</code>. |
| Such connector will be able to handle PROXY protocol bytes coming from a load balancer |
| such as HAProxy (with the <code class="literal">ProxyConnectionFactory</code>), then handle TLS bytes (with |
| <code class="literal">SslConnectionFactory</code>) and therefore decrypting/encrypting the bytes from/to a remote |
| client, and finally handling HTTP/1.1 bytes (with <code class="literal">HttpConnectionFactory</code>). |
| Each <code class="literal">ConnectionFactory</code> is asked to create a <code class="literal">Connection</code> object for each TCP connection; |
| the <code class="literal">Connection</code> objects will be chained together to handle the bytes, each for its |
| own protocol. |
| Therefore the <code class="literal">ProxyConnection</code> will handle the PROXY protocol bytes, <code class="literal">SslConnection</code> |
| will handle the encryption/decryption of the bytes, and <code class="literal">HttpConnection</code> will handle |
| the HTTP/1.1 bytes producing a request and response object that will be processed by |
| applications.</p><p>Advanced usages of Jetty will allow users to write their own <code class="literal">ConnectionFactory</code> to |
| handle custom protocols that are not implemented directly by the Jetty project, |
| therefore using Jetty as a generic network server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_handlers"></a>Handlers</h3></div></div></div><p>A <code class="literal">Handler</code> is the component that deals with HTTP requests and responses. |
| The core API of a handler is the handle method:</p><p><span class="inlinemediaobject"><img src="images/basic-architecture-handlers.png" width="576" alt="image"></span></p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException</code></pre><p>Parameters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">target</code> – the target of the request, either a URI or a name.</li><li class="listitem"><code class="literal">baseRequest</code> – the original unwrapped request object.</li><li class="listitem"><code class="literal">request</code> – the request object, either as the <code class="literal">baseRequest</code> object or a wrapper of <code class="literal">baseRequest</code>. |
| You can use the HttpConnection.getCurrentConnection() method to access the Request object if required.</li><li class="listitem">response – the response object, either unwrapped as <code class="literal">Response</code> or a wrapper of that response. |
| You can use the HttpConnection.getCurrentConnection() method to access the <code class="literal">Response</code> object if required.</li></ul></div><p>An implementation of this method can handle the request, pass the request onto another handler (or servlet) |
| or it might modify and/or wrap the request and then pass it on. |
| This gives three styles of Handler:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Coordinating handlers – handlers that route requests to other handlers (<code class="literal">HandlerCollection</code>, <code class="literal">ContextHandlerCollection</code>)</li><li class="listitem">Filtering handlers – handlers that augment a request and pass it on to other handlers (<code class="literal">HandlerWrapper</code>, <code class="literal">ContextHandler</code>, <code class="literal">SessionHandler</code>)</li><li class="listitem">Generating handlers – handlers that produce content (<code class="literal">ResourceHandler</code> and <code class="literal">ServletHandler</code>)</li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_nested_handlers_and_handlers_called_sequentially"></a>Nested Handlers and Handlers Called Sequentially</h4></div></div></div><p>You can combine handlers to handle different aspects of a request by nesting them, |
| calling them in sequence, or by combining the two models.</p><p><span class="inlinemediaobject"><img src="images/basic-architecture-nested-handlers.png" width="576" alt="image"></span></p><p>Handlers called in sequence perform actions that do not depend on the next invocation, nor on the handler order. |
| They handle a request and generate the response without interacting with other handlers. |
| The main class for this model is <code class="literal">HandlerCollection</code>.</p><p>Nested handlers are called according to a before/invokeNext/after pattern. |
| The main class for nested handlers is <code class="literal">HandlerWrapper</code>. |
| Nested handlers are much more common than those called in sequence.</p><p>See also <a class="xref" href="jetty-handlers.html#writing-custom-handlers" title="Writing Custom Handlers">Writing Custom Handlers</a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_servlet_handler"></a>Servlet Handler</h4></div></div></div><p>The <code class="literal">ServletHandler</code> is a <code class="literal">Handler</code> that generates content by passing the request to any |
| configured Servlet Filters and then to a Servlet mapped by a URI pattern.</p><p><span class="inlinemediaobject"><img src="images/basic-architecture-servlet-handler.png" width="576" alt="image"></span></p><p>A <code class="literal">ServletHandler</code> is normally deployed within the scope of a <code class="literal">ServletContext</code>, which is a |
| <code class="literal">ContextHandler</code> that provides convenience methods for mapping URIs to servlets.</p><p>Filters and Servlets can also use a <code class="literal">RequestDispatcher</code> to reroute a request to another context |
| or another Servlet in the current context.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="what-is-a-context"></a>Contexts</h3></div></div></div><p>Contexts are handlers that group other handlers below a particular URI context path or a virtual host. |
| Typically a context can have:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">A context path that defines which requests are handled by the context (e.g. <code class="literal">/myapp</code>)</li><li class="listitem">A resource base for static content (a document root)</li><li class="listitem">A class loader to obtain classes specific to the context (typically from <code class="literal">/WEB-INF/classes</code> and <code class="literal">/WEB-INF/lib</code>)</li><li class="listitem">Virtual host names</li></ul></div><p>Contexts implementations include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">ContextHandler</code></li><li class="listitem"><code class="literal">ServletContextHandler</code></li><li class="listitem"><code class="literal">WebAppContext</code></li></ul></div><p>A web application context combines handlers for security, session and servlets in a single unit |
| that you can configure with a <code class="literal">web.xml</code> descriptor.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_web_application"></a>Web Application</h3></div></div></div><p>A <code class="literal">WebAppContext</code> is a derivation of <code class="literal">ServletContextHandler</code> that supports the standardized layout |
| of a web application and configuration of session, security, listeners, filter, servlets, and JSP |
| via a <code class="literal">web.xml</code> descriptor normally found in the <code class="literal">/WEB-INF</code> directory of a web application.</p><p><span class="inlinemediaobject"><img src="images/basic-architecture-web-application.png" width="576" alt="image"></span></p><p>Essentially <code class="literal">WebAppContext</code> is a convenience class that assists the construction and configuration |
| of other handlers to achieve a standard web application configuration. |
| Configuration is actually done by pluggable implementations of the Configuration class and the |
| prime among these is <code class="literal">WebXmlConfiguration.</code></p></div></div></div><script type="text/javascript"> |
| SyntaxHighlighter.all() |
| </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jetty-ref-guide.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="jetty-ref-guide.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="jetty-classloading.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Part V. Jetty Reference Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top"> Jetty Classloading</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout"> |
| See an error or something missing? |
| <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at |
| <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2020-03-10)</i></span></div></p></body></html> |
