https://github.com/ralscha/embedded-tomcat-starters
https://github.com/ralscha/embedded-tomcat-starters
Last synced: 17 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/ralscha/embedded-tomcat-starters
- Owner: ralscha
- License: apache-2.0
- Created: 2026-05-23T17:08:57.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-03T03:26:22.000Z (23 days ago)
- Last Synced: 2026-06-03T04:26:20.838Z (23 days ago)
- Language: Java
- Size: 27.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.118`
- `tomcat10` for Jakarta EE 10 / `jakarta.*` applications on Tomcat `10.1.55`
- `tomcat11` for Jakarta EE 11 / `jakarta.*` applications on Tomcat `11.0.22`
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.
```sh
./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:
```sh
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=...`
- `--classesDir=...`
- `--catalinaBase=...`
- `--contextPath=...`
- `--host=...`
- `--port=...`
- `--reloadable=true|false`
- `--sharedLibDir=dir1dir2`
- `--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:
```sh
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.
- `--sharedLibDir` uses the current platform path separator: `;` on Windows and `:` on Unix-like systems.
- Application runtime jars discovered under `/target/dependency`, `/target/lib`, and exploded `/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 `/lib` when `contextXml` is under `/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.