Entering Undertow Web server

Francesco MarchioniJanuary 6th, 2014Last Updated: January 7th, 2014

3 799 6 minutes read

With the arrival of Java EE 7 and the requirement to handle advanced features such as the Web Sockets API and HTTP upgrades (e.g. EJB over HTTP), an important decision has been made by the WildFly development team. After a long commitment to JBoss Web Server (a fork of Apache Tomcat), the new release of the application server is now based on a new Web server named Undertow.

Undertow is a flexible, fast, Web server written in Java that is based on the J2SE New Input Output (NIO) API. Undertow is designed around a composition based architecture that allows you to build a fully functional Web server by combining small single components called handlers. These handlers are chained together to form either a fully functional Java EE servlet 3.1 container or a simpler HTTP Process handler embedded in your code.

As you can see from the following picture, an handler chain is composed of several individual handlers which eventually produce either a Servlet response or an error, for example in case that the requested Path is not found:

Undertow Web server also the flexibility to choose between the non-blocking asynchronous handlers to handle tasks, or delegate requests to a blocking handler, backed by a Thread Pool.

We will now have a look at the Web server configuration so just open your configuration file (any standalone configuration file or domain.xml) and move to the “undertow” subsystem which by default looks like this:

<subsystem xmlns="urn:jboss:domain:undertow:1.0">
   <buffer-caches>
      <buffer-cache name="default" buffer-size="1024" buffers-per-region="1024" max-regions="10" />
   </buffer-caches>
   <server name="default-server">
      <http-listener name="default" max-post-size="10485760" socket-binding="http" />
      <host name="default-host" alias="localhost">
         <location name="/" handler="welcome-content" />
      </host>
   </server>
   <servlet-container name="default" default-buffer-cache="default" stack-trace-on-error="local-only">
      <jsp-config />
      <persistent-sessions path="persistent-web-sessions" relative-to="jboss.server.data.dir" />
   </servlet-container>
   <handlers>
      <file name="welcome-content" path="${jboss.home.dir}/welcome-content" directory-listing="true" />
   </handlers>
</subsystem>

One key elements of the Undertow configuration are Buffer Caches. A Buffer is essentially a block of memory into which you can write data, which you can then later read again. This memory block is wrapped in a NIO Buffer object, which provides a set of methods that makes it easier to work with the memory block. The obvious advantage of using a Buffer is that memory access is much faster than physical access.

Besides Java NIO, WildFly makes a large use of XNIO (http://www.jboss.org/xnio) which is a low-level I/O layer which can be used anywhere to simplify the usage of NIO API. It solves out some of the complexities of using Selectors and the lack of NIO support for multicast sockets and non-socket I/O such as serial ports, while still maintaining all the capabilities present in NIO.

In order to manage the Undertow web server, from your Administration console select the Profile tab and move to the Web panel. This contains a set of label such as:

Web services: Used to specify some core Web services settings such as WSDL host and port
Servlets: Used to specify if using Development mode (Default false) which enables reloading JSP on-the-fly
HTTP: Used to configure the Undertow HTTP Connectors. From here, for example, you will associate your Web server with a pool of IO resources
Undertow Core: Used to associate Handlers and Filters to the HTTP Connection.

Configuring the Web server Pool

If you are arriving from a JBoss AS 7 environment, this is a part of your configuration which is going to change. In the earlier release of the application server you used to reference a Thread Executor in order to tune your Web server Thread pool. With WildFly 8, on the other hand, you need to reference a Worker element which needs to be created in the IO subsystem. Let’s see how to do it. Expand the Core option from the left tree menu and select “IO” as shown by this picture:

The “Worker” panel needs to be selected from the main panel. As you can see a “default” worker already exists. You can at any time Create or Remove new ones by clicking on the corresponding buttons. However right now we will click on the “Edit” link so that we customize the number of Threads to be used in our default Worker. Once clicked on the link, we will edit the following attributes:

The first parameter, the Stack size corresponds to the Web server Thread stack size. With a larger Thread stack size, the Web server will consume more resources, and thus fewer users can be supported. The Task keepalive (default 60) controls the number of seconds to wait for the next request from the same client on the same connection. With Keep-Alives the browser gets to eliminate a full round trip for every request after the first, usually cutting full page load times in half.

The number of Io threads corresponds to the number of Web server Threads available. This is an important tuning parameter which needs to be increased for Web applications which experience a high traffic. The Task Max Threads has control on the max number of concurrent requests. Click Save when you are fine with your IO Worker configuration.

Now that we have defined out Worker, we will need to reference it from the from Web server side. In order to do that, from the left tree menu expand the Web subsystem and select the HTTP option. There you will be able to configure some properties which are peculiar of the HTTP server:

Click on the “default” element contained in the table and check that the Worker element is associated with your IO Worker. The worker needs to be enabled as well in order to be usable. Next, we need to associate the HTTP listener with a Socket binding (see from the General Configuration left menu the option Socket Binding to check the available socket bindings for your configuration). Finally, an HTTP server is also bound to a Java NIO Buffer Pool implementation which is discussed in the next section.

Once you have completed your HTTP’s worker configuration, the Web server will use its worker Threads which are named using the following criteria: [worker name]-[worker id]. As you can see from the following picture, the user has defined a worker named “custom” which has been monitored through the Threads section of JConsole utility (included as part of the JDK standard edition):

Configuring the Web server Buffer Pool

As we said, Undertow is based on the Java NIO API and makes use of a pool of J2SE’s

java.nio.ByteBuffer whenever buffering is needed.

A Buffer is an object, which holds some data, that is to be written to or that has just been read from. The addition of the Buffer object in NIO marks one of the most significant differences between the new library and original I/O. In stream-oriented I/O you used to write data directly to, and read data directly from, Stream objects. In the NIO library, all data is handled with Buffers. When data is read, it is read directly into a buffer. When data is written, it is written into a buffer. Anytime you access data in NIO, you are pulling it out of the Buffer.

Undertow IO Buffer Pool configuration can be reached by selecting the Core | IO left menu, and the Buffer Pools option as shown by the following picture:

Click on the “default” Buffer Pool row where you will be able to configure the following elements:

Buffers per slice

This parameter defines how many buffers per slice are assigned. Slices are used for manipulating sub-portions of large buffers, avoiding the overhead of processing the entire buffer.

Direct buffers

This option let you choose if buffers are set as direct buffers or not. The characteristic of direct buffers is that they are allocated outside the Java heap; therefore, once allocated, their memory address is fixed for the lifetime of the buffer. Having a fixed memory address in turn causes that the kernel can safely access them directly and, hence, direct buffers can be used more efficiently in I/O operations

Buffer size

This option let you define the java.nio.ByteBuffer size. Provided that direct buffers are being used, the default 16kb buffers are optimal if maximum performance is required (as this corresponds to the default socket buffer size on Linux).

This excerpt has been taken from the “Wildfly 8 Book” which is a practical, easy to understand guide that discusses the most popular open source Java application server: JBoss Wildfily (renamed from JBoss AS). This book covers all details on administration and management aspect of this new exciting version of the application server. Focusing exclusively on the management instruments of the application server, the book takes you through all of the latest architectural and performance changes. You’ll progress from basic server configuration to more advanced techniques for clustering, JDBC connectivity, logging, and much more.