This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch feat/WW-5864-struts-maven-plugin-watch in repository https://gitbox.apache.org/repos/asf/struts.git
commit 40c2d9e9e72b803b6c3f8be798b90abfde822661 Author: Lukasz Lenart <[email protected]> AuthorDate: Sat Nov 14 09:14:24 2026 +0100 WW-5864 docs(tools): struts-maven-plugin usage Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --- tools/struts-maven-plugin/README.md | 89 +++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/tools/struts-maven-plugin/README.md b/tools/struts-maven-plugin/README.md new file mode 100644 index 000000000..48ffb639a --- /dev/null +++ b/tools/struts-maven-plugin/README.md @@ -0,0 +1,89 @@ +# Struts Maven Plugin + +`struts:watch` copies edited resources (`struts.xml`, `*.properties`, FreeMarker templates, validation files) into +`target/classes` while an application runs, so Struts' own reload picks them up without a rebuild or restart. + +It pushes resource changes only. It does not compile or reload Java classes: use a restart or debugger hotswap for +those. Webapp files (JSP, FTL under `src/main/webapp`) are already served from source. + +## Application setup + +The application must have reloading on: `struts.devMode=true` (with the reload switches not explicitly `false`), or +`struts.configuration.xml.reload=true` and `struts.i18n.reload=true`. An explicit `false` wins over `devMode`. The goal +logs a warning at startup when it can see the switches are off (best effort: it reads only `struts.xml` and +`struts.properties` in the output directory). + +Declare the plugin in the application's `pom.xml`; the `struts:` prefix resolves from there, no `pluginGroups` entry +is needed. + +```xml +<plugin> + <groupId>org.apache.struts</groupId> + <artifactId>struts-maven-plugin</artifactId> + <version>${struts.version}</version> +</plugin> +``` + +## Running it + +Next to a server started in another terminal, the goal blocks until Ctrl+C: + +``` +mvn struts:watch -pl <module> +``` + +Or bound to `process-resources` in the background, switched on from the command line, together with the Jetty plugin: + +```xml +<execution> + <id>watch</id> + <phase>process-resources</phase> + <goals> + <goal>watch</goal> + </goals> + <configuration> + <background>true</background> + </configuration> +</execution> +``` + +``` +mvn jetty:run -Dstruts.watch +``` + +Without `-Dstruts.watch` a background execution does nothing. + +Each push is logged, for example `pushed struts.xml -> target/classes/struts.xml`. Files whose output is missing or +older than the source are pushed once at startup. Filtering follows the module's `maven-resources-plugin` +configuration. + +## Parameters + +| Parameter | Property | Default | Meaning | +|---|---|---|---| +| `pollInterval` | `struts.watch.pollInterval` | `500` | Milliseconds between scans of the resource directories | +| `background` | `struts.watch.background` | `false` | Run on a daemon thread and return, so the goal can be bound to a phase | +| `enabled` | `struts.watch` | `false` | Switches background watching on; consulted only when `background` is `true` | +| `timeout` | `struts.watch.timeout` | `0` | Seconds after which a blocking run stops; `0` runs until interrupted | + +## Jetty scanner + +Pushed resources land in `target/classes`, which the Jetty Maven plugin's scanner would treat as a change and restart +the webapp. Restrict its class scan to compiled classes so recompiles still restart the webapp but resource pushes do +not: + +```xml +<scanClassesPattern> + <includes> + <include>**/*.class</include> + </includes> +</scanClassesPattern> +``` + +`apps/showcase/pom.xml` has both the bound execution and this setting. Its committed `struts.xml` keeps `devMode` and +the reload switches off, so to try it there flip them locally. + +## Limitations + +- Single module only: in a multi-reactor build the goal fails with a message to run it with `-pl <module>`. +- No Java class reloading, no Gradle support, no Struts Boot support.
