In this section, we’ll take a look at the key request processing components within
Tomcat; the engine, virtual host, and context components.
An Engine represents a running instance of the Catalina servlet engine and
comprises the heart of a servlet container’s function. There can only be one engine
within a given service. Being a true container, an Engine may contain one or more
virtual hosts as children.
Being the primary request processing component, it receives objects that represent
the incoming request and the outgoing response. Its main function is to delegate
the processing of the incoming request to the appropriate virtual host. If the engine
has no virtual host with a name matching the one to which the request should be
directed, it consults its defaultHost attribute to determine the host that should
A virtual host in Tomcat is represented by the Host component, which is a container
for web applications, or, in Tomcat parlance, contexts.
Two key concepts come into play when working with virtual hosts—the host’s
domain name and its application base folder.
- Domain name: Each virtual host is identified by the domain name that you
registered for use with this host. This is the value that you expect the client
browser to send in the Host: request header. A host’s name is required to be
unique within its containing engine.
- Application base folder: This fo lder is the location that contains the contexts
that will be deployed to this host. This folder location can either be specified
as an absolute path or as a path relative to CATALINA_BASE.
CATALINA_HOME is an environment variable that references the location
of the Tomcat binaries. The CATALINA_BASE environment variable
makes it possible to use a single binary installation of Tomcat to run
multiple Tomcat instances with different configurations (which are
primarily determined by the contents of the conf folder).
In addition, the use of a CATALINA_BASE location that is separate
from CATALINA_HOME keeps the standard binary distribution separate
from your installation. This has the beneficial effect of making it easy
to upgrade to a newer Tomcat version, without having to worry about
clobbering your existing web applications and related configuration files.
This component is covered in more detail in Chapter 7,
The Engine Component.
When it comes to mapping host names to Internet Protocol addresses, the
simplest scenario is one in which a given Fully Qualified Host Name (FQHN),
such as www.swengsol.com, is associated with the IP address that maps to a
particular physical host.
The downside with this approach is that connecting a host to the Internet is
fairly expensive. This is especially true when you consider the costs related to
bandwidth, infrastructure (such as database/mail servers, firewalls, uninterruptible
power supplies, fault tolerance, and so on), and maintenance (including staffing,
administration, and backups), not to mention having to obtain an IP address in
the first place.
As a result, many small businesses find it preferable to lease space and
infrastructure from hosting service providers. The hosting service may have a
single physical server that is connected to the Internet and is identified with a
specific IP address. This physical server could host several domains on behalf
of the provider’s customers.
For example, consider the case where Acme Widgets Inc. and Vertico LLC have
their domains, www.acme-widgets.com and www.vertico.com, hosted on a single
physical machine at a hosting service. The applications that are deployed to both
these domains must be able to function without any interference from the other.
In this case, both these domains are termed ‘virtual’ hosts, in the sense that they
appear to be represented by separate physical hosts. However, in reality, they
exist simply as a logical partitioning of the address space on a single physical host.
Virtual host techniques
There are two common ways to set up virtual hosting:
- IP-based virtual hosting
- Name-based virtual hosting
IP-based virtual hosting
With this technique, each FQHN resolves to a separate IP address. However, each of
these IP addresses resolves to the same physical machine.
You can achieve this by using either of the following mechanisms:
- A multi-homed server, that is, a machine that has multiple physical Network
Interface Cards (NICs) installed, each of which has an assigned IP address.
- Using operating system facilities to set up virtual network interfaces by
dynamically assigning multiple IP addresses to a single physical NIC.
In either case, the downside is that we need to acquire multiple IP addresses, and
these addresses (at least for IPv4) are a limited resource.
The web server is configured to listen on ports that are assigned to each of these IP
addresses, and when it detects an incoming request on a particular IP address, it
generates the response appropriate for that address.
For example, you can have a web server that is running on a particular physical host
that is monitoring port 80 on both 220.127.116.115 and 18.104.22.1686. It is configured
to respond to requests that are coming in on the former IP address with content
that is associated with a particular host name, say www.host1.com, whereas it is
www.host2.com for the latter.
When a request comes in on 22.214.171.1246, the server knows that it should serve
content from the www.host2.com, and does so. To the user, this is indistinguishable
from an entirely separate physical server.
Name-based virtual hosting
This is a newer technique that lets you map different domain names to the same IP
address. The domain names are registered as normal, and multiple DNS entries exist
to map these domain names to the same IP address.
The HTTP/1.1 protocol requires that every request must contain a Host: header
that carries the fully qualified host name, as well as the port number (if specified)
to which the user wishes to connect. The web server that runs on the host at the IP
address will receive this request and will read this header to determine the specific
virtual host that should handle this request.
Name-based virtual hosting is preferred for its simplicity and for the fact that it does
not use up IP addresses needlessly.
However, you may have to use IP-based virtual hosting when you are using virtual
hosts together with SSL. The reason is that the negotiation protocol commits to a
certificate before it pays heed to the specific virtual host for which the request is
being made. This is because the SSL protocol layer works at a lower level than the
HTTP protocol, and the module negotiating this handshake with the client cannot
read the HTTP request header until the handshake is complete.
You may be able to use name-based virtual hosting with SSL if
your web server and client supports the Server Name Indication
extension as specified in RFC 3546—Transport Layer Security
Using this extension, during the SSL negotiation, the client also
transmits the host name to which it is trying to connect, thereby
allowing the web server to handle the handshake appropriately
by returning the certificate for the correct host name.
Virtual host aliasing
Aliasing works by informing the web server that if it sees the aliased domain name
in the Host: header, it should be treated in exactly the same manner as the virtual
host’s domain name.
For example, if you set up swengsol.com as an alias for the www.swengsol.com
virtual host, then typing either domain name in the URL will result in the same
virtual host being used to process the request.
This works well when a particular host may be known by more than one domain
name, and you don’t want to clutter your configuration file by creating one set of
entries per alias that a user may use to connect to that host.
This component is covered in more detail in Chapter 8,
The Host Component.
A Context, or web application, is where your application specific code (servlets
and JSPs) live. It provides a neat way to organize the resources that comprise a
given web application.
A context maps to a ServletContext instance within the servlet specification.
In many ways, the servlet specification is primarily concerned with this context
component. For instance, it mandates the format for deploying a context, and
dictates the contents of the deployment descriptor.
Important attributes for a context include:
- Document base: This is the path name, either absolute or relative to its
containing host’s application base, to where its WAR file or exploded folder
(its content root) are located.
- Context path: It represents the portion of the URL that uniquely identifies a
web application within a given host. It helps the host container to determine
which of its deployed contexts should be responsible for handling an
One of your contexts may be identified as the default context. This context is
then the application that will be invoked when no context path is specified
on the URL. This default context is identified by specifying an empty string
as its context path, and as such, can be referenced by using a URL that only
specifies a hostname. The default application is identified in Tomcat by a
folder named ROOT in the application base folder for a given host.
- Automatic reload: A c ontext’s resources can be monitored for changes, and
the context reloaded automatically when any changes are detected. While
this is remarkably useful during development, this is an expensive operation
and should be turned off in production.
A Context is unique because it has multiple options when it comes to its configuration.
We have already noted the presence of the conf/server.xml file that is used to set up
the overall structure of the Tomcat instance. While this file’s <Context> element can be
used to configure a context, this is no longer recommended.
Instead, Tomcat lets you configure a Context by letting you extract the <Context>
element from the server.xml file and move it into a separate file called a context
fragment file. C ontext fragments are monitored and reloaded by Tomcat at runtime.
Note that the server.xml file is only ever loaded once at startup.
To ensure a clear separation of contexts by host and engine, Tomcat expects to
find context fragments using a specific directory path CATALINA_HOME/conf/
<EngineName>/<HostName>/. The context fragments for contexts deployed into
this host are found within this folder and are named <ContextPath>.xml.
For the default case, that is, an engine named Catalina and a host named
localhost, this works out to be the folder CATALINA_HOME/conf/Catalina/
localhost. However, the name of the host could be any valid domain name, for
example, www.swengsol.com, resulting in a folder named CATALINA_HOME/conf/
In addition, context fragments may also be found embedded within the
META-INF folder of a web application’s WAR file or exploded directory.
In such cases, the fragment must be named context.xml.
Contexts can also be configured using the web application deployment descriptor,
web.xml. While the fragment file is proprietary to Tomcat, the deployment descriptor
is described by the servlet specification, and therefore is portable across Java EE
compliant servlet containers.
We will consider both of these in much greater detail in later chapters.
This component is covered in more detail in Chapter 9,
The Context Component.
A Wrapper object is a child of the context container and represents an individual
servlet (or a JSP file converted to a servlet). It is called a Wrapper because it wraps
an instance of a javax.servlet.Servlet.
This is the lowest level of the Container hierarchy, and any attempt to add a child to
it will result in an exception being thrown.
A wrapper is responsible for the servlet that it represents, including loading it,
instantiating it, and invoking its lifecycle methods such as init(), service(),
It is also responsible, through its basic valve, for the invocation of the filters that are
associated with the wrapped servlet.
This component is covered in more detail in Chapter 10,
The Wrapper Component.