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 e2bf21e148ff53a5f639e511925fab3b2713eacc
Author: Lukasz Lenart <[email protected]>
AuthorDate: Sat Nov 14 08:31:47 2026 +0100

    WW-5864 docs(spec): design for the struts:watch Maven goal
    
    Co-Authored-By: Claude Opus 5.5 <[email protected]>
---
 .../2026-11-14-struts-maven-plugin-watch-design.md | 167 +++++++++++++++++++++
 1 file changed, 167 insertions(+)

diff --git 
a/docs/superpowers/specs/2026-11-14-struts-maven-plugin-watch-design.md 
b/docs/superpowers/specs/2026-11-14-struts-maven-plugin-watch-design.md
new file mode 100644
index 000000000..01c977941
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-14-struts-maven-plugin-watch-design.md
@@ -0,0 +1,167 @@
+# Struts Maven Plugin: `struts:watch` — Design
+
+Date: 2026-11-14 · Ticket: 
[WW-5864](https://issues.apache.org/jira/browse/WW-5864) · Status: approved
+
+## Intent
+
+Developers working on a Struts application under `mvn jetty:run` (or any 
server that runs
+from `target/classes`) with `struts.devMode=true` expect edits to `struts.xml` 
and message
+bundles to show up on the next request. Today they have to restart the server.
+
+A spike (2026-11-14, showcase app, devMode on, Jetty 11 plugin) showed that 
Struts' own
+reloading works — the gap is in the build layout:
+
+| Change | Edited in `src/main/resources` | Same edit in `target/classes` |
+|---|---|---|
+| New action in `struts.xml` | not picked up | picked up on the next request |
+| Message in `globalMessages.properties` | not picked up | picked up on the 
next request |
+| Action class (recompiled) | — | old class keeps running |
+
+Struts watches the URL it loaded each file from (`DefaultFileManager` / 
`FileRevision`,
+checked per request by `ConfigurationManager.conditionalReload()`). Under 
`jetty:run` that is
+`target/classes/...`, and nothing copies edits there while the server runs. 
When something
+does, Jetty's own scanner (`<scan>` in the showcase pom) additionally restarts 
the whole
+webapp, duplicating the work Struts already did.
+
+`struts:watch` closes the copy gap: it watches the project's resource 
directories and pushes
+changed files into the output directory through Maven's own resource 
processing, so Struts'
+existing reload picks them up.
+
+## Goals
+
+- Save a resource file in `src/main/resources`, refresh the browser, see the 
change — no
+  server restart, no IDE build step, works from the command line.
+- Honour the project's Maven resource configuration: the declared 
`<resources>` directories,
+  includes/excludes, `targetPath`, and filtering (`${...}` placeholders), so 
the file in
+  `target/classes` is exactly what `process-resources` would have produced.
+- Run alongside whatever server the developer already uses (`jetty:run`, 
Cargo, Tomcat
+  plugin, an IDE-managed server) with no dependency on any of them.
+- Help the developer see the loop working: log each file pushed, warn when 
Struts' reload
+  switches look off.
+
+## Non-goals
+
+- **Java class reloading.** Out of scope (decided). Developers keep using a 
restart or JVM
+  hotswap under a debugger.
+- **Starting or embedding a server.** The plugin never owns Jetty/Tomcat 
(decided: alongside,
+  not a wrapper).
+- **Webapp files (JSP/FTL in `src/main/webapp`).** Already served from source 
by `jetty:run`.
+- **Gradle, and Struts Boot apps.** A later, separate question.
+- **Multi-module applications** (resources in a jar module, `jetty:run` in the 
war module).
+  Single module only for now (decided). The goal watches the module it runs 
in; run from a
+  reactor with more than one project, it fails fast with a message to run it 
in the module
+  that owns the resources (`-pl <module>`) instead of silently watching only 
the first one.
+- **Any change to Struts core's reload mechanism.** The spike showed it works.
+
+## Anti-goals
+
+- A file in `target/classes` that differs from what `process-resources` would 
produce
+  (unfiltered placeholders, ignored excludes). Developers would chase phantom 
bugs.
+- Anything that leaks into the deployed application — this is a build-time 
tool only.
+- A save that triggers a full webapp restart in the documented setup.
+
+## Constraints
+
+- Lives in the Struts reactor, released with Struts. First `maven-plugin` 
packaging module in
+  the repo: needs `maven-plugin-plugin` and the Maven plugin API (`provided` 
scope).
+- Java 17 (`maven.compiler.release` in the root pom).
+- ASF naming: `maven-*-plugin` is reserved for Apache Maven; the artifact is
+  `struts-maven-plugin`, giving the prefix `struts` → `mvn struts:watch`. 
Prefix resolution
+  works when the plugin is declared in the application's pom (no 
`pluginGroups` needed).
+- macOS: the JDK `WatchService` is polling-based with a ~10 s default interval 
there, which
+  is too slow for save-and-refresh.
+
+## Approaches considered
+
+1. **IDE build + Jetty scan config (docs only).** IntelliJ ⌘F9 / Eclipse 
auto-build already
+   copy resources. No code, but needs the IDE and a habit; no help from the 
CLI.
+2. **Point Jetty's classloader at `src/main/resources` (pom recipe).** No 
code, no build step,
+   but loses resource filtering and it is unverified whether `extraClasspath` 
can precede
+   `target/classes`.
+3. **Struts core watches source folders in devMode.** Server-agnostic, but 
bakes the Maven
+   layout into core, ignores filtering, and adds devMode code that reads 
outside the
+   classpath — new core surface and security review.
+4. **Struts Maven plugin** — chosen. Two variants:
+   - **Alongside (`struts:watch`)** — chosen: small, no server dependency, 
survives server
+     version changes; costs a second command (or a background mode, see below).
+   - Wrapper (`struts:run` embedding a server) — rejected: Struts would own a 
server version,
+     its Jakarta line and every config option developers expect from 
`jetty:run`; effectively
+     a second Struts Boot.
+
+## Design
+
+### Module
+
+- Location: `tools/struts-maven-plugin` (new top-level `tools` aggregator; 
`plugins/` is
+  reserved for runtime Struts plugins). _My call._
+- `groupId` `org.apache.struts`, `artifactId` `struts-maven-plugin`, packaging 
`maven-plugin`.
+- No dependency on `struts2-core` — it never loads Struts classes.
+
+### Goal `watch`
+
+- Default: blocking. Developer runs `mvn struts:watch` in a second terminal 
next to
+  `mvn jetty:run`. Ctrl+C stops it.
+- Background mode (`<background>true</background>` / 
`-Dstruts.watch.background=true`):
+  the goal starts a daemon watcher thread and returns, so binding it to 
`process-resources`
+  in the app's pom makes `mvn jetty:run` alone enough (jetty:run forks the 
lifecycle, then
+  blocks; the watcher lives as long as the Maven JVM). _My call; the builder 
must verify the
+  thread survives `jetty:run`'s forked lifecycle._
+- A bound background execution is a no-op unless explicitly switched on
+  (`-Dstruts.watch=true`, typically `mvn jetty:run -Dstruts.watch`), so 
committing the binding
+  to an application pom never starts a watcher in 
`package`/`install`/CI/release builds.
+  _My call._
+- Watched roots: every `<resource>` directory from the project model 
(`project.getResources()`),
+  not a hard-coded `src/main/resources`.
+- On change: re-process **only the changed file** with the project's resource 
settings via
+  `maven-filtering` (`MavenResourcesFiltering`, the library 
`maven-resources-plugin` uses),
+  honouring includes/excludes, `targetPath`, filtering, encoding and 
delimiters. Write to
+  `project.getBuild().getOutputDirectory()`.
+- Filtering settings that are not in the project model (delimiters, 
`escapeString`,
+  `nonFilteredFileExtensions`, `propertiesEncoding`, `useDefaultDelimiters`,
+  `addDefaultExcludes`) are read from the effective `maven-resources-plugin` 
configuration of
+  the `default-resources` execution in the model — no mirror parameters on 
`struts:watch`, so
+  the two cannot drift. _My call._
+- A change to a filter file (`build.filters`) re-pushes every filtered 
resource. _My call._
+- Extra `copy-resources` executions writing into the output directory are out 
of scope. _My call._
+- On delete: remove the corresponding output file.
+- Change detection: a last-modified/size polling scan of the watched roots at 
a configurable
+  interval (default 500 ms), not `WatchService`, because of the macOS 
constraint. Debounce so
+  an editor's save-via-rename produces one push.
+- Logging: one INFO line per push (`pushed struts.xml → 
target/classes/struts.xml`).
+
+### Struts-specific help
+
+- At start, best-effort check of `struts.devMode`, 
`struts.configuration.xml.reload` and
+  `struts.i18n.reload` in the output directory's `struts.xml` / 
`struts.properties`; WARN when
+  devMode is explicitly `false` or a reload switch is explicitly `false`. 
Best-effort only —
+  constants set from Spring, Java config or system properties are invisible, 
so never fail.
+- Docs show the Jetty plugin config that stops Jetty's scanner restarting on 
resource
+  changes. _Unverified whether Jetty 11/12's `scanClassesPattern` excludes 
cover this; the
+  builder must confirm, or document `<scan>0</scan>` as the fallback._
+
+### Showcase and docs
+
+- `apps/showcase` declares the plugin with a bound background execution, inert 
without
+  `-Dstruts.watch` (so CI and the `jetty:start` ITs never run a watcher), and 
its Jetty config
+  is switched to the documented "no restart on resource change" setup — the 
showcase is the
+  reference setup. Showcase keeps `devMode=false` (it also runs the ITs). The 
plugin's own
+  invoker IT is what actually exercises the watcher. _My call._
+- The plugin's generated goal docs ship with the module; the struts-site usage 
page is a
+  follow-up PR in that repo. _My call._
+- Fix version comes from the ticket.
+
+## Testing
+
+- The watcher/copier is a plain class tested without Maven (JUnit 4, matching 
the repo):
+  change, add, delete, excluded file ignored, filtered placeholder resolved, 
`targetPath`
+  respected, debounce.
+- One integration test through `maven-invoker-plugin` (or the plugin testing 
harness) on a
+  tiny fixture project running the goal in background mode. _Builder's choice 
of harness._
+
+## Left to the builder
+
+- Exact `maven-plugin-plugin` / `maven-filtering` versions and the Maven API 
baseline.
+- Thread/lifecycle handling for background mode and clean shutdown.
+- Test harness for the integration test.
+- Whether the `tools` aggregator joins the default reactor or a profile 
(default preferred, so
+  it is released with every Struts release).

Reply via email to