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>&lt;a href&gt;</code> links, 
because <code>&lt;s:url&gt;</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>&lt;s:url&gt;</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>&lt;package extension="do"&gt;</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>&lt;action extension=""&gt;</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>

Reply via email to