Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
e2bf21e
WW-5864 docs(spec): design for the struts:watch Maven goal
lukaszlenart Nov 14, 2026
2471b04
WW-5864 docs(plan): implementation plan for the struts:watch goal
lukaszlenart Nov 14, 2026
cf10e46
WW-5864 build(tools): add struts-maven-plugin module skeleton
lukaszlenart Nov 14, 2026
4ae6d97
WW-5864 feat(tools): scan resource roots and debounce changes
lukaszlenart Nov 14, 2026
d1d2c69
WW-5864 fix(tools): keep watching when a resource scan fails
lukaszlenart Nov 14, 2026
102d84f
WW-5864 feat(tools): push changed resources through maven-filtering
lukaszlenart Nov 14, 2026
18b430e
WW-5864 feat(tools): warn when Struts reload switches are off
lukaszlenart Nov 14, 2026
bbe0e55
WW-5864 feat(tools): add the struts:watch goal
lukaszlenart Nov 14, 2026
d75f44e
WW-5864 fix(tools): report stale-push failures and keep going
lukaszlenart Nov 14, 2026
0fb7e39
WW-5864 test(tools): invoker IT for struts:watch
lukaszlenart Nov 14, 2026
59ca0ee
WW-5864 test(tools): gate the IT edit on the watch loop having started
lukaszlenart Nov 14, 2026
e528772
WW-5864 build(showcase): reference struts:watch setup and Jetty scanner
lukaszlenart Nov 14, 2026
40c2d9e
WW-5864 docs(tools): struts-maven-plugin usage
lukaszlenart Nov 14, 2026
d0570f0
WW-5864 docs(tools): fix README version placeholder and warning notes
lukaszlenart Nov 14, 2026
2200e51
WW-5864 build(rest-showcase): revert scanClassesPattern addition
lukaszlenart Nov 14, 2026
707242d
WW-5864 build(tools): skippable invoker IT resolving from the outer l…
lukaszlenart Nov 14, 2026
02e6d33
WW-5864 fix(tools): push overlapping roots in scan order
lukaszlenart Nov 14, 2026
b87303e
WW-5864 fix(tools): follow plugin-level filters and escaping settings
lukaszlenart Nov 14, 2026
d40f839
WW-5864 fix(tools): one reported background watcher per output directory
lukaszlenart Nov 14, 2026
d8e5526
WW-5864 docs(tools): pasteable execution snippet and multi-module notes
lukaszlenart Nov 14, 2026
ea48149
WW-5864 docs(tools): dev profile to keep struts:watch on locally
lukaszlenart Nov 14, 2026
bdebab4
WW-5864 chore(tools): mark the Struts Maven Plugin as experimental
lukaszlenart Nov 14, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions apps/showcase/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,23 @@

<build>
<plugins>
<plugin>
<groupId>org.apache.struts</groupId>
<artifactId>struts-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<id>watch</id>
<phase>process-resources</phase>
<goals>
<goal>watch</goal>
</goals>
<configuration>
<background>true</background>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
Expand Down Expand Up @@ -285,6 +302,11 @@
<port>8090</port>
</httpConnector>
<scan>10</scan>
<scanClassesPattern>
<includes>
<include>**/*.class</include>
</includes>
</scanClassesPattern>
<webApp>
<extraClasspath>
${project.build.directory}/extraclasspath/struts2-velocity-tools-view-jakarta.jar,
Expand Down
314 changes: 314 additions & 0 deletions docs/superpowers/plans/2026-11-14-struts-maven-plugin-watch.md

Large diffs are not rendered by default.

167 changes: 167 additions & 0 deletions docs/superpowers/specs/2026-11-14-struts-maven-plugin-watch-design.md
Original file line number Diff line number Diff line change
@@ -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).
1 change: 1 addition & 0 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@
<module>core</module>
<module>plugins</module>
<module>boot</module>
<module>tools</module>
<module>apps</module>
</modules>

Expand Down
38 changes: 38 additions & 0 deletions tools/pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.apache.struts</groupId>
<artifactId>struts2-parent</artifactId>
<version>7.5.0-SNAPSHOT</version>
<relativePath>../parent/pom.xml</relativePath>
</parent>

<artifactId>struts2-tools</artifactId>
<packaging>pom</packaging>
<name>Struts 2 Tools</name>

<modules>
<module>struts-maven-plugin</module>
</modules>
</project>
123 changes: 123 additions & 0 deletions tools/struts-maven-plugin/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
# 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.

The Struts Maven Plugin is experimental: its goals, parameters and defaults may change between minor releases.

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, or when `struts.devMode` is not found at all (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>X.Y.Z</version>
</plugin>
```

`X.Y.Z` is the Struts version; the plugin is released together with Struts.

## Running it

Next to a server started in another terminal, the goal blocks until Ctrl+C:

```sh
mvn struts:watch
```

In a multi-module build, run it from the root with `-pl <module>`. Do not add `-am`: it puts the module's dependencies
into the build too, and the goal then fails because it supports a single module.

Or bound to `process-resources` in the background, switched on from the command line, together with the Jetty plugin:

```xml
<plugin>
<groupId>org.apache.struts</groupId>
<artifactId>struts-maven-plugin</artifactId>
<version>X.Y.Z</version>
<executions>
<execution>
<id>watch</id>
<phase>process-resources</phase>
<goals>
<goal>watch</goal>
</goals>
<configuration>
<background>true</background>
</configuration>
</execution>
</executions>
</plugin>
```

```sh
mvn jetty:run -Dstruts.watch
```

Without `-Dstruts.watch` a background execution does nothing.

To keep it on while developing, set the property in a profile rather than in the pom's top-level `<properties>`.
Switched on there, every `package`, `install` and CI build would start a watcher, and a multi-module build would fail
the single-module check:

```xml
<profiles>
<profile>
<id>dev</id>
<properties>
<struts.watch>true</struts.watch>
</properties>
</profile>
</profiles>
```

Run `mvn jetty:run -Pdev`, or list `dev` under `<activeProfiles>` in your own `~/.m2/settings.xml` so plain
`mvn jetty:run` watches on your machine while CI never does.

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, including its plugin-level `<filters>`. The pom is read once at startup: restart the goal after changing
the resource or filtering 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-module build the goal fails with a message to run it with `-pl <module>` (without
`-am`).
- No Java class reloading, no Gradle support, no Struts Boot support.
Loading
Loading