Meet Tomcat Catalina

Apache Tomcat is a widely used implementation of the Java Servlet Specification, which has been developed as an open-source project by the Apache Software Foundation since 1999, when the project source was donated to the ASF by Sun Microsystems.  

Tomcat is actually composed of a number of components, including a Tomcat JSP engine and a variety of different connectors, but its core component is called Catalina.  Catalina provides Tomcat's actual implementation of the servlet specification; when you start up your Tomcat server, you're actually starting Catalina.

In this article, we'll get to know Tomcat's core component, from the origins of the name "Catalina", to an overview of how Catalina is configured.  We'll also look at some Catalina-related tips and tricks, such as how to get the most out of Catalina's built-in logging functionality, and how to manage the Catalina class as an MBean using JMX.

How Did Catalina Get Its Name?

There's nothing like an Apache product name to raise an eyebrow - the Apache volunteers have a knack for turning out oddly named technologies that's only rivaled by Ubuntu's "adjective-animal" naming format.

The name "Catalina," according to Craig McClanahan, who designed the original architecture of the servlet container, can be attributed to three things: his love for Catalina Island (despite never having visited it), his cat's habit of hanging around the computer while he was writing the code, and the consideration, at an early stage of development, of building Tomcat on a server framework called Avalon, which is the name of a town on Catalina island.  

The Avalon framework was eventually abandoned, but the name stuck, and the rest is history.

Catalina's Configuration Files

Catalina's default behavior can be directly configured by editing the six configuration files located in Tomcat's "$CATALINA_BASE/conf" directory.  Here's an overview of the files located in this directory and the kinds of options that can be configured within each.

catalina.policy

catalina.properties

logging.properties

content.xml

server.xml

tomcat-users.xml

web.xml

If you need more information about configuring Catalina, check out our Tomcat Configuration page!

Rotating Catalina.out

A common question asked by Tomcat beginners is how to rotate the Catalina.out log file, without restarting Tomcat.  (If you're not familiar with the file, Catalina.out is the standard destination log file for System.out and System.err, JVM loggers that print information about fatal errors in the JVM.)  

There are two answers.  

The first, which is more direct, is that you can rotate Catalina.out by adding a simple pipe to the log rotation tool of your choice in Catalina's startup shell script.  This will look something like:

"$CATALINA_BASE"/logs/catalina.out WeaponOfChoice 2>&1 &

Simply replace "WeaponOfChoice" with your favorite log rotation tool.

The second answer is less direct, but ultimately better.  The best way to handle the rotation of Catalina.out is to make sure it never needs to rotate.  Simply set the "swallowOutput" property to true for all Contexts in "server.xml".  

This will route System.err and System.out to whatever Logging implementation you have configured, or JULI, if you haven't configured it.  All commons-logger implementations rotate logs by default, so rotating Catalina.out is no longer your problem.

For more information about JULI, Log4J, and Tomcat logging in general, check out our easy-to-follow guide to Tomcat Logging.

Managing Catalina as an MBean

Because Catalina is a Java class, if you enable Java Management Extentions (JMX) management, you can actually manage all of Catalina's exposed functions as a single MBean, and reference all its hierarchical elements by name.  Apache maintains a list of all the MBean names as part of the Tomcat documentation.

In order to begin managing Catalina as an MBean, all you need to do is modify the CATALINA_OPTS system variable to allow JMX access.

For a comprehensive, step by step guide to enabling and using JMX with Catalina, check out our guide to Tomcat JMX!  

Learn More About Catalina

If you want to learn more about the Catalina servlet container, there are a number of resources you can consult.  Here are some of our favorite Tomcat Catalina resources:

Understanding Apache Tomcat - MuleSoft's comprehensive guide to Apache Tomcat, including FAQs, HOW-TO's, whitepapers, and more.

The Tomcat API - Apache's documentation of the Tomcat API, with detailed information about each package and its contained elements.

The Java Servlet Specification - Information on the Servlet specification that Catalina implements.

The Tomcat Mailing Lists - User and Developer Discussions about Tomcat-related topics hosted on the Apache Website.