Embedded Tomcat Starters

This repository packages the existing embedded Tomcat launcher as three release-ready Maven modules:

• tomcat9 for Java EE 8 / javax.* applications on Tomcat 9.0.122
• tomcat10 for Jakarta EE 10 / jakarta.* applications on Tomcat 10.1.60
• tomcat11 for Jakarta EE 11 / jakarta.* applications on Tomcat 11.0.26

All three modules compile the same shared launcher sources from shared-java and only vary the Tomcat dependency line. Each runnable jar includes embedded Tomcat core, JSP, WebSocket, DBCP, Tomcat JDBC pool, and the launcher. That keeps the implementation generalized while still producing one runnable jar per Tomcat major.

Build

From the repository root:

Use a JDK 25 toolchain before building.

./mvnw clean package

This produces one fat jar per module:

• tomcat9/target/embedded-tomcat-starter-tomcat9-x.jar
• tomcat10/target/embedded-tomcat-starter-tomcat10-x.jar
• tomcat11/target/embedded-tomcat-starter-tomcat11-x.jar

Run

Each jar supports the same launcher arguments:

java -jar tomcat9/target/embedded-tomcat-starter-tomcat9-x.jar --appProject=C:\w\ws\backend --contextXml=C:\w\java\backend\conf\Catalina\localhost\backend.xml --contextPath=/backend --port=8080

--appProject and --contextXml are required. All other arguments are optional.

Available arguments:

• --appProject=...
• --contextXml=...
• --webappDir=...
• --explodedWebapp=true|false
• --classesDir=...
• --catalinaBase=...
• --contextPath=...
• --host=...
• --port=...
• --reloadable=true|false
• --sharedLibDir=dir1<path-separator>dir2
• --watchSource=...
• --watchTarget=...
• --watchExtensions=...

Directory watcher

When both --watchSource and --watchTarget are supplied, a file-system watcher runs as a daemon thread alongside Tomcat. It recursively monitors the source directory and copies changed files into the target directory, preserving the relative path structure.

This is useful for JSF development workflows where .xhtml facelets, CSS, and other web resources should be reflected immediately without a rebuild:

java -jar tomcat11/target/embedded-tomcat-starter-tomcat11-x.jar \
  --appProject=C:\w\ws\myapp \
  --contextXml=C:\w\ws\myapp\conf\Catalina\localhost\myapp.xml \
  --watchSource=C:\w\ws\myapp\src\main\webapp \
  --watchTarget=C:\w\ws\myapp\target\classes\META-INF\resources \
  --watchExtensions=.xhtml,.css,.js,.properties

• --watchExtensions accepts a comma-separated list of dot-prefixed extensions (e.g. .xhtml,.css,.js). Use * to watch all file types. When omitted, all files are watched.

Notes:

• If --contextPath is omitted, the launcher derives it from the context.xml file name, so backend.xml becomes /backend and ROOT.xml becomes the root context.

• By default, webappDir is <appProject>/src/main/webapp, classesDir is <appProject>/target/classes, and discovered runtime jars are mounted under WEB-INF/lib.

• Set --explodedWebapp=true when webappDir points to a complete exploded web application containing its own WEB-INF/classes and WEB-INF/lib. In this mode --webappDir is required, classesDir is ignored, and runtime jars from appProject are not mounted a second time:

  java -jar tomcat11/target/embedded-tomcat-starter-tomcat11-x.jar \
    --appProject=C:\w\ws\myapp \
    --contextXml=C:\w\ws\myapp\conf\Catalina\localhost\myapp.xml \
    --webappDir=C:\w\ws\myapp\target\myapp \
    --explodedWebapp=true
  

• --sharedLibDir uses the current platform path separator: ; on Windows and : on Unix-like systems.

• Application runtime jars discovered under <appProject>/target/dependency, <appProject>/target/lib, and exploded <appProject>/target/*/WEB-INF/lib directories are mounted under /WEB-INF/lib. Jars from --sharedLibDir are loaded through the parent classloader and are intended for shared container-style libraries.

• If --sharedLibDir is omitted, the launcher looks for a sibling lib directory next to the application root inferred from contextXml, for example <appProject>/lib when contextXml is under <appProject>/conf/Catalina/localhost.

• context.xml parsing covers Resource, Environment, Parameter, and nested Resources entries for PreResources, JarResources, and PostResources when they use Tomcat DirResourceSet, JarResourceSet, or FileResourceSet. DataSource Resource entries without a factory default to Tomcat DBCP; entries that specify another factory, such as Tomcat JDBC pool, keep their factory-specific properties unchanged.

GitHub release

Tag the repository with a semantic version such as v1.0.0. The workflow in .github/workflows/release.yml builds all modules and publishes the three runnable jars as release assets.