Embedded Tomcat

Download from http://www.nyangau.org/et/et.zip.

Overview

Often people develop web applications and deploy the resulting .war file to Tomcat, or other servlet engine, or application server.

These servlet engines can come with their own baggage, which includes complex installation, configuration and administration. It also can include larger deployment footprints and runtime requirements. As servlet engines can sometimes be provided by other groups or departments, operational/procedural dependencies can be created between AD groups and web teams or system administrators.

Often what you want is that some application you have written should also listen on a port and serve web content too. Or perhaps the packaging and deployment framework within which you work doesn't play nicely with the operational constraints described above.

So for this, we can use Embedded Tomcat. This makes Tomcat a part of your application. Your application includes a few Tomcat related .jar files. Upon startup, the application creates a new Tomcat(), customises it a little and starts it listening for web requests.

This package is really a demonstration of how this can work.

Components

This package delivers three Maven projects.

My WAR

The mywar project is a simple web application. It includes some static content and a servlet.

The servlet appears in three places (url-patterns), two requiring authenticated access, one also requiring confidential access (ie: SSL).

The pom.xml produces a .war as its result.

In principle, this .war could be deployed to real Tomcat, another servlet engine or application server, or even to the cloud.

Web Container using Embedded Tomcat

The wcet project depends on the appropriate Tomcat .jars.

This includes a WCET class, which is what instantiates Embedded Tomcat and customises it :-

it provides a static method (call this first) to stop logging going to the console, and instead log it to N files of M MB each, and it also reformats the logging to something nicer than the java.util.logging.* default
it sets up a HTTP and/or HTTPS connector (with reasonable security settings)
it adds a valve to log accesses, and does so to N files of M MB each
it provides methods to add users and roles
it provides a method to register a .war file at a certain context location

The code explicitly avoids log rotation based on date, as runaway logging can fill a disk and take a system down before rotation kicks in. Instead it promises to keep within a disk size limit, and if runaway logging does occur, the worst that happens is that the logs don't go back as far in time as they would normally. Log numbers and sizes have defaults which can be overridden using properties.

My Web Process

The mywebproc project instantiates a WCET, registers My WAR into it, and starts listening.

The main .java file is therefore very short and unexciting. It is likely that in real use, userids and passwords might be obtained from a credential store and configured into the WCET.

Its pom.xml depends on the mywar project and the wcet project.

Perhaps the most interesting thing is the use of an assembly.xml to construct the file deployable asset. It creates a .zip file containing something like this :-

$ unzip -v mywebproc-0.1-SNAPSHOT-bin.zip 
Archive:  mywebproc-0.1-SNAPSHOT-bin.zip
 Length   Method    Size  Cmpr    Date    Time   CRC-32   Name
--------  ------  ------- ---- ---------- ----- --------  ----
      76  Defl:N       76   0% 12-30-2015 12:26 5b612a39  mywebproc.bat
  174180  Defl:N   160728   8% 02-17-2024 10:03 d3a3e26e  lib/tomcat-jasper-el-10.1.18.jar
    3169  Defl:N     1763  44% 12-29-2015 16:03 b6bb4483  keystores/webserver.jks
   11655  Defl:N     9661  17% 02-17-2024 10:03 9775dc2e  lib/tomcat-api-10.1.18.jar
       0  Stored        0   0% 12-29-2015 16:03 00000000  keystores/
  231775  Defl:N   211941   9% 02-17-2024 10:03 7f58266c  lib/tomcat-util-scan-10.1.18.jar
      84  Defl:N       84   0% 12-30-2015 12:26 1a2d7e3f  mywebproc
  151893  Defl:N   142650   6% 02-17-2024 10:03 248580bd  lib/tomcat-jdbc-10.1.18.jar
       0  Stored        0   0% 02-17-2024 10:09 00000000  lib/
  213824  Defl:N   195190   9% 02-17-2024 10:03 8a9056b2  lib/tomcat-util-10.1.18.jar
   11297  Defl:N    10167  10% 02-17-2024 10:04 72a48962  lib/wcet-0.1-SNAPSHOT.jar
    2727  Defl:N     1815  33% 02-17-2024 10:09 dae6fe71  lib/mywebproc-0.1-SNAPSHOT.jar
 3512643  Defl:N  3283815   7% 02-17-2024 10:03 4b46efba  lib/tomcat-embed-core-10.1.18.jar
   14207  Defl:N    11212  21% 02-17-2024 10:03 a0aed964  lib/tomcat-annotations-api-10.1.18.jar
       0  Stored        0   0% 02-17-2024 10:09 00000000  base/
       0  Stored        0   0% 02-17-2024 10:09 00000000  base/webapps/
    4001  Defl:N     2810  30% 02-17-2024 10:08 4db679bc  base/webapps/mywar.war
  672294  Defl:N   627040   7% 02-17-2024 10:03 9ba8cac2  lib/tomcat-embed-jasper-10.1.18.jar
  261049  Defl:N   242788   7% 02-17-2024 10:03 2383bcaf  lib/tomcat-embed-el-10.1.18.jar
 3160927  Defl:N  3012755   5% 02-17-2024 10:03 90494674  lib/ecj-3.33.0.jar
  576650  Defl:N   542812   6% 02-17-2024 10:03 30c63768  lib/tomcat-jasper-10.1.18.jar
  366661  Defl:N   344432   6% 02-17-2024 10:03 6627679d  lib/tomcat-servlet-api-10.1.18.jar
   48715  Defl:N    44898   8% 02-17-2024 10:03 6c28634e  lib/tomcat-juli-10.1.18.jar
   77961  Defl:N    65663  16% 02-17-2024 10:03 dcca3557  lib/tomcat-jsp-api-10.1.18.jar
   91393  Defl:N    84968   7% 02-17-2024 10:03 4a2337bc  lib/tomcat-el-api-10.1.18.jar
--------          -------  ---                            -------
 9587181          8997268   6%                            25 files

Its important to spot that although mywebproc-0.1-SNAPSHOT.jar was put in the lib subdirectory, the assembly process has carefully arranged to put mywar.war (named without a version suffix) in the base/webapps/ subdirectory. This is so the Java code that registers a .war into Tomcat has a fixed filename to refer to it by.

Note the inclusion of a couple of scripts (mywebproc and mywebproc.bat) to run the program. You can imagine more sophisticated versions that could be used as init-scripts.

The intent of this structure is that you simply unzip the file, and run the script.

In reality, the installation process or the start script is likely to need to add a context.xml into the META-INF/ subdirectory of the .war file. This file contains things such as database connection definitions, and is therefore likely to vary depending on the environment into which the application is deployed.

Usage

This code now requires Java 11 (or later).

Usage :-

$ unzip mywebproc-0.1-SNAPSHOT-bin.zip
$ bin/mywebproc

Point your browser at http://localhost:8080/mywar/ or https://localhost:8443/mywar/.

This code now uses Tomcat 10 because the later Tomcat 11 requires Java 21, and I'm not moving to this quite yet. As side effect of this is that the Servlet spec is now provided by Jakarta, requiring changes to the imports in the code and the maven dependencies.

Copying

Feel free to copy, its public domain. Caveat Emptor.

The documentation is written and maintained by the Embedded Tomcat example author, Andy Key

andy.z.key@googlemail.com