Skip to content

WW-5864 Add struts:watch Maven goal for resource hot reload under jetty:run - #2143

Draft
lukaszlenart wants to merge 22 commits into
mainfrom
feat/WW-5864-struts-maven-plugin-watch
Draft

lukaszlenart wants to merge 22 commits into
mainfrom
feat/WW-5864-struts-maven-plugin-watch

Conversation

@lukaszlenart

@lukaszlenart lukaszlenart commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Fixes WW-5864

Why

With struts.devMode=true, Struts reloads struts.xml and message bundles when the files it loaded change. Under mvn jetty:run those files are the copies in target/classes, and nothing updates them while the server runs, so edits in src/main/resources need a restart. A spike confirmed the framework's reload works as soon as the target/classes copy changes; the gap is the build layout. Jetty's <scan> additionally restarted the whole webapp on top of Struts' own reload.

What

A new tools/struts-maven-plugin module (first maven-plugin packaging in the reactor), marked [EXPERIMENTAL] like Struts Boot (goals, parameters and defaults may change between minor releases), with a watch goal that runs alongside the developer's server:

  • polls the module's <resources> directories (500 ms; the JDK WatchService polls slowly on macOS) and debounces, so an editor's save-via-rename gives one push
  • pushes each changed file into target/classes through maven-filtering, using the effective maven-resources-plugin configuration (delimiters, encodings, escapeString, nonFilteredFileExtensions, plugin-level <filters>/useBuildFilters, …); deletes are mirrored; files whose output is missing or older are pushed once at startup
  • blocking mode (mvn struts:watch) or a background mode bound to process-resources, which does nothing unless -Dstruts.watch (mvn jetty:run -Dstruts.watch); one background watcher per output directory
  • warns at startup, best-effort, when struts.devMode or the reload switches are off (an explicit false wins over devMode, as in StrutsBeanSelectionProvider#switchDevMode)
  • single module only: run from a reactor with more than one project it fails and asks for -pl <module>

Out of scope: Java class reloading, webapp files, multi-module apps, Gradle, Struts Boot.

The showcase declares the plugin (inert by default) and its Jetty config scans only **/*.class, so recompiles still restart the webapp but resource pushes don't. The showcase keeps devMode=false because it also runs the ITs; the README explains what an app needs.

Design and plan: docs/superpowers/specs/2026-11-14-struts-maven-plugin-watch-design.md, docs/superpowers/plans/2026-11-14-struts-maven-plugin-watch.md.

Testing

  • 49 unit tests (JUnit 4 + AssertJ)
  • one invoker IT runs the real goal on a fixture project; the edit is gated on the Watching N resource root(s) log line and the push must be logged after it, so the startup push cannot satisfy it. It uses blocking mode with a timeout, since a background run's Maven JVM exits immediately
  • live check: mvn jetty:run -Dstruts.watch on the showcase (devMode switched on locally) — a new action and a changed message were picked up on the next request, no Jetty restart

Build cost

The IT adds ~12 s to verify/install of this module and is skipped with -DskipITs. src/it/settings.xml uses the invoker docs' local-repository profile (@localRepositoryUrl@), so the IT resolves from the outer local repo; an artifact missing there can still fall back to Central rather than failing.

Known follow-ups (not in this PR)

  • fileNameFiltering=true with ${...} in a file name: the output path is computed from the unfiltered name
  • the background thread lives as long as the JVM — under mvnd a later build reuses the earlier watcher
  • the <outputDirectory> warning also fires when it is set to the default value

Security review (/security-review plus SECURITY.md/THREAT_MODEL.md): no findings — build-time tool, inputs are the developer's own pom and resources.

🤖 Generated with Claude Code

lukaszlenart and others added 22 commits November 14, 2026 08:31
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Add a background struts:watch execution (process-resources) to the showcase,
inert unless -Dstruts.watch is given.

Jetty scanner research: jetty-maven-plugin 11.0.26 exposes scanClassesPattern
(includes/excludes), so scanning compiled classes is kept and only **/*.class
is scanned; resource pushes into target/classes no longer restart the webapp.
<scan>0</scan> was not needed.

rest-showcase uses scanIntervalSeconds, which does not exist in the 11.0.26
plugin.xml (silently ignored), so scanning there was never configured via that
name; the same scanClassesPattern is added so it holds if scanning is enabled.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ocal repo

-DskipITs skips the invocation, src/it/settings.xml points the IT at the
outer local repository instead of Central, the fixture timeout drops to
10 s and invoker.timeoutInSeconds guards against a hang.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reads <filters>, <useBuildFilters>, <escapeWindowsPaths>,
<supportMultiLineFiltering> and <fileNameFiltering> from the effective
maven-resources-plugin configuration, watches the combined filter files,
and warns when <outputDirectory> or <skip> is set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Throwable escaping the background watcher is logged before the thread
ends, and a second bound execution in the same JVM for the same output
directory logs that a watcher is already running and returns.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The module name carries the [EXPERIMENTAL] suffix like Struts Boot, and the
README says goals, parameters and defaults may change between minor releases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
79.4% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant