Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Jetty/Reference/Jetty Architecture"

m (Nested Handlers and Handlers Called Sequentially)
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
=Jetty 7 Architecture=
 
=Jetty 7 Architecture=
 +
 +
{{Jetty Redirect|http://www.eclipse.org/jetty/documentation/current/basic-architecture.html}}
  
 
==View from 20,000 feet==
 
==View from 20,000 feet==
Line 51: Line 53:
 
The [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/Handler.html Handler] is the component that deals with received requests. The core API of a handler is the handle method:
 
The [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/Handler.html Handler] is the component that deals with received requests. The core API of a handler is the handle method:
  
<div class="code panel" style="border-width: 1px"><div class="codeContent panelContent">
+
<source lang="java">
 +
 
 +
public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response)
 +
    throws IOException, ServletException
 +
 
 +
</source>
  
public void handle(String target, HttpServletRequest request, HttpServletResponse response, int dispatch)
+
Parameters:
    throws IOException, ServletException;
+
  
</div></div>
+
* <tt>target</tt>–The target of the request, either a URI or a name.
 +
* <tt>baseRequest</tt>–The original unwrapped request object.
 +
* <tt>request</tt>–The request either as the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/Request.html Request] object or a wrapper of that request. You can use the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/HttpConnection.html HttpConnection.getCurrentConnection()] method to access the Request object if required.
 +
* <tt>response</tt>–The response as the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/Response.html Response] object or a wrapper of that request. You can use the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/HttpConnection.html HttpConnection.getCurrentConnection()] method to access the Response object if required.
  
 
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: <br class="atl-forced-newline" />
 
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: <br class="atl-forced-newline" />
Line 71: Line 80:
  
 
* 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 [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/handler/HandlerCollection.html Handler Collection].
 
* 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 [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/handler/HandlerCollection.html Handler Collection].
* Nested handlers are called according to a before/invokeNext/after pattern. The main class for nested handlers is [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/handler/HandlerWrapper.html Handler Wrappers]. Nested handlers are much more common than those called in sequence.  
+
* Nested handlers are called according to a before/invokeNext/after pattern. The main class for nested handlers is [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/handler/HandlerWrapper.html Handler Wrapper]. Nested handlers are much more common than those called in sequence.  
  
 
See also [http://wiki.eclipse.org/Jetty/Howto/Write_Jetty_Handler Writing a Jetty Handler].
 
See also [http://wiki.eclipse.org/Jetty/Howto/Write_Jetty_Handler Writing a Jetty Handler].

Latest revision as of 15:38, 23 April 2013

Jetty 7 Architecture

Warning2.png
Jetty 7 and Jetty 8 are now EOL (End of Life)




THIS IS NOT THE DOCUMENTATION YOU ARE LOOKING FOR!!!!!






All development and stable releases are being performed with Jetty 9 and Jetty 10.






This wiki is now officially out of date and all content has been moved to the Jetty Documentation Hub






Direct Link to updated documentation: http://www.eclipse.org/jetty/documentation/current/basic-architecture.html


View from 20,000 feet

JettyUML1.png

The Jetty Server is the plumbing between a collection of Connectors that accept HTTP connections, and a collection of Handlers that service requests from the connections and produce responses, with the work being done by threads taken from a thread pool.


Note.png
While the jetty request/responses are derived from the Servlet API, the full features of the servlet API are only available if the appropriate handlers are configured. For example, the session API on the request is inactive unless the request has been passed to a Session Handler. The concept of a Servlet itself is implemented by a Servlet Handler. 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.


The job of configuring jetty is the job of building a network 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:

Patterns

JettyUML2.png

The implementation of Jetty follows some fairly standard patterns. Most abstract concepts such as Connector, Handler and Buffer are captured by interfaces. Generic handling for those interfaces is then provided in an Abstract implementation such as AbstractConnector, AbstractHandler and AbstractBuffer.

The JSR77 inspired life cycle of most jetty components is represented by LifeCycle interface and the AbstractLifeCycle implementation used as the base of many Jetty components.

Jetty provides its own IO Buffering abstract over String, byte arrays and NIO buffers. This allows for greater portability of Jetty as well as hiding some of the complexity of the NIO layer and its advanced features.

Connectors

JettyUML3.png


Note.png
This diagram is a little out of date, as a Connection interface has been extracted out of HttpConnector to allow support for the AJP protocol.


The connectors represent the protocol handlers that accept connections, parse requests and generate responses. The different types of connectors available are based on the protocols, scheduling model and IO APIs used:

Handlers

JettyUML4.png

The Handler is the component that deals with received requests. The core API of a handler is the handle method:

public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException

Parameters:

  • target–The target of the request, either a URI or a name.
  • baseRequest–The original unwrapped request object.
  • request–The request either as the Request object or a wrapper of that request. You can use the HttpConnection.getCurrentConnection() method to access the Request object if required.
  • response–The response as the Response object or a wrapper of that request. You can use the HttpConnection.getCurrentConnection() method to access the Response object if required.

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:

  1. Coordinating Handlers - Handlers that route requests to other handlers (eg HandlerCollection, ContextHandlerCollection)
  2. Filtering Handlers - Handlers that augment a request and pass it on to other handlers (eg. HandlerWrapper, ContextHandler, SessionHandler)
  3. Generating Handlers - Handlers that produce content (eg ResourceHandler and ServletHandler)

Nested Handlers and Handlers Called Sequentially

You can combine handlers to handle different aspects of a request by nesting them, calling them in sequence, or by combining the two models.

Jettynested.png

  • 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 Handler Collection.
  • Nested handlers are called according to a before/invokeNext/after pattern. The main class for nested handlers is Handler Wrapper. Nested handlers are much more common than those called in sequence.

See also Writing a Jetty Handler.

Servlets

JettyUML5.png

The ServletHandler is a Handler that generates content by passing the request to any configured Filters and then to a Servlet mapped by a URI pattern.

A ServletHandler is normally deployed within the scope of a servlet Context, which is a ContextHandler that provides convenience methods for mapping URIs to servlets.

Filters and Servlets can also use a RequestDispatcher to reroute a request to another context or another servlet in the current context.

Context

Contexts are handlers that group other handlers below a particular URI context path or a virtual host. Typcially a context can have :

  • A context path that defines which requests are handled by the context (eg /myapp )
  • A resource base for static content (a docroot)
  • A class loader to obtain classes specific to the context (typically docroot/WEB-INF/classes)
  • Virtual host names

Contexts implementations include:

A web application context combines handlers for security, session and servlets in a single unit that can be configured with a web.xml descriptor.

Web Applications

JettyUML6.png

A Web App Context is a derivation of the servlet Context that supports the standardized layout of a web application and configuration of session, security, listeners, filter, servlets and JSP via a web.xml descriptor normally found in the WEB-INF directory of a webapplication.

Essentially the WebAppContext 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 WebXmlConfiguration.

Back to the top