This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/struts-examples.git
The following commit(s) were added to refs/heads/main by this push:
new ce03581 feat(action-extension): add example for global, package and
action extensions (#555)
ce03581 is described below
commit ce0358187d7c662f25c0baefd2f51cb681cb6b74
Author: Lukasz Lenart <[email protected]>
AuthorDate: Fri Nov 13 15:54:03 2026 +0100
feat(action-extension): add example for global, package and action
extensions (#555)
* docs(action-extension): add design and implementation plan
Co-Authored-By: Claude Opus 5.5 <[email protected]>
* feat(action-extension): add module with global, package and action
extensions
Co-Authored-By: Claude Opus 5.5 <[email protected]>
* feat(action-extension): add pages and README showing generated URLs and
rejection
Co-Authored-By: Claude Opus 5.5 <[email protected]>
* docs(action-extension): explain how generated URLs pick an extension
Co-Authored-By: Claude Opus 5.5 <[email protected]>
---------
Co-authored-by: Claude Opus 5.5 <[email protected]>
---
action-extension/README.md | 49 +++++++
action-extension/pom.xml | 51 +++++++
action-extension/src/main/resources/log4j2.xml | 15 ++
action-extension/src/main/resources/struts.xml | 41 ++++++
.../src/main/webapp/WEB-INF/jsp/badExtension.jsp | 16 ++
.../src/main/webapp/WEB-INF/jsp/hello.jsp | 15 ++
.../src/main/webapp/WEB-INF/jsp/index.jsp | 20 +++
.../src/main/webapp/WEB-INF/jsp/links.jspf | 28 ++++
.../src/main/webapp/WEB-INF/jsp/orders.jsp | 15 ++
.../src/main/webapp/WEB-INF/jsp/report.jsp | 15 ++
action-extension/src/main/webapp/WEB-INF/web.xml | 21 +++
action-extension/src/main/webapp/index.jsp | 1 +
.../apache/struts_example/ActionExtensionTest.java | 90 ++++++++++++
.../plans/2026-11-13-action-extension-example.md | 162 +++++++++++++++++++++
.../2026-11-13-action-extension-example-design.md | 76 ++++++++++
pom.xml | 1 +
16 files changed, 616 insertions(+)
diff --git a/action-extension/README.md b/action-extension/README.md
new file mode 100644
index 0000000..6542be0
--- /dev/null
+++ b/action-extension/README.md
@@ -0,0 +1,49 @@
+# Action Extension
+
+This example shows the three places where an action extension can be set in
Apache Struts:
+globally, on a `<package>`, and on a single `<action>`. It covers both which
request URLs reach
+an action and which extension the Struts tags use when they generate a URL to
it.
+
+Requires Apache Struts 7.5.0 or later.
+
+## Run
+
+```bash
+./mvnw -pl action-extension jetty:run
+```
+
+Then open http://localhost:8080/action-extension/
+
+## What is configured
+
+| Layer | Config in `struts.xml` | Action | URL |
+|---|---|---|---|
+| Global | `<constant name="struts.action.extension" value="action"/>` |
`hello` | `/hello.action` |
+| Package | `<package name="legacy" namespace="/legacy" extension="do">` |
`orders` | `/legacy/orders.do` |
+| Action | `<action name="report" extension="">` | `report` | `/legacy/report`
|
+
+An action's extensions are taken from the most specific place that declares
them:
+
+action → package → parent packages → `struts.action.extension`
+
+Every place uses the same format: a comma-separated list. The first entry is
the default, and an
+empty entry means "no extension" (`extension=""`, or `action,,`).
+
+## Generated URLs
+
+`<s:url>`, `<s:a>`, `<s:form>` and the `redirectAction` result build the URL
from the
+**target** action's extensions. The URL keeps the current page's extension
when the target
+accepts it, otherwise it uses the target's first entry. Every list in this
example has a single
+entry, so a link to `orders` from `/legacy/report` comes out as
`/legacy/orders.do`, and a link to
+`hello` from `/legacy/orders.do` comes out as `/hello.action`.
+
+## Wrong extensions
+
+- `/legacy/orders.action` and `/legacy/report.do` reach an action that
declares its own
+ extensions. The `actionExtension` interceptor rejects them and returns the
`bad-extension`
+ result. Without a `bad-extension` result, the response is a 404.
+- `/hello.do` is a plain 404. `hello` declares no extension, so only the
global list applies to
+ it, and `.do` is never mapped to it.
+
+Extensions control which URL is the canonical one for an action. They are not
access control:
+do not use them to hide actions.
diff --git a/action-extension/pom.xml b/action-extension/pom.xml
new file mode 100644
index 0000000..b7b44b9
--- /dev/null
+++ b/action-extension/pom.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+<project
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
https://maven.apache.org/xsd/maven-4.0.0.xsd"
+ xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>org.apache.struts</groupId>
+ <artifactId>struts-examples</artifactId>
+ <version>2.0.0</version>
+ </parent>
+
+ <artifactId>action-extension</artifactId>
+ <name>Action Extension Apache Struts Example Application</name>
+ <description>Shows global, package-level and action-level action
extensions in Apache Struts</description>
+
+ <packaging>war</packaging>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.struts</groupId>
+ <artifactId>struts2-junit-plugin</artifactId>
+ <version>${struts2.version}</version>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-web</artifactId>
+ <version>${spring-web.version}</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <finalName>action-extension</finalName>
+ <plugins>
+ <plugin>
+ <groupId>org.eclipse.jetty</groupId>
+ <artifactId>jetty-maven-plugin</artifactId>
+ <version>${jetty-plugin.version}</version>
+ <configuration>
+ <webApp>
+ <contextPath>/${project.artifactId}</contextPath>
+ </webApp>
+ <stopKey>CTRL+C</stopKey>
+ <stopPort>8999</stopPort>
+ <scan>10</scan>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+</project>
diff --git a/action-extension/src/main/resources/log4j2.xml
b/action-extension/src/main/resources/log4j2.xml
new file mode 100644
index 0000000..b622886
--- /dev/null
+++ b/action-extension/src/main/resources/log4j2.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration>
+ <Appenders>
+ <Console name="STDOUT" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.struts2" level="info"/>
+ <Logger name="org.apache.struts2.helloworld" level="debug"/>
+ <Root level="warn">
+ <AppenderRef ref="STDOUT"/>
+ </Root>
+ </Loggers>
+</Configuration>
\ No newline at end of file
diff --git a/action-extension/src/main/resources/struts.xml
b/action-extension/src/main/resources/struts.xml
new file mode 100644
index 0000000..89a43b1
--- /dev/null
+++ b/action-extension/src/main/resources/struts.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE struts PUBLIC
+ "-//Apache Software Foundation//DTD Struts Configuration 7.5//EN"
+ "https://struts.apache.org/dtds/struts-7.5.dtd">
+<struts>
+ <constant name="struts.enable.DynamicMethodInvocation" value="false"/>
+ <constant name="struts.devMode" value="true"/>
+
+ <!-- Global: actions that declare nothing answer only on .action -->
+ <constant name="struts.action.extension" value="action"/>
+
+ <package name="default" namespace="/" extends="struts-default">
+ <global-results>
+ <result name="bad-extension">/WEB-INF/jsp/badExtension.jsp</result>
+ </global-results>
+
+ <action name="index">
+ <result>/WEB-INF/jsp/index.jsp</result>
+ </action>
+
+ <action name="hello">
+ <result>/WEB-INF/jsp/hello.jsp</result>
+ </action>
+ </package>
+
+ <!-- Package override: every action in this package answers on .do -->
+ <package name="legacy" namespace="/legacy" extends="struts-default"
extension="do">
+ <global-results>
+ <result name="bad-extension">/WEB-INF/jsp/badExtension.jsp</result>
+ </global-results>
+
+ <action name="orders">
+ <result>/WEB-INF/jsp/orders.jsp</result>
+ </action>
+
+ <!-- Action override: an empty extension means no extension at all -->
+ <action name="report" extension="">
+ <result>/WEB-INF/jsp/report.jsp</result>
+ </action>
+ </package>
+</struts>
diff --git a/action-extension/src/main/webapp/WEB-INF/jsp/badExtension.jsp
b/action-extension/src/main/webapp/WEB-INF/jsp/badExtension.jsp
new file mode 100644
index 0000000..8adae6b
--- /dev/null
+++ b/action-extension/src/main/webapp/WEB-INF/jsp/badExtension.jsp
@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8" %>
+<%@ taglib prefix="s" uri="/struts-tags" %>
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>Action Extension - Wrong extension</title>
+</head>
+<body>
+<h1>Wrong extension</h1>
+<p>The request to <code><s:property
value="#request['jakarta.servlet.forward.request_uri']"/></code> was rejected
+ by the <code>actionExtension</code> interceptor. The action exists, but
its declared extensions do not include the one in this URL.</p>
+<p>The interceptor returned the <code>bad-extension</code> result, which this
example maps to this page. Without that result, the response would be a 404.</p>
+<p><a href="<s:url action='index' namespace='/'/>">Back to the start
page</a></p>
+</body>
+</html>
diff --git a/action-extension/src/main/webapp/WEB-INF/jsp/hello.jsp
b/action-extension/src/main/webapp/WEB-INF/jsp/hello.jsp
new file mode 100644
index 0000000..bdebc9a
--- /dev/null
+++ b/action-extension/src/main/webapp/WEB-INF/jsp/hello.jsp
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8" %>
+<%@ taglib prefix="s" uri="/struts-tags" %>
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>Action Extension - Global</title>
+</head>
+<body>
+<h1>Global extension</h1>
+<p>You reached <code>hello</code> in the <code>default</code> package. Neither
the action nor its package declares an extension, so it answers on the global
<code>struts.action.extension</code> value: <code>.action</code>.</p>
+<%@ include file="links.jspf" %>
+<p><a href="<s:url action='index' namespace='/'/>">Back to the start
page</a></p>
+</body>
+</html>
diff --git a/action-extension/src/main/webapp/WEB-INF/jsp/index.jsp
b/action-extension/src/main/webapp/WEB-INF/jsp/index.jsp
new file mode 100644
index 0000000..39a80e0
--- /dev/null
+++ b/action-extension/src/main/webapp/WEB-INF/jsp/index.jsp
@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8" %>
+<%@ taglib prefix="s" uri="/struts-tags" %>
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>Action Extension - Welcome</title>
+</head>
+<body>
+<h1>Action extensions in Apache Struts</h1>
+<p>An action extension can be set in three places. Struts uses the most
specific one: the action, then its package, then parent packages, then the
global <code>struts.action.extension</code> constant. See
<code>struts.xml</code>.</p>
+<p>The wrong-extension links are plain <code><a href></code> links,
because <code><s:url></code> would always fix the extension.</p>
+<ul>
+ <li><code>orders.action</code> and <code>report.do</code> reach an action
that declares its own extensions, so the <code>actionExtension</code>
interceptor rejects them and shows the <code>bad-extension</code> result.</li>
+ <li><code>hello.do</code> is a plain 404. <code>hello</code> declares no
extension, so only the global list (<code>action</code>) applies to it, and
<code>.do</code> is never mapped to it.</li>
+</ul>
+<%@ include file="links.jspf" %>
+<p><a href="<s:url action='index' namespace='/'/>">Back to the start
page</a></p>
+</body>
+</html>
diff --git a/action-extension/src/main/webapp/WEB-INF/jsp/links.jspf
b/action-extension/src/main/webapp/WEB-INF/jsp/links.jspf
new file mode 100644
index 0000000..df66446
--- /dev/null
+++ b/action-extension/src/main/webapp/WEB-INF/jsp/links.jspf
@@ -0,0 +1,28 @@
+<%@ page pageEncoding="UTF-8" %>
+<%@ taglib prefix="s" uri="/struts-tags" %>
+<s:url var="helloUrl" action="hello" namespace="/"/>
+<s:url var="ordersUrl" action="orders" namespace="/legacy"/>
+<s:url var="reportUrl" action="report" namespace="/legacy"/>
+<h2>Generated links</h2>
+<p>Each link is built with <code><s:url></code>, which uses the target
action's extensions: it keeps this page's extension only when the target
accepts it, otherwise it uses the target's first entry.</p>
+<table>
+ <tr><th>Layer</th><th>Link</th><th>Generated URL</th><th>Wrong
extension</th></tr>
+ <tr>
+ <td>Global (<code>struts.action.extension</code>)</td>
+ <td><s:a href="%{#helloUrl}">hello</s:a></td>
+ <td><code><s:property value="#helloUrl"/></code></td>
+ <td><a href="${pageContext.request.contextPath}/hello.do">hello.do</a>
(plain 404)</td>
+ </tr>
+ <tr>
+ <td>Package (<code><package extension="do"></code>)</td>
+ <td><s:a href="%{#ordersUrl}">orders</s:a></td>
+ <td><code><s:property value="#ordersUrl"/></code></td>
+ <td><a
href="${pageContext.request.contextPath}/legacy/orders.action">orders.action</a>
(rejected)</td>
+ </tr>
+ <tr>
+ <td>Action (<code><action extension=""></code>)</td>
+ <td><s:a href="%{#reportUrl}">report</s:a></td>
+ <td><code><s:property value="#reportUrl"/></code></td>
+ <td><a
href="${pageContext.request.contextPath}/legacy/report.do">report.do</a>
(rejected)</td>
+ </tr>
+</table>
diff --git a/action-extension/src/main/webapp/WEB-INF/jsp/orders.jsp
b/action-extension/src/main/webapp/WEB-INF/jsp/orders.jsp
new file mode 100644
index 0000000..e74cb0f
--- /dev/null
+++ b/action-extension/src/main/webapp/WEB-INF/jsp/orders.jsp
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8" %>
+<%@ taglib prefix="s" uri="/struts-tags" %>
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>Action Extension - Package</title>
+</head>
+<body>
+<h1>Package extension</h1>
+<p>You reached <code>orders</code> in the <code>legacy</code> package. The
package declares <code>extension="do"</code>, so every action in it answers on
<code>.do</code> unless the action declares its own.</p>
+<%@ include file="links.jspf" %>
+<p><a href="<s:url action='index' namespace='/'/>">Back to the start
page</a></p>
+</body>
+</html>
diff --git a/action-extension/src/main/webapp/WEB-INF/jsp/report.jsp
b/action-extension/src/main/webapp/WEB-INF/jsp/report.jsp
new file mode 100644
index 0000000..459adcf
--- /dev/null
+++ b/action-extension/src/main/webapp/WEB-INF/jsp/report.jsp
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8" %>
+<%@ taglib prefix="s" uri="/struts-tags" %>
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>Action Extension - Action</title>
+</head>
+<body>
+<h1>Action extension</h1>
+<p>You reached <code>report</code> in the <code>legacy</code> package. The
action declares <code>extension=""</code>, which overrides the package's
<code>do</code>. An empty entry means no extension, so the URL is
<code>/legacy/report</code>.</p>
+<%@ include file="links.jspf" %>
+<p><a href="<s:url action='index' namespace='/'/>">Back to the start
page</a></p>
+</body>
+</html>
diff --git a/action-extension/src/main/webapp/WEB-INF/web.xml
b/action-extension/src/main/webapp/WEB-INF/web.xml
new file mode 100644
index 0000000..80d952b
--- /dev/null
+++ b/action-extension/src/main/webapp/WEB-INF/web.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<web-app id="WebApp_ID" version="6.0"
+ xmlns="https://jakarta.ee/xml/ns/jakartaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd">
+ <display-name>Action Extension Apache Struts Example</display-name>
+ <welcome-file-list>
+ <welcome-file>index.jsp</welcome-file>
+ </welcome-file-list>
+
+ <filter>
+ <filter-name>struts2</filter-name>
+
<filter-class>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter</filter-class>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>struts2</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+
+</web-app>
diff --git a/action-extension/src/main/webapp/index.jsp
b/action-extension/src/main/webapp/index.jsp
new file mode 100644
index 0000000..3a36e86
--- /dev/null
+++ b/action-extension/src/main/webapp/index.jsp
@@ -0,0 +1 @@
+<% response.sendRedirect("index.action"); %>
diff --git
a/action-extension/src/test/java/org/apache/struts_example/ActionExtensionTest.java
b/action-extension/src/test/java/org/apache/struts_example/ActionExtensionTest.java
new file mode 100644
index 0000000..d87691f
--- /dev/null
+++
b/action-extension/src/test/java/org/apache/struts_example/ActionExtensionTest.java
@@ -0,0 +1,90 @@
+/*
+ * 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.
+ */
+package org.apache.struts_example;
+
+import org.apache.struts2.ActionSupport;
+import org.apache.struts2.dispatcher.mapper.ActionMapping;
+import org.apache.struts2.junit.StrutsJUnit4TestCase;
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+
+public class ActionExtensionTest extends StrutsJUnit4TestCase<Object> {
+
+ @Test
+ public void testGlobalExtensionMapsHello() {
+ ActionMapping mapping = getActionMapping("/hello.action");
+
+ assertNotNull(mapping);
+ assertEquals("hello", mapping.getName());
+ assertEquals("/", mapping.getNamespace());
+ assertEquals("action", mapping.getExtension());
+ }
+
+ @Test
+ public void testPackageExtensionMapsOrders() {
+ ActionMapping mapping = getActionMapping("/legacy/orders.do");
+
+ assertNotNull(mapping);
+ assertEquals("orders", mapping.getName());
+ assertEquals("/legacy", mapping.getNamespace());
+ assertEquals("do", mapping.getExtension());
+ }
+
+ @Test
+ public void testActionExtensionMapsReport() {
+ ActionMapping mapping = getActionMapping("/legacy/report");
+
+ assertNotNull(mapping);
+ assertEquals("report", mapping.getName());
+ assertEquals("/legacy", mapping.getNamespace());
+ }
+
+ @Test
+ public void testUndeclaredActionDoesNotClaimDo() {
+ assertNull(getActionMapping("/hello.do"));
+ }
+
+ @Test
+ public void testHelloExecutesOnAction() throws Exception {
+ assertEquals(ActionSupport.SUCCESS,
getActionProxy("/hello.action").execute());
+ }
+
+ @Test
+ public void testOrdersExecutesOnDo() throws Exception {
+ assertEquals(ActionSupport.SUCCESS,
getActionProxy("/legacy/orders.do").execute());
+ }
+
+ @Test
+ public void testReportExecutesWithoutExtension() throws Exception {
+ assertEquals(ActionSupport.SUCCESS,
getActionProxy("/legacy/report").execute());
+ }
+
+ @Test
+ public void testOrdersRejectsActionExtension() throws Exception {
+ assertEquals("bad-extension",
getActionProxy("/legacy/orders.action").execute());
+ }
+
+ @Test
+ public void testReportRejectsDoExtension() throws Exception {
+ assertEquals("bad-extension",
getActionProxy("/legacy/report.do").execute());
+ }
+}
diff --git a/docs/superpowers/plans/2026-11-13-action-extension-example.md
b/docs/superpowers/plans/2026-11-13-action-extension-example.md
new file mode 100644
index 0000000..fbfddd1
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-13-action-extension-example.md
@@ -0,0 +1,162 @@
+# `action-extension` Example Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use
superpowers:subagent-driven-development (recommended) or
superpowers:executing-plans to implement this plan task-by-task. Steps use
checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A new standalone `action-extension` example module that demonstrates
global, package-level and action-level action extensions (Apache Struts 7.5.0,
WW-4164).
+
+**Architecture:** One `struts.xml` with two packages: `default` at `/`, which
uses the global `struts.action.extension=action`, and `legacy` at `/legacy`
with `extension="do"`, which holds one action declaring `extension=""`. The
actions have no classes; they use the default `ActionSupport` and point at JSPs
under `WEB-INF/jsp/`. A `StrutsTestCase` test pins the inbound mapping and the
rejection. A Jetty smoke check covers the outbound links.
+
+**Tech Stack:** Apache Struts 7.5.0, Jakarta Servlet 6 / JSP,
`struts2-junit-plugin`, Jetty Maven plugin.
+
+**Spec:**
`docs/superpowers/specs/2026-11-13-action-extension-example-design.md`
+
+## Global Constraints
+
+- Struts config DOCTYPE: `-//Apache Software Foundation//DTD Struts
Configuration 7.5//EN` / `https://struts.apache.org/dtds/struts-7.5.dtd`.
+- `web.xml` on `web-app_6_0.xsd`, `version="6.0"`; `jakarta.*` only.
+- Call the framework "Apache Struts", never "Struts 2" (this includes
`<display-name>` and the pom `<name>`).
+- Module versions come from the root pom; the module pom declares only
`struts2-junit-plugin` (test) and `spring-web` (test), copied from
`unit-testing/pom.xml`.
+- The README states that extensions are URL canonicalisation, not access
control.
+
+## Review Focus
+
+1. **Welcome URL** `http://localhost:8080/action-extension/`: the global list
has no empty entry, so a `/index` welcome file would not map. A reader opening
the root URL must still land on the index page. Pinned by the Task 2 smoke
check (`curl -L /action-extension/` shows the index).
+2. **Outbound from an extensionless page**: links rendered on `legacy/report`
must still emit `hello.action` and `legacy/orders.do`, not inherit "no
extension". Pinned by the Task 2 smoke check on `report`.
+3. **Outbound from a `.do` page to a global action**: `orders.do` linking to
`hello` must emit `hello.action`. Pinned by the Task 2 smoke check on
`orders.do`.
+4. **Direct JSP access** `/action-extension/WEB-INF/jsp/hello.jsp`: must not
render, because pages live under `WEB-INF`. Pinned by the Task 2 smoke check
(expect 404).
+5. **Undeclared action on a foreign extension** `hello.do`: the reader expects
a 404, not the bad-extension page. Pinned by
`testUndeclaredActionDoesNotClaimDo` (Task 1) and the Task 2 smoke check.
+
+---
+
+### Task 1: Module, configuration and mapping test
+
+**Files:**
+- Create: `action-extension/pom.xml`
+- Create: `action-extension/src/main/resources/struts.xml`
+- Create: `action-extension/src/main/resources/log4j2.xml` (copy of
`helloworld/src/main/resources/log4j2.xml`)
+- Create: `action-extension/src/main/webapp/WEB-INF/web.xml`
+- Create:
`action-extension/src/test/java/org/apache/struts_example/ActionExtensionTest.java`
+- Modify: `pom.xml` (root): add `<module>action-extension</module>` after
`<module>sitemesh3</module>`
+
+**Interfaces:**
+- Produces: action names and results that Task 2's JSPs link to:
+ - namespace `/`: `index` → `/WEB-INF/jsp/index.jsp`, `hello` →
`/WEB-INF/jsp/hello.jsp`
+ - namespace `/legacy`: `orders` → `/WEB-INF/jsp/orders.jsp`, `report` →
`/WEB-INF/jsp/report.jsp`
+ - global result `bad-extension` → `/WEB-INF/jsp/badExtension.jsp` in
**both** packages (`legacy` does not extend `default`; each declares its own
`<global-results>`)
+
+- [ ] **Step 1: Create `action-extension/pom.xml`**
+
+Copy `helloworld/pom.xml` with `artifactId` set to `action-extension`,
`<name>Action Extension Apache Struts Example Application</name>`, a matching
`<description>`, `<finalName>action-extension</finalName>`, and the
`<dependencies>` block from `unit-testing/pom.xml`. Add the module to the root
`pom.xml`.
+
+- [ ] **Step 2: Write the failing test**
+
+`ActionExtensionTest extends org.apache.struts2.junit.StrutsTestCase`, JUnit 4
`@Test` methods, following the style of `unit-testing/.../RegisterTest.java`:
+
+```java
+@Test public void testGlobalExtensionMapsHello() //
getActionMapping("/hello.action"): name "hello", namespace "/", extension
"action"
+@Test public void testPackageExtensionMapsOrders() //
getActionMapping("/legacy/orders.do"): name "orders", namespace "/legacy",
extension "do"
+@Test public void testActionExtensionMapsReport() //
getActionMapping("/legacy/report"): name "report", namespace "/legacy"
+@Test public void testUndeclaredActionDoesNotClaimDo() //
assertNull(getActionMapping("/hello.do"))
+@Test public void testDeclaredExtensionsExecute() //
getActionProxy(uri).execute() == "success" for "/hello.action",
"/legacy/orders.do", "/legacy/report"
+@Test public void testOrdersRejectsActionExtension() //
getActionProxy("/legacy/orders.action").execute() == "bad-extension"
+@Test public void testReportRejectsDoExtension() //
getActionProxy("/legacy/report.do").execute() == "bad-extension"
+```
+
+Create a fresh request between the proxies in `testDeclaredExtensionsExecute`,
or split it into three methods if reusing one request leaks state.
+
+- [ ] **Step 3: Run the test to verify it fails**
+
+Run: `./mvnw -pl action-extension test`
+Expected: FAIL. With no `struts.xml` yet, the mappings are null or the proxies
cannot be created.
+
+- [ ] **Step 4: Write `web.xml` and `struts.xml`**
+
+`web.xml`: copy `helloworld`'s, with `<display-name>Action Extension Apache
Struts Example</display-name>` and `<welcome-file>index.jsp</welcome-file>`
(the top-level redirect page comes in Task 2).
+
+`struts.xml` (the exact structure is the teaching content):
+
+```xml
+<constant name="struts.devMode" value="true"/>
+<constant name="struts.action.extension" value="action"/>
+
+<package name="default" namespace="/" extends="struts-default">
+ <global-results><result
name="bad-extension">/WEB-INF/jsp/badExtension.jsp</result></global-results>
+ <action name="index"><result>/WEB-INF/jsp/index.jsp</result></action>
+ <action name="hello"><result>/WEB-INF/jsp/hello.jsp</result></action>
+</package>
+
+<package name="legacy" namespace="/legacy" extends="struts-default"
extension="do">
+ <global-results><result
name="bad-extension">/WEB-INF/jsp/badExtension.jsp</result></global-results>
+ <action name="orders"><result>/WEB-INF/jsp/orders.jsp</result></action>
+ <action name="report"
extension=""><result>/WEB-INF/jsp/report.jsp</result></action>
+</package>
+```
+
+Each of the three levels gets a one-line XML comment naming it (global /
package override / action override). Keep
`struts.enable.DynamicMethodInvocation=false` as in the other examples.
+
+- [ ] **Step 5: Run the test to verify it passes**
+
+Run: `./mvnw -pl action-extension test`
+Expected: `Tests run: 7, Failures: 0, Errors: 0`. JSP rendering is not
exercised by the mock dispatcher, so missing JSPs do not fail the test.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add pom.xml action-extension
+git commit -m "feat(action-extension): add module with global, package and
action extensions"
+```
+
+### Task 2: Pages, README and outbound smoke check
+
+**Files:**
+- Create: `action-extension/src/main/webapp/index.jsp`: redirects to
`index.action` (`<% response.sendRedirect("index.action"); %>`)
+- Create: `action-extension/src/main/webapp/WEB-INF/jsp/index.jsp`,
`hello.jsp`, `orders.jsp`, `report.jsp`, `badExtension.jsp`
+- Create: `action-extension/README.md`
+
+**Interfaces:**
+- Consumes: the action names, namespaces and results from Task 1.
+
+- [ ] **Step 1: Write the pages**
+
+- A shared link block appears on `WEB-INF/jsp/index.jsp` and on each result
page (inline it or use `<%@ include file="links.jspf" %>`; builder's choice).
For each of `hello` (ns `/`), `orders` (ns `/legacy`) and `report` (ns
`/legacy`), the block has:
+ - an `<s:a>` link built with `<s:url var=... action=... namespace=.../>`,
with the generated URL printed next to it via `<s:property value="#var"/>`;
+ - a plain `<a href="...">` wrong-extension link:
`${pageContext.request.contextPath}/hello.do`, `.../legacy/orders.action`,
`.../legacy/report.do`.
+- Each result page says in one or two sentences which layer it demonstrates
and where that layer is configured.
+- `badExtension.jsp` explains that the `actionExtension` interceptor rejected
the request because the URL's extension is not in the action's declared list.
It shows the requested URI (`${pageContext.request.requestURI}` is the
forwarded JSP path, so use
`${requestScope['jakarta.servlet.forward.request_uri']}`) and links back to
`index.action`.
+- The index page also explains why `hello.do` is a plain 404: `hello` declares
no extension, so only the global list (`action`) applies, and `.do` is never
mapped to it.
+
+- [ ] **Step 2: Write `README.md`**
+
+Contents: one-paragraph purpose; run command `./mvnw -pl action-extension
jetty:run`; URL `http://localhost:8080/action-extension/`; the three-layer
table from the spec; resolution order "action → package → parent packages →
`struts.action.extension`"; list format (comma-separated, first entry is the
default for generated URLs, an empty entry means no extension); a note that a
wrong extension goes to the `bad-extension` result or a 404; a note that this
is URL canonicalisation, not acces [...]
+
+- [ ] **Step 3: Build and run**
+
+Run: `./mvnw -pl action-extension clean package` → `BUILD SUCCESS`.
+Then start `./mvnw -pl action-extension jetty:run` in the background and wait
for `Started Server`.
+
+- [ ] **Step 4: Smoke-check inbound and outbound**
+
+```bash
+B=http://localhost:8080/action-extension
+curl -sL $B/ | grep -q 'hello.action' #
welcome redirect lands on index
+curl -s $B/index.action | grep -oE 'href="[^"]*"' #
expect /action-extension/hello.action, /action-extension/legacy/orders.do,
/action-extension/legacy/report
+curl -s $B/legacy/report | grep -oE 'href="[^"]*"' #
expect the same three generated hrefs
+curl -s $B/legacy/orders.do | grep -oE 'href="[^"]*"' #
expect the same three generated hrefs
+curl -s -o /dev/null -w '%{http_code}\n' $B/hello.do
# 404
+curl -s $B/legacy/orders.action | grep -qi 'rejected' #
bad-extension page
+curl -s $B/legacy/report.do | grep -qi 'rejected' #
bad-extension page
+curl -s -o /dev/null -w '%{http_code}\n' $B/WEB-INF/jsp/hello.jsp
# 404
+```
+
+Expected: every check holds. Stop Jetty afterwards.
+
+- [ ] **Step 5: Full reactor build**
+
+Run: `./mvnw -B clean package` → `BUILD SUCCESS`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add action-extension
+git commit -m "feat(action-extension): add pages and README showing generated
URLs and rejection"
+```
diff --git
a/docs/superpowers/specs/2026-11-13-action-extension-example-design.md
b/docs/superpowers/specs/2026-11-13-action-extension-example-design.md
new file mode 100644
index 0000000..e652759
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-13-action-extension-example-design.md
@@ -0,0 +1,76 @@
+# `action-extension` example — design
+
+- **Feature:** per-package / per-action `extension` attribute, Apache Struts
7.5.0
+ ([WW-4164](https://issues.apache.org/jira/browse/WW-4164))
+- **Date:** 2026-11-13
+
+## Intent
+
+A tutorial-ready example of the three layers of action extension resolution:
the global
+`struts.action.extension`, an override on `<package>`, and an override on
`<action>`. It shows
+both inbound mapping (which URL reaches which action) and outbound URL
generation (tags emit the
+target action's extension), plus what happens on a wrong extension.
+
+## Goals
+
+- New standalone module `action-extension`, registered in the root
`<modules>`, runnable with
+ `./mvnw -pl action-extension jetty:run` at
`http://localhost:8080/action-extension/`.
+- Three layers, each with its own URL prefix:
+
+ | Layer | Config | Action | URL |
+ |---|---|---|---|
+ | Global | `<constant name="struts.action.extension" value="action"/>` |
`/index`, `/hello` | `index.action`, `hello.action` |
+ | Package | `<package name="legacy" namespace="/legacy" extension="do">` |
`/legacy/orders` | `legacy/orders.do` |
+ | Action | `<action name="report" extension="">` inside `legacy` |
`/legacy/report` | `legacy/report` |
+
+- `index.jsp` links to each action with `s:a`, so readers see the generated
URL pick up the
+ target's extension. It also prints the generated URL as text next to each
link.
+- Each layer also gets one "wrong extension" link, written as a plain `<a
href>` because `s:a`
+ would correct the extension:
+ - `legacy/orders.action` and `legacy/report.do` → rejected by the
`actionExtension`
+ interceptor → a mapped `bad-extension` global result (`badExtension.jsp`),
which explains why.
+ - `hello.do` → container 404. `hello` declares no extension, so it never
claims `.do`, and the
+ global list has no empty entry. The page text explains this, because it is
the "undeclared
+ actions follow the global list only" rule.
+- The result pages (`hello.jsp`, `orders.jsp`, `report.jsp`) link back to the
others with `s:a`.
+ This shows that outbound URLs follow the *target's* list, not the current
page's extension.
+- `README.md` with the run command, the URLs, and the resolution order
+ (action → package → parent packages → global).
+- A `StrutsJUnit4TestCase` test pinning the three mappings and the
`bad-extension` rejection.
+
+## Non-goals
+
+- Convention-plugin / annotation extensions (not supported in 7.5.0).
+- REST or other non-default action mappers.
+- Changes to any other module.
+
+## Anti-goals
+
+- Presenting extensions as access control. The README says they are for URL
canonicalisation,
+ not for hiding actions.
+
+## Constraints
+
+- Struts 7 conventions from `CLAUDE.md`: `struts-7.5.dtd`, `web-app_6_0.xsd`,
Jakarta only,
+ "Apache Struts" naming.
+- Any action that takes request parameters needs `@StrutsParameter`. The
example has no form
+ input, so probably none.
+- `actionExtension` is already in the default stacks. Packages extend
`struts-default` and keep
+ the default stack, so the startup "interceptor missing" warning doesn't fire.
+
+## Approaches
+
+- **A. Two packages in separate namespaces (`/` and `/legacy`)**: picked. Each
layer has a
+ distinct URL prefix, which is easiest to follow in a tutorial.
+- **B. Two packages in the same namespace `/`**: shows that extension is set
per package, not per
+ namespace, but the URLs for different layers end up side by side and harder
to tell apart.
+- Scope option B (mapping + generated links + rejection) was picked over
mapping only.
+
+## Left to the builder
+
+- Action classes: one small `ActionSupport` subclass per action, or plain
result-only actions
+ where nothing is computed.
+- Exact page copy and styling (keep it as plain as the other examples).
+- Whether the test drives the mapping through `getActionMapping` /
`executeAction` or asserts
+ through the `ActionMapper` directly. Check that `StrutsJUnit4TestCase`
routes through the
+ configured mapper with the configuration manager. Otherwise the declared
extensions are not seen.
diff --git a/pom.xml b/pom.xml
index 2ddbd0c..2ca05f0 100644
--- a/pom.xml
+++ b/pom.xml
@@ -124,6 +124,7 @@
<module>wildcard-regex</module>
<module>jasperreports</module>
<module>sitemesh3</module>
+ <module>action-extension</module>
</modules>
<dependencyManagement>