Java Tech Programming: Apache Tomcat Architecture And Configuration Files Tutorial PART 1

This article is meant for advanced programmers who is interested to know more about Tomcat; or using Tomcat for production.

The authoritative source of information on Tomcat is the Tomcat's documentation, available under Tomcat's "webapps\docs" directory. You may also refer to the Java Servlet, JSP and JSF specifications, as Tomcat is the Reference Implementation for these technologies.

I shall assume that Tomcat is installed in d:\myproject\tomcat, and shall denote this directory as $CATALINA_HOME (Unix-style) or %CATALINA_HOME% (Windows-style). Catalina is the codename for Tomcat 5 and above.

Tomcat's Architecture and the main configuration file "server.xml"

Tomcat is an HTTP server. Tomcat is also a container that can execute Java Servlet, and converting JavaServer Pages (JSP) and JavaServerFaces (JSF) to Java Servlet. Tomcat employs a hierarchical and modular architecture as illustrated:

Tomcat Architecture,Tomcat Configuration files tutorial,Tomcat configuration files explanation

Tomcat's main configuration file is the "server.xml", kept under the $CATALINA_HOME\conf directory. The default "server.xml" is reproduced as follows (after removing the comments and some minor touch ups):

<?xml version='1.0' encoding='utf-8'?>

<Resource name="UserDatabase" auth="Container"

type="org.apache.catalina.UserDatabase"

description="User database that can be updated and saved"

factory="org.apache.catalina.users.MemoryUserDatabaseFactory"

pathname="conf/tomcat-users.xml" />

</GlobalNamingResources>

<Connector port="8080" protocol="HTTP/1.1"

connectionTimeout="20000"

redirectPort="8443" />

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"

resourceName="UserDatabase"/>

</Realm>

<Host name="localhost" appBase="webapps"

unpackWARs="true" autoDeploy="true">

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"

prefix="localhost_access_log." suffix=".txt"

pattern="%h %l %u %t "%r" %s %b" />

</Host>

</Engine>

</Service>

</Server>

You can define other global resource JNDI such as MySQL database to implement connection pooling.

Services

A Service associates one or more Connectors to a Engine. The default configuration defines a Service called "Catalina", and associates two Connectors: HTTP and AJP to the Engine.

<Service name="Catalina"> ...... </Service>

Connectors

A Connector is associated with a TCP port to handle communications between the Service and the clients. The default configuration defines two Connectors:

HTTP/1.1: Handle HTTP communication and enable Tomcat to be an HTTP server. Clients can issue HTTP requests to the server via this Connector, and receive the HTTP response messages.
```
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />
```
The default chooses TCP port 8080 to run the Tomcat HTTP server, which is different from the default port number of 80 for HTTP production server. You can choose any number between 1024 to 65535, which is not used by any application, to run your Tomcat server.
The connectionTimeout attribute define the number of milliseconds this connector will wait, after accepting a connection, for the request URI line (request message) to be presented. The default is 20 seconds.
The redirect attribute re-directs the SSL requests to TCP port 8443.
AJP/1.3: Apache JServ Protocol connector to handle communication between Tomcat server and Apache HTTP server.
```
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
```
You could run Tomcat and Apache HTTP servers together, and let the Apache HTTP server handles static requests and PHP; while Tomcat server handles the Java Servlet/JSP.

Containers

Tomcat refers to Engine, Host, Context, and Cluster, as container. The highest-level is Engine; while the lowest-level is Context. Certain components, such as Realm and Valve, can be placed in a container.

Engine

A Engine is the highest-level of a container. It can contains one or more Hosts. You could configure a Tomcat server to run on several hostnames, known as virtual host.

<Engine name="Catalina" defaultHost="localhost">

The Catalina Engine receives HTTP requests from the HTTP connector, and direct them to the correct host based on the hostname/IP address in the request header.

Realm

A Realm is a database of user, password, and role for authentication (i.e., access control). You can define Realm for any container, such as Engine, Host, and Context, and Cluster.

<Realm className="org.apache.catalina.realm.LockOutRealm">
  <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>
</Realm>

The default configuration defines a Realm (UserDatabaseRealm) for the Catalina Engine, to perform user authentication for accessing this engine. It uses the JNDI name UserDatabase defined in theGlobalNamingResources.

Besides the UserDatabaseRealm, there are: JDBCRealm (for authenticating users to connect to a relational database via the JDBC driver); DataSourceRealm (to connect to a DataSource via JNDI;JNDIRealm (to connect to an LDAP directory); and MemoryRealm (to load an XML file in memory).

Hosts

A Host defines a virtual host under the Engine, which can in turn support many Contexts (webapps).

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">

The default configuration define one host called localhost. The appBase attribute defines the base directory of all the webapps, in this case, $CATALINA_HOME\webapps. By default, each webapp's URL is the same as its directory name. For example, the default Tomcat installation provides four webapps: docs, examples, host-manager and manager under the webapps directory. The only exception is ROOT, which is identified by an empty string. That is, its URL is http://localhost:8080/.

The unpackWARs specifies whether WAR-file dropped into the webapps directory shall be unzipped. For unpackWARs="false", Tomcat will run the application from the WAR-file directly, without unpacking, which could mean slower execution.

The autoDeploy attribute specifies whether to deploy application dropped into the webapps directory automatically.

Cluster

Tomcat supports server clustering. It can replicate sessions and context attributes across the clustered server. It can also deploy a WAR-file on all the cluster.

Valve

A Valve can intercept HTTP requests before forwarding them to the applications, for pre-processing the requests. A Valve can be defined for any container, such as Engine, Host, and Context, andCluster.

In the default configuration, the AccessLogValve intercepts an HTTP request and creates a log entry in the log file, as follows:

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
       prefix="localhost_access_log." suffix=".txt"
       pattern="%h %l %u %t &quot;%r&quot; %s %b" />

Other valves include:

RemoteAddrValve: which blocks requests from certain IP addresses,
RemoteHostValve: which blocks request based on hostnames,
RequestDumperValve: which logs details of the requests,
SingleSignOn Valve: when placed under a <host>, allows single sign-on to access all the webapp under the host.

Context (Application or Webapp)

A web context is a single web application (webapp). It is the lowest-level container, that you can define components such as Realm and Valve. By default, all webapps are kept under the$CATALINA_HOME\webapps directory (as configured in the <host> element appBase attribute.

A Java webapp may contain many types of files, such as HTML, CSS, Scripts, images, JSP, servlet, utility classes, external library jar-files. A Java webapp must follow a strict directory structure as depicted in the Servlet/JSP specifications. This enables deployment in a Java-capable web server (such as Apache Tomcat and Glassfish). The resources must be kept in the correct directories and sub-directories.

The URL of a webapp, by default, is the same as the base directory name (or context root) of the webapp.