Getting Started With Apache Tomcat

Apache Tomcat is a pure Java open-source web server that implements the Java Servlet, JavaServer Pages, and Expression Language specifications .

According to the JRebel report, Tomcat is one of the most used web servers in the Java world with more than 50% of the market share.

Download

The quickest way to run Tomcat is to download and run a compiled version. Go to http://tomcat.apache.org/ and in the Download section choose the Tomcat version that fits your requirements and package file depending on your OS.

To run Tomcat, you have to first install a Java Runtime Environment (JRE). Make sure to install the right version depending on the Tomcat version you want to run (see table above).

$ wget http://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/8.0.24/tomcat-8.0.24.tar.gz

$ tar -zxvf apache-tomcat-8.0.24.tar.gz

$ cd apache-tomcat-8.0.24

The root directory is known as CATALINA_HOME. Optionally, Tomcat may be configured for multiple instances by defining CATALINA_BASE for each instance. For a single installation, CATALINA_BASE is the same as CATALINA_HOME.

Running

The main script to start Tomcat is ${CATALINA_HOME}/bin/catalina.sh and the most used start-up commands are:

When Tomcat is started in the foreground, it can be stopped by pressing Ctrl+C.

There is a Windows package distribution that installs Tomcat as a Service on Windows operation systems. Most Linux distributions have their own packaging.

Directory Layout

Classloading

In the case of web applications, and according to Servlet specifications, when a classloader is asked to load a class or resource, it will first try in its own classloader, and then in its parent classloader(s).

Embedding

An embedded Tomcat instance can be started within the same JVM of the running application.

Some dependencies must be added to a class path.

Gradle file with dependencies required:

dependencies {

//Minimal dependencies

compile 'org.apache.tomcat.embed:tomcat-embed-core:8.0.9'

compile 'org.apache.tomcat.embed:tomcat-embed-logging-juli:8.0.9'

​

//Optional dependency for JSP

compile 'org.apache.tomcat.embed:tomcat-embed-jasper:8.0.9'

compile 'org.eclipse.jdt.core.compiler:ecj:4.4'

}

Then you can instantiate a new Tomcat instance as any other Java class and call Tomcat operations such as registering Servlet, setting a webapp directory, or configuring resources programmatically.

//creates a Tomcat instance to listen on 8080 port

Tomcat tomcat = new Tomcat();

tomcat.setPort(8080);

​

//adds a new context pointing to current directory as base dir.

Context ctx = tomcat.addContext("/", new File(".").getAbsolutePath());

​

//registers a servlet with name hello

Tomcat.addServlet(ctx, "hello", new HttpServlet() {

protected void service(HttpServletRequest req, HttpServletResponse resp) throws Exception {

Writer w = resp.getWriter();

w.write("Hello World");

w.flush();

}

});

​

//adds a new mapping for the “hello” Servlet matching any URL.

ctx.addServletMapping("/*", "hello");

​

//starts Tomcat instance

tomcat.start();

​

//waits current thread indefinitely

tomcat.getServer().await();

Apache Tomcat’s main configuration is composed of four files: server.xml, context.xml, web.xml, and logging.properties.

server.xml

server.xml is located in ${CATALINA_BASE}/conf and represents the server itself. Here is an example:

<?xml ?>

<Server port="8005" shutdown="SHUTDOWN">

​

<Listener className="xxxxx" />

<GlobalNamingResources>

<Resource name="UserDatabase" auth="Container" type="org.apache.catalina.UserDatabase" description="User database" factory="org.apache.catalina.users.MemoryUserDatabaseFactory"pathname="conf/tomcat-users.xml" />

</GlobalNamingResources>

​

<Service name="Catalina">

<Executor name="tomcatThreadPool" namePrefix="catalina-exec-" maxThreads="150" minSpareThreads="4"/>

​

<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

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

<Realm className="..." />

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

<Valve className="..." />

</Host>

​

</Engine>

</Service>

</Server>

The XML file represents almost a 1:1 layout of the server itself, which conforms with Tomcat’s hierarchical design.

The Tomcat Digester Rules processes the XML files. Each node can get an attribute className to specify which implementation you want to use, as well as a set of attributes which will be set on the created instance.

These are the most important tags to know to use Tomcat:

context.xml

context.xml is a configuration file for a web application. You can also use a Context element under the Host tag in server.xml, but it is recommended (if necessary) that you provide them either in the web application in META-INF/context.xml or (if the configuration is local to the Tomcat instance) in ${CATALINA_BASE}/conf/<engine name>/<hostname>/<warname>.xml.

This last option overrides the META-INF file if both exist. This is convenient for overriding a packaged version, for instance overriding a DataSource.

A shared web application configuration (across all applications) is done in ${CATALINA_BASE}/conf/context.xml (global) and ${CATALINA_BASE}/conf/<engine name>/<hostname>/context.xml.default (specific to a host).

The following are the main children tags of Context:

web.xml

This section does not refer to WEB-INF/web.xml, which is a standard deployment descriptor of the Servlet specification, but about ${CATALINA_BASE}/conf/web.xml.

This is a standard web.xml where mime types, default servlets/filters, default welcome files, and default session timeouts are defined.

This configuration is inherited by all web applications.

Here are the default servlets and some examples of why you might need to update them:

Tomcat uses an enhanced version of the Java Util Logging (JUL) API built into the JVM. As a container, Tomcat needs to support logging configuration at the container level for itself, but it also needs to support application specific configurations.

logging.properties

Tomcat uses a custom LogManager to be able to more finely configure the logging: org.apache.juli.ClassLoaderLogManager

The default configuration is in ${CATALINA_BASE}/conf/logging.properties. Each web application can embed its own configuration by defining a logging.properties file under WEB-INF/classes directory of the webapp.

Configuration Overview

my.logger.name.level = FINEST # a java.util.logging.Level

my.logger.name.handlers = myHandler1,myHandler2,...

my.logger.name.useParentHandlers = true # false by default

Prefixes

You can prefix a logger name with a String starting with a digit and ending with a dot (for instance 1prefix.my.logger.name). This is useful to simultaneously configure the same handler (a file, for instance) with different settings.

Dynamic Values

You can use place holders like ${xxx}. They get replaced automatically at runtime with the value of the Java system property with the key xxx.

Root Logger

Root logger is configured using an empty name:

.handlers = ….

Handler

Tomcat provides several additional handlers like org.apache.juli.FileHandler, which supports log buffering; AsyncFileHandler, which is asynchronous; and some formatters like JdkLoggerFormatter, which uses the log4j equivalent format %r %-15.15c{2} %-1.1p %m %n.

ServletContext Logging

ServletContext.log(...) output is configurable using property org.apache.catalina.core.ContainerBase.[${engine}].[${host}].[${context}].

Replace JUL

You can use log4j for Tomcat itself. To do this, you need to add log4j.jar, tomcat-juli-adapters.jar, log4j.properties in ${CATALINA_HOME}/lib and replace tomcat-juli.jar from bin/ directory with tomcat-juli.jar from extras modules (See Tomcat download page). Don't forget to remove the conf/logging.properties file so that JUL does not create empty files.

Clustering

Tomcat supports clustering (session distribution and deployments) out of the box. To activate it, add a Cluster tag in your Host or Engine.

The cluster tag supports these configurations:

Here is the most basic example:

<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>

NOTE: Don't forget your session attributes need to be Serializable. This is also a requirement if you want the session to survive Tomcat cycles (a.k.a. HTTP session serialization).

Apache Tomcat is supported by major IDE vendors.

Eclipse

To register Tomcat in Eclipse WTP (Web Tools Platform):

- Open Window -> Preferences -> Server -> Installed Runtimes

- Click on Add and in New Server Runtime, select Apache -> Apache Tomcat v8.0

- Click Next and fill in your Tomcat installation directory

IntelliJ IDEA

To register Tomcat in IntelliJ IDEA Ultimate Edition (community edition is not supported)

- Open File -> Settings -> (IDE Settings) Application Servers

- Click on + symbol and select Tomcat Server

- In the dialog box fill Tomcat Home with your Tomcat installation directory

Netbeans

Netbeans Java EE comes with Apache Tomcat already installed, but you can use register Tomcat as well.

- Open Windows -> Services

- Right-Click on Servers -> Add Server

- In the dialog box choose Apache Tomcat

- Click Next -> fill Server Location with your Tomcat installation directory

Following today's needs Tomcat proposes several I/O solutions.

Connectors

As explained in the Configuration section, Tomcat handles I/O thanks to connectors. Most of them share a common configuration, the full details of which are available at http://tomcat.apache.org/tomcat-8.0-doc/config/http.html.

NIO/NIO2

The NIO and NIO2 connectors allow you to use Java NIO to handle incoming requests. With the release of Tomcat 8, they are now the default connectors to handle HTTP requests.

Note that to use NIO2 you need to specify the class org.apache.coyote.http11.Http11Nio2Protocol on your Connector tag in the class-name attribute. Keep in mind it is still a “beta” connector, but it can bring your application some significant speed enhancements.

BIO

The BIO connector allows you to use the old blocking I/O. It was the default connector to handle HTTP requests for prior Tomcat 8 versions.

The main difference between NIO and BIO is that with the BIO connector you generally need more threads to handle requests concurrently, and they don’t guarantee better performances. These connectors impose you to get one thread by connection!

For Tomcat 9+ versions, the BIO connector has been completely removed.

AJP

AJP is a protocol like HTTP. Its main goal is to get higher performances. It is a binary version of HTTP, and also a connected protocol as opposed to HTTP. It can be used with httpd (a.k.a Apache Web Server) and most of the time with mod_jk or mod_proxy_ajp httpd modules. If you are using SSL or have a lot of static resources, this is the fastest connector!

CometD

CometD is the old way to handle asynchronous I/O (i.e. let the container call you when data are available). This only works with APR or NIO connectors.

To use CometD, you first need to implement it within a servlet org.apache.catalina.comet.CometProcessor (eliminating portability) and then handle events in event(CometEvent):

public class MyCometDServlet extends HttpServlet implements CometProcessor {

@Override

public void event(final CometEvent event) throws IOException, ServletException {

​

final HttpServletRequest request = event.getHttpServletRequest();

final HttpServletResponse response = event.getHttpServletResponse();

​

if (event.getEventType() == CometEvent.EventType.BEGIN) { //keep the response to bulk send data to everybody

} else

​

if (event.getEventType() == CometEvent.EventType.ERROR || event.getEventType() == CometEvent.EventType.END) {

// state cleanup if needed

         event.close();

         // we are done

} else

​

if (event.getEventType() == CometEvent.EventType.READ) {

final InputStream is = request.getInputStream();

do {

// read is

} while (is.available() > 0);

}

}

}

WebSocket

WebSockets (RFC 6455) have been supported by Tomcat since version 7, but only versions 7.0.43 and later implement the specification (a.k.a JSR-356). Before ( version 7.0.27 and earlier) Tomcat was using a proprietary API and implementation didn't scale as much as today -- so ensure you are using an up-to-date version.

The Tomcat WebSocket implementation needs at least Java 7. If you are running on Java 7, it is activated by default and you just need to deploy your code inside Tomcat:

@ServerEndpoint("/tchat")

public class TchatEndpoint {

​

@OnMessage

public void onMessage(Session session, String msg) {

try {

session.getBasicRemote().sendText(msg);

} catch (IOException e) { ... }

}

}

WebSocket doesn't require you to use an APR or NIO connector like CometD does, but it is highly recommended, as you will likely have a high number of connections.

JNDI

Tomcat provides a JNDI InitialContext implementation instance for each web application. As mentioned in the Configuration section, JNDI resources can be registered in conf/server.xml, conf/web.xml, or any context.xml file. But Tomcat also follows the Java EE standard for /WEB-INF/web.xml file to reference/define resources.

In order to use a JNDI resource, specify the JNDI name defined in the web application's deployment descriptor:

context.xml

<context ...>

<!-- Definition of DataSource in context.xml -->

<Resource name="jdbc/employeeDB" type="javax.sql.DataSource" global="jdbc/employeeDB" .../>

</context>

​

web.xml

<web-app>

<!-- Declaring a reference to DataSource in web.xml -->

<resource-ref>

<description>Employee Datasource</description>

<res-ref-name>jdbc/employeeDB</res-ref-name>

<res-type>javax.sql.DataSource</res-type>

<res-auth>Container</res-auth>

</resource-ref>

<env-entry>

<env-entry-name>message</env-entry-name>

<env-entry-value>Hello World</env-entry-value>

<env-entry-type>java.lang.String</env-entry-type>

</env-entry>

</webapp>

Java Code

Context initCtx = new InitialContext();

DataSource ds = (DataSource) initCtx.lookup("java:comp/env/jdbc/EmployeeDB");

String message = (String)initCtx.lookup("java:comp/env/message");

A Listener element defines a component that performs actions when specific events occur, usually Tomcat starting or Tomcat stopping.

Listeners are registered inside conf/server.xml inside Server, Engine, Host, and Context tags.

Each Listener must implement org.apache.catalina.LifecycleListener interface.

Custom Listener

public class PrintLifecycleStatesListener implements LifecycleListener {

@Override

public void lifecycleEvent(LifecycleEvent e) {

System.out.println(e.getLifecycle().getStateName());

}

}

The JAR file containing this class is stored at $CATALINA_BASE/lib directory.

And add the next line at conf/server.xml.

<Server ...>

<Listener className="org.superbiz.PrintLifecycleStatesListener"/>

</Server>

Shipped Listeners

After installing and configuring Tomcat, you will need to deploy web applications.

Drop-In WAR

Deploying an application to Tomcat can be as simple as dropping a WAR file inside the $CATALINA_BASE/webapps directory; this will deploy the application.

Hot Deployment

To deploy a new application, you must restart the server in order for the application to function. To fix this problem, Tomcat provides a hot deployment option, which deploys an application without the need to restart.

To enable hot deployment, the autoDeploy attribute from host tag in server.xml must be set to true. See the configuration section for an example.

Tomcat Manager

Web Application

Tomcat also comes with a manager that allows for deploying an application from the web console. To use the manager, you need to add a username and password to conf/tomcat-users.xml with role manager-gui.

<tomcat-users>

<role rolename="manager-gui"/>

<user username="tomcat" password="s3cret" roles="manager-gui"/>

</tomcat-users>

Next, access http://<host>:<port>/manager to access the web console.

URI

The Tomcat Manager also provides URI commands to upload applications. They follow this schema:

http://{host}:{port}/manager/text/{command}?{parameters}

Some examples of deploying an application using URI commands:

http://{host}:{port}/manager/text/deploy?path=/foo

The above uploads to the remote server, the war with path /foo. The war is provided as the body of the HTTP PUT.

http://{host}:{port}/manager/text/deploy?path=/foo&:/path/to/foo.war

This deploys application stored in the server directory path/to/foo.war.

Arquillian

Arquillian is an integration and functional testing platform that can be used for Java middleware testing. The main goal of Arquillian is to make tests that require a server to be as simple as writing unit tests.

You can use Arquillian Tomcat adapters to write integration/functional tests.

Arquillian Tomcat 8 adapter release is coming soon.

Maven coordinates can be found at:

http://arquillian.org/modules/arquillian-tomcat-embedded-7-container-adapter/

http://arquillian.org/modules/arquillian-tomcat-managed-7-container-adapter/

http://arquillian.org/modules/arquillian-tomcat-remote-7-container-adapter/

http://arquillian.org/modules/arquillian-tomcat-embedded-8-container-adapter/

When using the embedded adapter, Tomcat embedded dependencies are required as well.

When using the remote adapter, the Tomcat instance has to expose a remote JMX MbeanConnection.

JAVA_OPTS=”$JAVA_OPTS -Dcom.sun.management.jmxremote.port=8089 “

JAVA_OPTS=”$JAVA_OPTS -Dcom.sun.management.jmxremote.ssl=false “

JAVA_OPTS=”$JAVA_OPTS -Dcom.sun.management.jmxremote.authenticate=false”

Maven

Maven is still one of the most used build tools and therefore Tomcat integration is available.

This integration is mainly (in addition to deploying artifacts on central) a Maven plugin.

Today, there are two plugins, tomcat-maven-plugin for Tomcat 6 and tomcat7-maven-plugin for Tomcat 7; tomcat8-maven-plugin is coming soon.

Their usage is more or less the same:

<plugin>

<groupId>org.apache.tomcat.maven</groupId>

<artifactId>tomcat7-maven-plugin</artifactId>

<version>2.2</version>

<configuration>

<url>http://localhost:8080/manager</url>

</configuration>

</plugin>

Here are the main configurations of the Maven plugin:

Once these configurations are set up,  the available goals are as follows:

Note: Often goals will exist with the "-only" suffix. For example, the deploy-only goal will not fork a Maven package lifecycle.

Each goal has further configurations, for example the “context” path within the “deploy” application goal.

You can find more details at: http://tomcat.apache.org/maven-plugin-trunk/tomcat7-maven-plugin/plugin-info.html.

Java EE and Beyond

Tomcat is a Servlet container that implements the Servlet/JSP/EL specifications. If you are required to use any other Java EE specification like CDI, JPA, EJB, JAX-RS, or Bean Validation, you can integrate it by yourself (assuming you understand the perils of doing it yourself), or you can use Apache TomEE. TomEE (pronounced "Tommy") is the Java Enterprise Edition of Apache Tomcat (Tomcat + Java EE = TomEE) and is Java EE 6 Web Profile certified. It maintains the light weight and simplicity of Tomcat but with the full power of Java EE.

References

Apache Tomcat site:http://tomcat.apache.org

Tomcat server.xml: http://tomcat.apache.org/tomcat-8.0-doc/config/server.html

Tomcat Logging:http://tomcat.apache.org/tomcat-8.0-doc/logging.html

Tomcat Clustering:http://tomcat.apache.org/tomcat-8.0-doc/cluster-howto.html

Tomcat Listeners:http://tomcat.apache.org/tomcat-8.0-doc/config/listeners.html

Tomcat WebSocket:http://tomcat.apache.org/tomcat-8.0-doc/web-socket-howto.html

Tomcat Maven Plugin:http://tomcat.apache.org/maven-plugin.html

Arquillian and Tomcat:https://docs.jboss.org/author/display/ARQ/Tomcat+7.0+-+Embedded