<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Chapter&nbsp;30.&nbsp;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&nbsp;V.&nbsp;Jetty Reference Guide"><link rel="prev" href="jetty-ref-guide.html" title="Part&nbsp;V.&nbsp;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.3.27.v20190418</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&nbsp;30.&nbsp;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>&nbsp;</td><th width="60%" align="center">Part&nbsp;V.&nbsp;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">&nbsp;<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&nbsp;30.&nbsp;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.3.27.v20190418/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> &#8211; the target of the request, either a URI or a name.</li><li class="listitem"><code class="literal">baseRequest</code> &#8211; the original unwrapped request object.</li><li class="listitem"><code class="literal">request</code> &#8211; 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 &#8211; 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 &#8211; handlers that route requests to other handlers (<code class="literal">HandlerCollection</code>, <code class="literal">ContextHandlerCollection</code>)</li><li class="listitem">Filtering handlers &#8211; 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 &#8211; 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>&nbsp;</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">&nbsp;<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&nbsp;V.&nbsp;Jetty Reference Guide&nbsp;</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">&nbsp;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: 2019-04-18)</i></span></div></p></body></html>