Entering Undertow Web server

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-cache name="default" buffer-size="1024" buffers-per-region="1024" max-regions="10" />
   <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" />
   <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" />
      <file name="welcome-content" path="${jboss.home.dir}/welcome-content" directory-listing="true" />

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 sliceThis 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 buffersThis 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 sizeThis 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).


http://www.itbuzzpress.com/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.

Related Whitepaper:

Functional Programming in Java: Harnessing the Power of Java 8 Lambda Expressions

Get ready to program in a whole new way!

Functional Programming in Java will help you quickly get on top of the new, essential Java 8 language features and the functional style that will change and improve your code. This short, targeted book will help you make the paradigm shift from the old imperative way to a less error-prone, more elegant, and concise coding style that’s also a breeze to parallelize. You’ll explore the syntax and semantics of lambda expressions, method and constructor references, and functional interfaces. You’ll design and write applications better using the new standards in Java 8 and the JDK.

Get it Now!  

Leave a Reply

five + = 14

Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books