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.

Reply via email to