Programmatically Create, Configure and Run a Tomcat Server

1. Overview

In this quick article, we’re going to programmatically create, configure and run a Tomcat server.

2. Setup

Before we get started, we need to setup our Maven project by adding the below dependencies to our pom.xml:

<dependencies>
    <dependency>
        <groupId>org.apache.tomcat</groupId>
        <artifactId>tomcat-catalina</artifactId>
        <version>${tomcat.version}</version>
    </dependency>
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>${apache.httpclient}</version>
    </dependency>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Here is a link to Maven Central with the latest versions of the dependencies used here in the project.

3. Initializing and Configuring Tomcat

Let’s first talk about the steps required for initialization and configuration of a Tomcat server.

3.1. Creating Tomcat

We can create an instance by simply doing:

Tomcat tomcat = new Tomcat();

Now that we have the server, let’s configure it.

3.2. Configuring Tomcat

We’ll focus on how to get the server up and running, adding a servlet and a filter.

First off, we need to configure a port, hostname and an appBase (typically web apps). For our purpose we’ll use the current directory:

tomcat.setPort(8080);
tomcat.setHostname("localhost");
String appBase = ".";
tomcat.getHost().setAppBase(appBase);

Next, we need to set a docBase (the context root directory for this web application):

File docBase = new File(System.getProperty("java.io.tmpdir"));
Context context = tomcat.addContext("", docBase.getAbsolutePath());

At this point, we have an almost functioning Tomcat.

Next, we’ll add a servlet and a filter and start the server to see if it’s working.

3.3. Adding a Servlet to Tomcat Context

Next, we’ll add a simple text to the HttpServletResponse. This is the text that is going to be displayed when we access the URL mapping for this servlet.

Let’s first define our servlet:

public class MyServlet extends HttpServlet {

    @Override
    protected void doGet(
      HttpServletRequest req, 
      HttpServletResponse resp) throws IOException {
 
        resp.setStatus(HttpServletResponse.SC_OK);
        resp.getWriter().write("test");
        resp.getWriter().flush();
        resp.getWriter().close();
    }
}

Now we add this servlet to the Tomcat server:

Class servletClass = MyServlet.class;
Tomcat.addServlet(
  context, servletClass.getSimpleName(), servletClass.getName());
context.addServletMappingDecoded(
  "/my-servlet/*", servletClass.getSimpleName());

3.4. Adding a Filter to Tomcat Context

Next, we define a filter and add it to Tomcat:

public class MyFilter implements Filter {

    @Override
    public void init(FilterConfig filterConfig) {
        // ...
    }

    @Override
    public void doFilter(
      ServletRequest request, 
      ServletResponse response, 
      FilterChain chain) 
      throws IOException, ServletException {

        HttpServletResponse httpResponse = (HttpServletResponse) response;
        httpResponse.addHeader("myHeader", "myHeaderValue");
        chain.doFilter(request, httpResponse);
    }

    @Override
    public void destroy() {
        // ...
    }
}

Adding the filter to the context requires a bit more work:

Class filterClass = MyFilter.class;
FilterDef myFilterDef = new FilterDef();
myFilterDef.setFilterClass(filterClass.getName());
myFilterDef.setFilterName(filterClass.getSimpleName());
context.addFilterDef(myFilterDef);

FilterMap myFilterMap = new FilterMap();
myFilterMap.setFilterName(filterClass.getSimpleName());
myFilterMap.addURLPattern("/my-servlet/*");
context.addFilterMap(myFilterMap);

At this point, we should have a servlet and a filter added to the Tomcat.

All that is left to do is start it and get the “test” page and check the logs to see if the filter works.

4. Starting Tomcat

This is a pretty simple operation and after that, we should see Tomcat running:

tomcat.start();
tomcat.getServer().await();

Once it started, we can go to http://localhost:8080/my-servlet and see the test page:

And if we look at the logs we’ll see something like this:

These logs show that Tomcat started listening on port 8080 and also that our filter is working correctly.

5. Conclusion

In this tutorial, we went through a basic programmatic setup of a Tomcat server.

We looked at how to create, configure and run the server, but also at how we can add a Servlet and a Filter programmatically to the Tomcat context.