Undertow Concepts: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
 
(63 intermediate revisions by the same user not shown)
Line 3: Line 3:
* [[Undertow#Subjects|Undertow]]
* [[Undertow#Subjects|Undertow]]
* [[XNIO Concepts]]
* [[XNIO Concepts]]
* [[Undertow WildFly Subsystem Concepts]]
=TODO=
<font color=red>
* Continue the official documentation starting here: http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#undertow-handler-authors-guide
* Parse it to the end
</font>
=Diagram=
[[Image:UndertowArchitecture.png|thumb|center]]


=Overview=
=Overview=
Line 21: Line 33:


=Artifacts=
=Artifacts=
* <tt>undertow-core</tt>
* <tt>undertow-servlet</tt> provides support for Servlet 3.1
* <tt>undertow-websockets-jsr</tt> provides support for the Java API for Websockets ([[JSR-356]])
=Container=
There in no Undertow ''container''. Undertow applications are assembled from Undertow handler classes and it is up to the embedding application to manage the lifecycle of all Undertow handlers.
=Bootstrap=
<font color=red>TODO
* http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#bootstrapping-undertow
* http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#the-builder-api
* http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#assembling-a-server-manually
</font>
=Architecture=
An Undertow server consists of one or more [[XNIO Concepts#XNIO_Worker|XNIO worker]] instances, one or more [[#Connector|connectors]] and a [[#Handler_Chain|handler chain]].
=XNIO Concepts=
* [[XNIO Concepts#XNIO_Worker|Worker]]
=Connector=
A connector (also known as a listener) is the Undertow part that handles incoming connections and the underlying wire protocol. The connector is tied to a [[XNIO Concepts#XNIO_Worker|XNIO Worker]]. By default, Undertow ships with 3 listeners: HTTP, HTTPS and AJP. <font color=purple>If multiple connectors are set to invoke into the same handler chain, the may share a Worker, or they may have separate workers. Usually there will only be a single worker instance that is shared between listeners, however it is possible to create a new worker for each listener.</font>
A connector (listener) is associated with a network interface and a port.
A connector comprises two [[XNIO Concepts#ChannelListener|XNIO Listeners]]: an open listener and a read listener:
==Open Listener==
The open listener is invoked when a connection is first received, and it will do any work necessary to set up the connection. Then, it will pass the connection to the [[#Read_Listener|read listener]].
==Read Listener==
The read listener is responsible for parsing the incoming request into a <tt>[[#HttpServerExchange|HttpServerExchange]]</tt> instance, setting protocol specific state and passing it to the first handler in the [[#Handler_Chain|handler chain]].
If persistent connections are used, the same read listener is used for subsequent requests came on the same connections.
==Listener Configuration==
For details on how to configure listeners see [[Undertow Configuration#Listener_Configuration|Undertow Configuration]].
=Handler=
The Undertow functionality is provided by assembling together <tt>io.undertow.server.HttpHandler</tt> instances, which form a [[#Handler_Chain|handler chain]].
==Handler Instance Lifecycle==
<font color=red>
The current assumption is that the handlers are singletons per host. Verify that.
</font>
==Handler Chain==
Handlers are generally chained together by specifying the next handler at construction time. There is no pipeline concept. This means a handler can pick the next handler to invoke into at runtime based on the current request.
==Built-in Handlers==
<font color=red>TODO http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#built-in-handlers
* Path
* Virtual Host
* Date
* Resource
* Predicate
* HTTP Continue
* Websocket
* Redirect
* Trace
* Header
* IP Access Control
* ACL
* URL Decoding
* Set Attribute
* Rewrite
* Graceful Shutdown
* Proxy Peer Address
* Request Limiting Handler
</font>
==Custom Handlers==
<font color=red>
TODO http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#undertow-handler-authors-guide
</font>
=Buffer Pool=
<font color=red>TODO: http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#buffer-pool</font>
Also see [[Java_Non-Blocking_I/O_Concepts#ByteBuffer|NIO ByteBuffer]].


=Request Lifecycle=
=Request Lifecycle=
<font color=red>TODO


* http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#request-lifecycle
* http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#request-lifecycle
* http://undertow.io/undertow-docs/undertow-docs-1.3.0/undertow-request-lifecycle.html
* http://undertow.io/undertow-docs/undertow-docs-1.3.0/undertow-request-lifecycle.html


=XNIO Concepts=
</font>


* [[XNIO Concepts#XNIO_Worker|Worker]]
==HttpServerConnection==
* [[XNIO Concepts#XNIO_Listener|Listener]]
 
=HttpServerExchange=


==HttpServerExchange==


<font color=red>
<font color=red>
Line 39: Line 151:
</font>
</font>


=Handler=
=Threading Model=
 
{{Internal|Undertow WildFly Subsystem Concepts#Threading_Model|Undertow WildFly Subsystem Threading Model}}

Latest revision as of 22:50, 25 July 2018

Internal

TODO

Diagram

UndertowArchitecture.png

Overview

Undertow is a web server written in Java. It provides both blocking and non-blocking APIs based on NIO. It has a composition-based architecture that allows assembling a web server combining small single purpose handlers.

Undertow is embeddable, its lifecycle is controlled by the embedding application and its configuration is controlled programmatically via API calls. Undertow is the default web server in WildFly since version 8, and in this case the configuration is exposed via XML in the server configuration file as:

        ...
        <subsystem xmlns="urn:jboss:domain:undertow:3.0">
            ...
        </subsystem>
        ...

It has support for Servlet 3.1.

Artifacts

  • undertow-core
  • undertow-servlet provides support for Servlet 3.1
  • undertow-websockets-jsr provides support for the Java API for Websockets (JSR-356)

Container

There in no Undertow container. Undertow applications are assembled from Undertow handler classes and it is up to the embedding application to manage the lifecycle of all Undertow handlers.

Bootstrap

TODO

Architecture

An Undertow server consists of one or more XNIO worker instances, one or more connectors and a handler chain.

XNIO Concepts

Connector

A connector (also known as a listener) is the Undertow part that handles incoming connections and the underlying wire protocol. The connector is tied to a XNIO Worker. By default, Undertow ships with 3 listeners: HTTP, HTTPS and AJP. If multiple connectors are set to invoke into the same handler chain, the may share a Worker, or they may have separate workers. Usually there will only be a single worker instance that is shared between listeners, however it is possible to create a new worker for each listener.

A connector (listener) is associated with a network interface and a port.

A connector comprises two XNIO Listeners: an open listener and a read listener:

Open Listener

The open listener is invoked when a connection is first received, and it will do any work necessary to set up the connection. Then, it will pass the connection to the read listener.

Read Listener

The read listener is responsible for parsing the incoming request into a HttpServerExchange instance, setting protocol specific state and passing it to the first handler in the handler chain.

If persistent connections are used, the same read listener is used for subsequent requests came on the same connections.

Listener Configuration

For details on how to configure listeners see Undertow Configuration.

Handler

The Undertow functionality is provided by assembling together io.undertow.server.HttpHandler instances, which form a handler chain.

Handler Instance Lifecycle

The current assumption is that the handlers are singletons per host. Verify that.

Handler Chain

Handlers are generally chained together by specifying the next handler at construction time. There is no pipeline concept. This means a handler can pick the next handler to invoke into at runtime based on the current request.

Built-in Handlers

TODO http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#built-in-handlers

  • Path
  • Virtual Host
  • Date
  • Resource
  • Predicate
  • HTTP Continue
  • Websocket
  • Redirect
  • Trace
  • Header
  • IP Access Control
  • ACL
  • URL Decoding
  • Set Attribute
  • Rewrite
  • Graceful Shutdown
  • Proxy Peer Address
  • Request Limiting Handler

Custom Handlers

TODO http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#undertow-handler-authors-guide

Buffer Pool

TODO: http://undertow.io/undertow-docs/undertow-docs-1.3.0/index.html#buffer-pool

Also see NIO ByteBuffer.

Request Lifecycle

TODO

HttpServerConnection

HttpServerExchange

An exchange can be in blocking or non-blocking mode, and it can be put in blocking mode.

Threading Model

Undertow WildFly Subsystem Threading Model