AP: fix springbootdemo WildFly build and clarify Tomcat vs WildFly docs

robertlazarski · claude · robertlazarski · commit 72e1ed04ecd2 · 2026-04-04T08:46:53.000-10:00
- Update springbootdemo/pom.xml Axis2 versions 2.0.0-SNAPSHOT -&gt; 2.0.1-SNAPSHOT
  so local Maven install resolves correctly
- Fix Tomcat11 guide: context root is / (ROOT deployment), not /axis2-json-api;
  correct all curl example URLs accordingly
- Replace 2-item differences list with a full comparison table in Tomcat11 guide
  covering: context root, deploy method, WildFly-specific files, DataSource
  auto-config exclusion, HTTP/2 config, and JSON format
- Add concise WildFly vs Tomcat differences summary in WildFly guide with link
  to Tomcat11 guide

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/modules/samples/userguide/src/userguide/springbootdemo/pom.xml b/modules/samples/userguide/src/userguide/springbootdemo/pom.xml
@@ -171,18 +171,18 @@
 	<dependency>
 		<groupId>org.apache.axis2</groupId>
 		<artifactId>axis2-kernel</artifactId>
-		<version>2.0.0-SNAPSHOT</version>
+		<version>2.0.1-SNAPSHOT</version>
 	</dependency>
 	<dependency>
 		<groupId>org.apache.axis2</groupId>
 		<artifactId>axis2-transport-http</artifactId>
-		<version>2.0.0-SNAPSHOT</version>
+		<version>2.0.1-SNAPSHOT</version>
 	</dependency>
 	<!-- HTTP/2 Transport for Enterprise Big Data Processing -->
 	<dependency>
 		<groupId>org.apache.axis2</groupId>
 		<artifactId>axis2-transport-h2</artifactId>
-		<version>2.0.0-SNAPSHOT</version>
+		<version>2.0.1-SNAPSHOT</version>
 	</dependency>
 	<!-- HTTP/2 Dependencies -->
 	<dependency>
@@ -193,42 +193,42 @@
 	<dependency>
 		<groupId>org.apache.axis2</groupId>
 		<artifactId>axis2-transport-local</artifactId>
-		<version>2.0.0-SNAPSHOT</version>
+		<version>2.0.1-SNAPSHOT</version>
 	</dependency>
 	<dependency>
 		<groupId>org.apache.axis2</groupId>
 		<artifactId>axis2-json</artifactId>
-		<version>2.0.0-SNAPSHOT</version>
+		<version>2.0.1-SNAPSHOT</version>
 	</dependency>
         <dependency>
             <groupId>org.apache.axis2</groupId>
             <artifactId>axis2-ant-plugin</artifactId>
-	    <version>2.0.0-SNAPSHOT</version>
+	    <version>2.0.1-SNAPSHOT</version>
         </dependency>
         <dependency>
             <groupId>org.apache.axis2</groupId>
             <artifactId>axis2-adb</artifactId>
-	    <version>2.0.0-SNAPSHOT</version>
+	    <version>2.0.1-SNAPSHOT</version>
         </dependency>
         <dependency>
             <groupId>org.apache.axis2</groupId>
             <artifactId>axis2-java2wsdl</artifactId>
-	    <version>2.0.0-SNAPSHOT</version>
+	    <version>2.0.1-SNAPSHOT</version>
         </dependency>
         <dependency>
             <groupId>org.apache.axis2</groupId>
             <artifactId>axis2-metadata</artifactId>
-	    <version>2.0.0-SNAPSHOT</version>
+	    <version>2.0.1-SNAPSHOT</version>
         </dependency>
         <dependency>
             <groupId>org.apache.axis2</groupId>
             <artifactId>axis2-spring</artifactId>
-	    <version>2.0.0-SNAPSHOT</version>
+	    <version>2.0.1-SNAPSHOT</version>
         </dependency>
         <dependency>
             <groupId>org.apache.axis2</groupId>
             <artifactId>axis2-jaxws</artifactId>
-	    <version>2.0.0-SNAPSHOT</version>
+	    <version>2.0.1-SNAPSHOT</version>
         </dependency>
         <dependency>
             <groupId>org.apache.neethi</groupId>
diff --git a/src/site/xdoc/docs/json-springboot-tomcat11-userguide.xml b/src/site/xdoc/docs/json-springboot-tomcat11-userguide.xml
@@ -74,18 +74,41 @@ prefix the subject of the mail with [Axis2].</p>
 
 <p>This guide is based on the
 <a href="json-springboot-userguide.html">Apache Axis2 JSON and REST with Spring Boot 3 User's Guide</a>,
-which targets WildFly 32. The code and configuration are identical except for two points:</p>
-
-<ol>
-<li><strong>No WildFly-specific deployment descriptors:</strong> The files
-<code>src/main/webapp/WEB-INF/jboss-deployment-structure.xml</code> and
-<code>src/main/webapp/WEB-INF/jboss-web.xml</code> are WildFly-only and must
-<em>not</em> be present in the Tomcat deployment. The
-<code>springbootdemo-tomcat11</code> sample directory does not include these files.</li>
-<li><strong>HTTP/2 requires Tomcat native (APR/NIO2) or Java 9+ ALPN:</strong>
-Tomcat 11 supports HTTP/2 via NIO2 with Java 9+ ALPN — no native library required.
-See the <a href="#tomcat11-http2">Enabling HTTP/2 on Tomcat 11</a> section below.</li>
-</ol>
+which targets WildFly 32. The following table summarises all differences:</p>
+
+<table border="1" cellpadding="4">
+<tr><th>Aspect</th><th>WildFly 32</th><th>Tomcat 11</th></tr>
+<tr>
+  <td><strong>Context root</strong></td>
+  <td><code>/axis2-json-api</code> (WAR name becomes context root automatically)</td>
+  <td><code>/</code> (deployed into <code>webapps/ROOT/</code>); base URL is <code>http://localhost:8080/services/...</code></td>
+</tr>
+<tr>
+  <td><strong>Deploy method</strong></td>
+  <td>Copy WAR directory to <code>standalone/deployments/</code>, then <code>touch axis2-json-api.war.dodeploy</code></td>
+  <td><code>cp -r target/deploy/axis2-json-api.war/* $CATALINA_HOME/webapps/ROOT/</code> then start Tomcat</td>
+</tr>
+<tr>
+  <td><strong>WildFly-specific files</strong></td>
+  <td><code>WEB-INF/jboss-deployment-structure.xml</code>, <code>WEB-INF/jboss-web.xml</code> required</td>
+  <td>These files must <em>not</em> be present; <code>springbootdemo-tomcat11</code> omits them</td>
+</tr>
+<tr>
+  <td><strong>DataSource auto-configuration</strong></td>
+  <td>WildFly's JPA subsystem suppresses Spring Boot's DataSource auto-config automatically</td>
+  <td>Must exclude explicitly in <code>@SpringBootApplication</code>:
+  <code>exclude={DataSourceAutoConfiguration.class, DataSourceTransactionManagerAutoConfiguration.class, HibernateJpaAutoConfiguration.class}</code></td>
+</tr>
+<tr>
+  <td><strong>HTTP/2 configuration</strong></td>
+  <td>Configured via WildFly subsystem</td>
+  <td>Requires <code>&lt;UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol"/&gt;</code> in <code>server.xml</code> HTTPS connector; Java 9+ ALPN, no native library needed</td>
+</tr>
+<tr>
+  <td><strong>JSON request format</strong></td>
+  <td colspan="2">Identical for both servers: <code>{"methodName":[{"paramName":{...}}]}</code></td>
+</tr>
+</table>
 
 <p>All sample source code for this guide is located in
 the <b>"modules/samples/userguide/src/springbootdemo-tomcat11"</b> directory of <a
@@ -204,7 +227,9 @@ tail -f $CATALINA_HOME/logs/catalina.out
 </pre>
 
 <p>You should see the Spring Boot application context starting and Axis2 servlet registering
-without errors. The context path will be <code>/axis2-json-api</code> (matching the WAR filename).</p>
+without errors. Because the contents are deployed into <code>webapps/ROOT/</code>, the context
+root is <code>/</code> — service URLs begin with <code>http://localhost:8080/services/...</code>,
+<em>not</em> <code>/axis2-json-api/services/...</code> as on WildFly.</p>
 
 <h2>Getting Started</h2>
 
@@ -406,7 +431,7 @@ sender configuration to your axis2.xml file:</p>
 Invoking the client for a login that returns a token can be done as follows:
 </p>
 <pre>
-curl -v -H "Content-Type: application/json" -X POST --data @/home/myuser/login.dat http://localhost:8080/axis2-json-api/services/loginService
+curl -v -H "Content-Type: application/json" -X POST --data @/home/myuser/login.dat http://localhost:8080/services/loginService
 </pre>
 <p>
 Where the contents of /home/myuser/login.dat are:
@@ -425,7 +450,7 @@ Invoking the client for a Test Service that validates a sample token can be done
 follows:
 </p>
 <pre>
-curl -v -H "Authorization: Bearer 95104Rn2I2oEATfuI90N" -H "Content-Type: application/json" -X POST --data @/home/myuser/test.dat http://localhost:8080/axis2-json-api/services/testws'
+curl -v -H "Authorization: Bearer 95104Rn2I2oEATfuI90N" -H "Content-Type: application/json" -X POST --data @/home/myuser/test.dat http://localhost:8080/services/testws'
 </pre>
 <p>
 Where the contents of /home/myuser/test.dat are below. arg0 is a var name
@@ -455,7 +480,7 @@ curl -v -H "Authorization: Bearer 95104Rn2I2oEATfuI90N" \
      -H "Content-Type: application/json" \
      -X POST \
      --data @/home/myuser/small_dataset.dat \
-     https://localhost:8443/axis2-json-api/services/BigDataH2Service
+     https://localhost:8443/services/BigDataH2Service
 </pre>
 
 <p>Where the contents of /home/myuser/small_dataset.dat are:</p>
@@ -479,7 +504,7 @@ curl -v -H "Authorization: Bearer 95104Rn2I2oEATfuI90N" \
      -H "Content-Type: application/json" \
      -X POST \
      --data @/home/myuser/medium_dataset.dat \
-     https://localhost:8443/axis2-json-api/services/BigDataH2Service
+     https://localhost:8443/services/BigDataH2Service
 </pre>
 
 <p>Where the contents of /home/myuser/medium_dataset.dat are:</p>
@@ -503,7 +528,7 @@ curl -v -H "Authorization: Bearer 95104Rn2I2oEATfuI90N" \
      -H "Content-Type: application/json" \
      -X POST \
      --data @/home/myuser/large_dataset.dat \
-     https://localhost:8443/axis2-json-api/services/BigDataH2Service
+     https://localhost:8443/services/BigDataH2Service
 </pre>
 
 <p>Where the contents of /home/myuser/large_dataset.dat are:</p>
diff --git a/src/site/xdoc/docs/json-springboot-userguide.xml b/src/site/xdoc/docs/json-springboot-userguide.xml
@@ -131,12 +131,24 @@ the <b>"modules/samples/userguide/src/springbootdemo"</b> directory of <a
 href="../download.cgi">Axis2 standard binary
 distribution</a>.</p>
 <p>
-This quide supplies a pom.xml for building an exploded WAR with Spring Boot 3 - 
-however this WAR does not have an embedded web server such as Tomcat. 
+This guide supplies a pom.xml for building an exploded WAR with Spring Boot 3 —
+this WAR does not have an embedded web server and must be deployed to an external application server.
 </p>
 <p>
-The testing was carried out on Wildfly 32 with Jakarta, by installing the WAR in its app server. 
+The testing was carried out on WildFly 32 with Jakarta, by installing the WAR in its app server.
+For the equivalent guide targeting Apache Tomcat 11, see the
+<a href="json-springboot-tomcat11-userguide.html">Tomcat 11 User's Guide</a>.
+The key differences between the two deployments are:
 </p>
+<ul>
+<li><strong>Context root:</strong> On WildFly the WAR name becomes the context root (<code>/axis2-json-api</code>);
+on Tomcat 11 (ROOT deployment) the context root is <code>/</code> and service URLs omit the <code>/axis2-json-api</code> prefix.</li>
+<li><strong>Deploy trigger:</strong> WildFly requires a <code>.dodeploy</code> marker file; Tomcat uses <code>cp -r</code> to <code>webapps/ROOT/</code>.</li>
+<li><strong>WildFly-specific files:</strong> <code>jboss-deployment-structure.xml</code> and <code>jboss-web.xml</code> are required here but absent from the Tomcat variant.</li>
+<li><strong>DataSource auto-config:</strong> WildFly suppresses Spring Boot's DataSource auto-configuration automatically;
+Tomcat requires explicit exclusion in <code>@SpringBootApplication</code>.</li>
+<li><strong>JSON request format:</strong> Identical for both — <code>{"methodName":[{"paramName":{...}}]}</code>.</li>
+</ul>
 <p>Please deploy the result of the maven build via 'mvn clean install', axis2-json-api.war, into your servlet container and ensure that it installs without any errors.</p>
 
 <h2>Creating secure Web Services</h2>
