This is an automated email from the ASF dual-hosted git repository. robertlazarski pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/axis-axis2-java-core.git
commit 3663bad32ad68227def6c1d5b0fd0b19c00fceb9 Author: Robert Lazarski <[email protected]> AuthorDate: Wed May 13 10:31:01 2026 -1000 docs: Update Spring Boot starter to document embedded Tomcat support The starter previously stated "Embedded Not Supported". Embedded Tomcat now works via the "embedded" Maven profile with -Daxis2.repo pointing to the exploded WAR. Changes: - spring-boot-starter.xml: Replaced "WAR Only" section with a deployment mode table (external WAR vs embedded Tomcat), added embedded Tomcat instructions with mvn spring-boot:run commands, documented dev-insecure profile and sample login credentials - toc.xml: Updated "WAR Only — Embedded Not Supported" to "WAR + Embedded Tomcat" - installationguide.xml.vm: Updated callout to mention both WAR and embedded deployment Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> --- src/site/xdoc/docs/installationguide.xml.vm | 8 +-- src/site/xdoc/docs/spring-boot-starter.xml | 79 +++++++++++++++++++++++------ src/site/xdoc/docs/toc.xml | 2 +- 3 files changed, 69 insertions(+), 20 deletions(-) diff --git a/src/site/xdoc/docs/installationguide.xml.vm b/src/site/xdoc/docs/installationguide.xml.vm index f80087eb1d..0f40ac959d 100644 --- a/src/site/xdoc/docs/installationguide.xml.vm +++ b/src/site/xdoc/docs/installationguide.xml.vm @@ -32,10 +32,10 @@ <div style="background-color: #e8f5e8; border: 1px solid #4CAF50; padding: 10px; margin: 10px 0;"> <strong>Using Spring Boot?</strong> For new projects, the <a href="spring-boot-starter.html">Spring Boot Starter</a> is the -recommended way to deploy Axis2 services. One Maven dependency, no -manual WAR assembly, and full support for JSON-RPC, OpenAPI, HTTP/2, -and MCP. The guide below covers the traditional standalone and servlet -container installation methods. +recommended way to deploy Axis2 services. Supports both WAR deployment +(Tomcat 11, WildFly 32+) and embedded Tomcat for local development, +with full JSON-RPC, OpenAPI, HTTP/2, and MCP support. +The guide below covers the traditional standalone installation methods. </div> <p>This document provides information on Axis2 distribution diff --git a/src/site/xdoc/docs/spring-boot-starter.xml b/src/site/xdoc/docs/spring-boot-starter.xml index cb9facfb12..32175aac8c 100644 --- a/src/site/xdoc/docs/spring-boot-starter.xml +++ b/src/site/xdoc/docs/spring-boot-starter.xml @@ -56,26 +56,75 @@ for details and rationale.</p> <!-- ============================================================ --> <a name="deployment_model"/> -<h2>0. Deployment Model (WAR Only)</h2> +<h2>0. Deployment Model</h2> -<p>This starter supports <strong>WAR deployment to an external servlet -container</strong> — the same deployment model used by most organizations running -Axis2 in production. Your Spring Boot application must extend -<code>SpringBootServletInitializer</code> and be packaged as a WAR.</p> +<p>Axis2 supports two Spring Boot deployment modes:</p> -<p><strong>Spring Boot embedded Tomcat (<code>java -jar</code>) is not supported.</strong></p> +<table border="1"> +<tr><th>Mode</th><th>How</th><th>Use Case</th></tr> +<tr> + <td><strong>External container (WAR)</strong></td> + <td>Package as WAR, deploy to Tomcat 11 or WildFly 32+</td> + <td>Production — the recommended deployment model</td> +</tr> +<tr> + <td><strong>Embedded Tomcat</strong></td> + <td><code>mvn spring-boot:run -Pembedded</code></td> + <td>Local development and testing</td> +</tr> +</table> -<h3>Why not embedded?</h3> +<h3>External container (production)</h3> + +<p>For production, deploy as a WAR to an external servlet container. +Your Spring Boot application must extend +<code>SpringBootServletInitializer</code> and be packaged as a WAR. +External containers provide operational advantages for long-running +Axis2 deployments:</p> + +<ul> +<li>Container-managed TLS, thread pools, and connection pools</li> +<li>Hot-redeploy via exploded WAR without JVM restart</li> +<li>Central certificate management (Tomcat's <code>server.xml</code>, WildFly's Elytron)</li> +<li>HTTP/2 with ALPN (via container connector, not application code)</li> +</ul> + +<h3>Embedded Tomcat (development)</h3> + +<p>For local development and testing, the sample application supports +Spring Boot's embedded Tomcat via a Maven profile. Axis2's +<code>WarBasedAxisConfigurator</code> requires a filesystem layout +(<code>WEB-INF/conf/axis2.xml</code>, <code>WEB-INF/services/*.aar</code>, +<code>WEB-INF/modules/*.mar</code>) that embedded Tomcat does not +provide from its temp docbase. The <code>-Daxis2.repo</code> system +property tells the configurator where to find the exploded WAR +from the build:</p> + +<pre> +# Build first (creates the exploded WAR with services and modules) +mvn clean install -DskipTests + +# Run with embedded Tomcat +mvn spring-boot:run -Pembedded \ + -Dspring-boot.run.arguments="--server.port=9090" \ + -Dspring-boot.run.jvmArguments="-Daxis2.repo=target/deploy/axis2-json-api/WEB-INF" +</pre> + +<p>For local testing without JWT authentication, activate the +<code>dev-insecure</code> profile (bypasses auth for all +<code>/services/*</code> requests — <strong>never use in +production</strong>):</p> + +<pre> +mvn spring-boot:run -Pembedded \ + -Dspring-boot.run.arguments="--server.port=9090 --spring.profiles.active=dev-insecure" \ + -Dspring-boot.run.jvmArguments="-Daxis2.repo=target/deploy/axis2-json-api/WEB-INF" +</pre> -<p>Axis2's <code>WarBasedAxisConfigurator</code> requires a real filesystem layout: -<code>WEB-INF/conf/axis2.xml</code>, <code>WEB-INF/services/*.aar</code>, and -<code>WEB-INF/modules/*.mar</code>. An embedded Spring Boot application runs from -a fat JAR with no exploded WAR directory. Supporting this would require runtime -classpath scanning for <code>.aar</code> files, temp directory staging, and a -new configurator implementation — work that is planned but not yet complete.</p> +<p>The sample login service accepts hardcoded credentials for testing: +<code>[email protected]</code> / <code>userguide</code>.</p> -<p>Additionally, external containers provide operational advantages for the -long-running, stateful service deployments typical of Axis2 workloads:</p> +<p>For production, external containers remain the recommended deployment:</p> <ul> <li>Container-managed thread pools, connection pools, and monitoring (Actuator/Micrometer)</li> diff --git a/src/site/xdoc/docs/toc.xml b/src/site/xdoc/docs/toc.xml index 37158a1063..29f6c60e11 100644 --- a/src/site/xdoc/docs/toc.xml +++ b/src/site/xdoc/docs/toc.xml @@ -81,7 +81,7 @@ Administrator's Guide</a></li> <li><a href="spring.html">Spring Guide</a></li> <li><a href="spring-boot-starter.html">Spring Boot Starter</a> <ul> -<li>12a.0 <a href="spring-boot-starter.html#deployment_model">Deployment Model (WAR Only — Embedded Not Supported)</a></li> +<li>12a.0 <a href="spring-boot-starter.html#deployment_model">Deployment Model (WAR + Embedded Tomcat)</a></li> <li>12a.1 <a href="spring-boot-starter.html#quickstart">Quick Start (Single Dependency)</a></li> <li>12a.2 <a href="spring-boot-starter.html#how_axisservlet_works">How AxisServlet Works (SOAP vs JSON)</a></li> <li>12a.3 <a href="spring-boot-starter.html#properties">Configuration Properties</a></li>
