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 deaaeaafec5be5d8d845e523717b436658cd38d9 Author: Robert Lazarski <[email protected]> AuthorDate: Sun Apr 19 18:46:49 2026 -1000 AXIS2-6103 Update HTTP/2 documentation and sample axis2.xml configuration Consolidate HTTP/2 integration guides, update Spring Boot starter docs, and configure streaming JSON formatter in sample axis2.xml. --- .../resources-axis2/conf/axis2.xml | 7 +- src/site/xdoc/docs/http2-integration-guide.xml | 165 ++++++- src/site/xdoc/docs/http2-transport-additions.xml | 206 +------- .../docs/openapi-rest-advanced-http2-userguide.xml | 359 -------------- src/site/xdoc/docs/spring-boot-starter.xml | 39 ++ .../xdoc/docs/tomcat-http2-integration-guide.xml | 230 --------- .../xdoc/docs/wildfly-http2-integration-guide.xml | 529 +-------------------- src/site/xdoc/index.xml | 7 + 8 files changed, 228 insertions(+), 1314 deletions(-) diff --git a/modules/samples/userguide/src/userguide/springbootdemo-tomcat11/resources-axis2/conf/axis2.xml b/modules/samples/userguide/src/userguide/springbootdemo-tomcat11/resources-axis2/conf/axis2.xml index b0f955b614..943d74bbeb 100644 --- a/modules/samples/userguide/src/userguide/springbootdemo-tomcat11/resources-axis2/conf/axis2.xml +++ b/modules/samples/userguide/src/userguide/springbootdemo-tomcat11/resources-axis2/conf/axis2.xml @@ -175,8 +175,13 @@ class="org.apache.axis2.kernel.http.SOAPMessageFormatter"/> <messageFormatter contentType="application/soap+xml" class="org.apache.axis2.kernel.http.SOAPMessageFormatter"/> + <!-- FieldFilteringMessageFormatter wraps MoshiStreamingMessageFormatter: + - Streams response in 64KB chunks (FlushingOutputStream) for HTTP/2 + - Supports ?fields=a,b,c query parameter for response field selection + - Zero overhead when no fields parameter is present + See: json-streaming-formatter.html --> <messageFormatter contentType="application/json" - class="org.apache.axis2.json.moshi.JsonFormatter"/> + class="org.apache.axis2.json.streaming.FieldFilteringMessageFormatter"/> </messageFormatters> <!-- ================================================= --> diff --git a/src/site/xdoc/docs/http2-integration-guide.xml b/src/site/xdoc/docs/http2-integration-guide.xml index 4e72f1c50b..11cadc8aaf 100644 --- a/src/site/xdoc/docs/http2-integration-guide.xml +++ b/src/site/xdoc/docs/http2-integration-guide.xml @@ -35,12 +35,134 @@ configuration that provides enhanced performance through cooperative integration with Undertow. </div> +<div style="background-color: #f0f8ff; border: 1px solid #0066cc; padding: 15px; margin: 15px 0;"> +<h3>Quick start — pick your path</h3> +<ul> + <li><strong>Just want the config?</strong> → + <a href="axis2-http2-simplified-example.html">2 parameters in axis2.xml</a></li> + <li><strong>Streaming large responses?</strong> → + <a href="json-streaming-formatter.html">Streaming JSON Formatter</a> + (64 KB flush + <code>?fields=</code> field selection)</li> + <li><strong>WildFly?</strong> → + <a href="wildfly-http2-integration-guide.html">WildFly HTTP/2 guide</a> + | <strong>Tomcat?</strong> → + <a href="tomcat-http2-integration-guide.html">Tomcat HTTP/2 guide</a></li> + <li><strong>Why is Axis2 different?</strong> → + <a href="#How_Axis2_HTTP2_Differs_From_Other_Frameworks">framework comparison</a> (below)</li> +</ul> +</div> + <h2>Overview</h2> -<p>This document provides a comprehensive staged migration plan for implementing <strong>dual-protocol HTTP/2 support</strong> -in Apache Axis2/Java using Apache HttpComponents 5.x. The architecture supports <strong>both HTTP/1.1 and HTTP/2 independently</strong>, -allowing selection of either protocol but not both simultaneously. This approach is specifically designed for enterprise -applications that process large JSON payloads (50MB+) within memory-constrained environments (2GB heap).</p> +<p>Apache Axis2/Java has <strong>native HTTP/2 support</strong> via a dedicated +transport module (<code>modules/transport-h2</code>) built on Apache +HttpComponents 5.x. The architecture supports <strong>both HTTP/1.1 and +HTTP/2 as independent transport implementations</strong>, with runtime +protocol selection and automatic fallback. HTTP/2 awareness extends +into the JSON serialization pipeline — streaming formatters flush +every 64 KB, converting buffered responses into HTTP/2 DATA frames +during serialization rather than after. This is designed for +enterprise applications that process large JSON payloads (50MB+).</p> + +<p><em>Note: sections below titled "Phase" or "Proposed" reflect the +original design process and are retained for architectural context. +The implementation is complete — see +<code>modules/transport-h2</code> and +<code>org.apache.axis2.json.streaming</code>.</em></p> + +<h2>How Axis2 HTTP/2 Differs From Other Frameworks</h2> + +<p>Most web service frameworks treat HTTP/2 as a transparent transport +upgrade — the servlet container (Tomcat, Undertow, Netty) negotiates +HTTP/2 via ALPN, and the framework's serialization layer is unaware of +the underlying protocol. The response is fully buffered in memory before +being handed to the container, which then splits it into HTTP/2 DATA +frames. This means a 50MB JSON response is buffered as a single 50MB +byte array regardless of whether the wire protocol is HTTP/1.1 or +HTTP/2.</p> + +<p>Axis2/Java takes a fundamentally different approach: +<strong>HTTP/2 awareness is built into the serialization pipeline +itself</strong>, not just the transport layer.</p> + +<ul> + <li><strong>Dedicated HTTP/2 transport module</strong> + (<code>modules/transport-h2</code>) — a standalone module with + ALPN protocol negotiation + (<code>ALPNProtocolSelector</code>), per-stream flow control + (<code>H2FlowControlManager</code>, + <code>ProgressiveFlowControl</code>), adaptive buffering + (<code>AdaptiveBufferManager</code>), compression optimization + (<code>CompressionOptimizer</code>), and HTTP/1.1 fallback + (<code>H2FallbackManager</code>). This is not a wrapper around + the servlet container's HTTP/2 — it is an independent + implementation using Apache HttpComponents 5.x.</li> + <li><strong>Streaming JSON formatters</strong> + (<code>MoshiStreamingMessageFormatter</code>, + <code>JSONStreamingMessageFormatter</code>) — flush every 64 KB + via <code>FlushingOutputStream</code>, converting a single + buffered response into a stream of HTTP/2 DATA frames during + serialization. Non-selected fields are never serialized when + field filtering is active + (<code>FieldFilteringMessageFormatter</code>). See + <a href="json-streaming-formatter.html">Streaming JSON Formatter</a>.</li> + <li><strong>C parity</strong> — the same architecture exists in + Axis2/C via Apache httpd <code>mod_h2</code> with + <code>ap_rflush()</code> in the message formatter. Both + implementations use the same 64 KB flush interval, producing + identical HTTP/2 DATA frame patterns from both C and Java + endpoints.</li> +</ul> + +<p>For comparison with other frameworks:</p> + +<table border="1"> + <tr> + <th>Framework</th> + <th>HTTP/2 approach</th> + <th>Serialization-layer awareness</th> + <th>Streaming during serialization</th> + </tr> + <tr> + <td>Spring MVC / Spring WebFlux</td> + <td>Servlet container handles HTTP/2 transparently</td> + <td>No — ResponseEntity buffers in full</td> + <td>WebFlux reactive streams possible, but not integrated into message formatters</td> + </tr> + <tr> + <td>JAX-RS (Jersey, RESTEasy)</td> + <td>Servlet container handles HTTP/2 transparently</td> + <td>No — MessageBodyWriter buffers in full by default</td> + <td>StreamingOutput possible but manual</td> + </tr> + <tr> + <td>gRPC</td> + <td>Mandatory HTTP/2 (the protocol is built on it)</td> + <td>Yes — protobuf serialization is streaming-native</td> + <td>Yes — but gRPC is a protocol, not an add-on</td> + </tr> + <tr> + <td>Django REST Framework</td> + <td>ASGI server handles HTTP/2; framework is oblivious</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td><strong>Apache Axis2/Java</strong></td> + <td><strong>Dedicated transport-h2 module + ALPN negotiation + flow control</strong></td> + <td><strong>Yes — FlushingOutputStream in the JSON formatter pipeline</strong></td> + <td><strong>Yes — 64 KB incremental flush, field filtering during serialization, C/Java parity</strong></td> + </tr> +</table> + +<p>The practical impact: a 50MB Axis2 JSON response flows to the client +in ~780 HTTP/2 DATA frames as serialization progresses, with the first +frame arriving within milliseconds of the first serialized field. A +50MB Spring MVC response arrives as a single burst after the entire +object graph is serialized. For large payloads behind reverse proxies +(nginx, AWS ALB/NLB), the Axis2 approach prevents 502 Bad Gateway +timeouts because the proxy sees continuous data flow rather than a long +silence followed by a large write.</p> <h2>Architecture Strategy: Dual-Protocol Design</h2> @@ -54,7 +176,7 @@ applications that process large JSON payloads (50MB+) within memory-constrained <li><strong>Future Maintenance</strong>: Each protocol can evolve independently</li> </ul> -<h3>Proposed Module Structure</h3> +<h3>Module Structure</h3> <pre> modules/ @@ -292,27 +414,22 @@ moshiMemoryOptimizationThreshold = 52428800 (50MB memory optimization) </li> </ol> -<h2>Migration Strategy</h2> - -<h3>Phase 1: Parallel Deployment</h3> -<ol> - <li>Deploy both HTTP/1.1 and HTTP/2 transports</li> - <li>Test HTTP/2 with non-critical services first</li> - <li>Monitor performance and memory usage</li> -</ol> - -<h3>Phase 2: Gradual Migration</h3> -<ol> - <li>Migrate high-volume services to HTTP/2</li> - <li>Focus on services with large JSON payloads (10MB+)</li> - <li>Measure performance improvements</li> -</ol> +<h2>Recommended Adoption Path</h2> -<h3>Phase 3: Full Migration</h3> +<p>HTTP/2 and HTTP/1.1 coexist as independent transport implementations. +A typical rollout:</p> <ol> - <li>Migrate remaining services to HTTP/2</li> - <li>Consider deprecating HTTP/1.1 transport</li> - <li>Optimize HTTP/2 configuration based on usage patterns</li> + <li><strong>Start with high-payload services</strong> — services returning + 10MB+ JSON responses benefit most from streaming (FlushingOutputStream + prevents reverse proxy timeouts).</li> + <li><strong>Enable globally</strong> — once validated, switch the + <code>axis2.xml</code> formatter to + <code>FieldFilteringMessageFormatter</code> (wraps the streaming + Moshi formatter). All services benefit; small responses have zero + overhead.</li> + <li><strong>HTTP/1.1 fallback remains available</strong> — the original + transport is unchanged and can be restored by reverting the + <code>axis2.xml</code> formatter class.</li> </ol> <h2>Security Considerations</h2> diff --git a/src/site/xdoc/docs/http2-transport-additions.xml b/src/site/xdoc/docs/http2-transport-additions.xml index 71f83263d6..3ad0fd8bca 100644 --- a/src/site/xdoc/docs/http2-transport-additions.xml +++ b/src/site/xdoc/docs/http2-transport-additions.xml @@ -268,43 +268,15 @@ progressive flow control that adapts to network conditions:</p> <parameter name="protocolNegotiationTimeout">5000</parameter> </pre> -<h3>Server Push Capabilities</h3> +<h3>Server Push</h3> -<p>HTTP/2 server push allows servers to proactively send resources to clients before they are requested. -However, for web service APIs and JSON REST endpoints, server push is typically disabled as it provides -limited benefits and can increase complexity.</p> - -<p><strong>When Server Push is Useful:</strong></p> -<ul> - <li>Web applications serving HTML with predictable resource dependencies (CSS, JS, images)</li> - <li>Content delivery networks (CDNs) pushing static assets</li> - <li>Applications where the server can predict client resource needs</li> -</ul> - -<p><strong>Why Server Push is Disabled for Web Services:</strong></p> -<ul> - <li><strong>API Pattern Mismatch:</strong> REST APIs typically follow request-response patterns</li> - <li><strong>Unpredictable Payloads:</strong> Server cannot predict what additional resources a JSON client will need</li> - <li><strong>Client Diversity:</strong> API clients (mobile apps, services, curl) don't benefit from pushed resources</li> - <li><strong>Cache Complexity:</strong> Pushed resources can interfere with client-side caching strategies</li> - <li><strong>Bandwidth Waste:</strong> Pushing unwanted resources wastes bandwidth, especially for large JSON payloads</li> -</ul> - -<p><strong>Configuration:</strong></p> +<p>Server push is <strong>disabled by default</strong> — REST/JSON APIs follow +request-response patterns where push provides no benefit. Enable only +for web-app use cases with predictable resource dependencies:</p> <pre> -<!-- Server push disabled by default (recommended for web services) --> -<parameter name="serverPushEnabled">false</parameter> - -<!-- If enabled for special use cases --> -<parameter name="serverPushEnabled">true</parameter> -<parameter name="pushPromiseTimeout">5000</parameter> -<parameter name="maxPushedStreams">10</parameter> +<parameter name="serverPushEnabled">false</parameter> <!-- default --> </pre> -<p><strong>Implementation Note:</strong> The Axis2 HTTP/2 transport disables server push by default in all -configuration profiles (standard, multiplexing, streaming) as it's optimized for JSON API and web service -usage patterns rather than web application resource delivery.</p> - <h3>Service-Level HTTP/2 Configuration</h3> <p>Individual services can specify HTTP/2 preferences in their services.xml:</p> @@ -569,171 +541,11 @@ set the cached HTTP/2 client using the CACHED_HTTP2_ASYNC_CLIENT property before <li><strong>Fallback Handling</strong>: Automatic fallback to HTTP/1.1 if HTTP/2 negotiation fails</li> </ul> -<h3>SSL Troubleshooting for HTTP/2</h3> - -<p>Common SSL configuration issues with HTTP/2:</p> - -<h4>ALPN Not Supported</h4> -<pre> -Error: ALPN not supported in current environment -Solution: Ensure Java 8u251+ or Java 11+ with ALPN support -</pre> - -<h4>TLS Version Mismatch</h4> -<pre> -Error: HTTP/2 requires TLS 1.2+ -Solution: Configure SSL context with TLS 1.2 or 1.3: -SSLContext sslContext = SSLContext.getInstance("TLSv1.3"); -</pre> - -<h4>Certificate Validation Failures</h4> -<pre> -Error: Certificate path validation failed -Solution: Add certificates to trust store or configure custom trust manager -</pre> - -<h4>Connection Manager Not Started</h4> -<pre> -Error: IllegalStateException - Request cannot be executed -Solution: Always start the async client: -httpAsyncClient.start(); -</pre> - -<h3>SOAP Support and Performance Expectations</h3> - -<p><strong>Current Status:</strong> HTTP/2 transport provides <strong>basic SOAP compatibility</strong> with limited performance benefits.</p> - -<h4>SOAP Over HTTP/2 Limitations</h4> - -<p>SOAP services can use HTTP/2 transport, but benefits are significantly limited compared to JSON APIs:</p> - -<table border="1"> -<tr><th>Aspect</th><th>JSON APIs</th><th>SOAP Services</th><th>HTTP/2 Benefit</th></tr> -<tr><td><strong>Protocol Efficiency</strong></td><td>Binary JSON + HPACK</td><td>Verbose XML + HPACK</td><td>High vs Minimal</td></tr> -<tr><td><strong>Payload Compression</strong></td><td>50-70% improvement</td><td>10-20% improvement</td><td>Limited by XML verbosity</td></tr> -<tr><td><strong>Multiplexing Benefit</strong></td><td>Significant for concurrent calls</td><td>Moderate for RPC-style calls</td><td>Some improvement</td></tr> -<tr><td><strong>Large Payload Streaming</strong></td><td>40-70% faster</td><td>5-15% faster</td><td>Minimal due to XML overhead</td></tr> -<tr><td><strong>Memory Efficiency</strong></td><td>20-30% reduction</td><td>5-10% reduction</td><td>Limited by XML processing</td></tr> -</table> - -<h4>Realistic SOAP Performance Expectations</h4> - -<p>For SOAP services using HTTP/2 transport:</p> - -<ul> - <li><strong>Small SOAP Messages (0MB-1MB):</strong> 5-15% latency improvement due to connection multiplexing</li> - <li><strong>Medium SOAP Messages (1-10MB):</strong> 10-20% improvement from header compression</li> - <li><strong>Large SOAP Messages (10MB+):</strong> 15-25% improvement from streaming, but still much slower than equivalent JSON</li> - <li><strong>Concurrent SOAP Calls:</strong> 20-40% improvement from stream multiplexing</li> - <li><strong>MTOM Attachments:</strong> Minimal improvement due to base64 encoding overhead</li> -</ul> - -<h4>SOAP Configuration Recommendations</h4> - -<p>For SOAP services that must use HTTP/2, optimize for the limited benefits:</p> - -<pre> -<transportSender name="h2" class="org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender"> - <parameter name="PROTOCOL">HTTP/2.0</parameter> - - <!-- SOAP-Optimized Settings --> - <parameter name="maxConcurrentStreams">50</parameter> <!-- Higher for concurrent RPC --> - <parameter name="initialWindowSize">131072</parameter> <!-- 128KB for typical SOAP --> - - <!-- Standard timeouts for SOAP processing --> - <parameter name="responseTimeout">120000</parameter> <!-- 2 minutes --> - - <!-- Enable fallback for SOAP clients that may not support HTTP/2 --> - <parameter name="http2FallbackEnabled">true</parameter> -</transportSender> -</pre> - -<h4>Why SOAP Benefits are Limited</h4> - -<ol> - <li><strong>XML Verbosity:</strong> SOAP's verbose XML structure reduces HTTP/2's binary efficiency gains</li> - <li><strong>Processing Overhead:</strong> XML parsing/serialization dominates performance, not transport</li> - <li><strong>Legacy Architecture:</strong> Most SOAP services designed for HTTP/1.1 request-response patterns</li> - <li><strong>Attachment Handling:</strong> MTOM base64 encoding negates HTTP/2 binary advantages</li> - <li><strong>Client Support:</strong> Many SOAP clients don't support HTTP/2 protocol negotiation</li> -</ol> - -<h4>Minimal SOAP Testing Status</h4> - -<p>The HTTP/2 transport includes basic SOAP compatibility testing via <code>H2SOAPCompatibilityTest.java</code>:</p> - -<ul> - <li>✅ <strong>SOAP 1.1 Messages:</strong> Basic envelope creation and processing tested</li> - <li>✅ <strong>SOAP 1.2 Messages:</strong> Basic envelope creation and processing tested</li> - <li>✅ <strong>Complex SOAP Structures:</strong> Multi-element message handling verified</li> - <li>✅ <strong>HTTP/2 Transport Integration:</strong> H2TransportSender initialization and configuration tested</li> - <li>⚠️ <strong>MTOM Attachments:</strong> Functional but limited performance benefit (not specifically tested)</li> - <li>⚠️ <strong>WS-Security:</strong> Compatible but not optimized for HTTP/2 (not specifically tested)</li> - <li>❌ <strong>Advanced SOAP Features:</strong> WS-ReliableMessaging, WS-AtomicTransaction not tested</li> -</ul> - -<p><strong>Test Coverage:</strong> The test suite focuses on basic compatibility rather than performance, -confirming that SOAP messages can be created, processed, and transported over HTTP/2 without errors. -This aligns with the 10% effort allocation for SOAP testing as documented in the migration plan.</p> - -<h4>Authentication Patterns: JSON vs SOAP Focus</h4> - -<p><strong>Important:</strong> The HTTP/2 transport has unimplemented authentication features that are -<strong>SOAP-focused rather than JSON-focused</strong>. This design decision reflects modern API patterns.</p> - -<table border="1"> -<tr><th>Authentication Type</th><th>JSON APIs</th><th>SOAP Services</th><th>HTTP/2 Status</th></tr> -<tr><td><strong>Bearer Token (JWT/OAuth 2.0)</strong></td><td>✅ Primary Method</td><td>❌ Rarely Used</td><td>✅ <strong>Supported</strong> (via headers)</td></tr> -<tr><td><strong>API Key Authentication</strong></td><td>✅ Very Common</td><td>❌ Rarely Used</td><td>✅ <strong>Supported</strong> (via headers)</td></tr> -<tr><td><strong>Custom Header Auth</strong></td><td>✅ Common</td><td>❌ Rarely Used</td><td>✅ <strong>Supported</strong> (via headers)</td></tr> -<tr><td><strong>HTTP Basic Authentication</strong></td><td>❌ Discouraged</td><td>✅ Very Common</td><td>❌ <strong>Not Implemented</strong></td></tr> -<tr><td><strong>HTTP Digest Authentication</strong></td><td>❌ Never Used</td><td>✅ Common</td><td>❌ <strong>Not Implemented</strong></td></tr> -<tr><td><strong>NTLM Authentication</strong></td><td>❌ Never Used</td><td>✅ Enterprise Use</td><td>❌ <strong>Not Implemented</strong></td></tr> -</table> - -<p><strong>JSON API Authentication Reality:</strong></p> -<pre> -# Modern JSON API patterns (fully supported by HTTP/2) -curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." https://api.example.com/data -curl -H "X-API-Key: abc123def456" https://api.example.com/data -curl -H "X-Auth-Token: custom-token-value" https://api.example.com/data -</pre> - -<p><strong>SOAP Service Authentication Reality:</strong></p> -<pre> -# Legacy SOAP patterns (not implemented in HTTP/2 transport) -# Basic Authentication: username:password encoded in Authorization header -# Digest Authentication: challenge-response authentication -# NTLM Authentication: Windows domain-integrated authentication -</pre> - -<p><strong>Design Rationale:</strong> The HTTP/2 transport prioritizes modern JSON API authentication patterns -over legacy SOAP authentication schemes. This reflects the reality that:</p> - -<ul> - <li><strong>JSON APIs (90% of HTTP/2 usage)</strong> use token-based authentication via standard HTTP headers</li> - <li><strong>SOAP Services (10% of HTTP/2 usage)</strong> typically remain on HTTP/1.1 with legacy authentication</li> - <li><strong>Enterprise SOAP migrations</strong> usually modernize authentication alongside protocol upgrades</li> -</ul> - -<p><strong>Missing Authentication Impact:</strong> The unimplemented HTTPAuthenticator schemes affect primarily -legacy SOAP services, not modern JSON APIs. For JSON applications, authentication works seamlessly through -standard HTTP headers without requiring HTTP/2 transport-specific authentication implementations.</p> - -<h4>Migration Recommendation</h4> - -<p><strong>For New Projects:</strong> Use JSON APIs over HTTP/2 for optimal performance</p> - -<p><strong>For Existing SOAP Services:</strong></p> -<ol> - <li><strong>Stay with HTTP/1.1</strong> unless you need specific HTTP/2 features</li> - <li><strong>Focus on XML optimization</strong> (compression, efficient serialization) rather than protocol changes</li> - <li><strong>Consider REST/JSON modernization</strong> for better HTTP/2 benefits</li> - <li><strong>Use HTTP/2 only for concurrent SOAP calls</strong> where multiplexing provides clear benefit</li> -</ol> +<h3>SSL Notes</h3> -<p><strong>Bottom Line:</strong> HTTP/2 transport works with SOAP but provides minimal benefits. -The 90% performance gains are reserved for JSON APIs, while SOAP sees only 5-25% improvements.</p> +<p>HTTP/2 requires TLS 1.2+ with ALPN. Use OpenJDK 11+ (ALPN built in). +If ALPN negotiation fails, the transport falls back to HTTP/1.1 +automatically when <code>http2FallbackEnabled=true</code>.</p> </body> </html> diff --git a/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml b/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml index e9d7ab7768..4733685118 100644 --- a/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml +++ b/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml @@ -443,364 +443,5 @@ export CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.coyote.http2.Http2Protocol.jmxMetrics=true" </pre> -<h3>Advanced Tomcat HTTP/2 Optimizations</h3> - -<p>Advanced configuration patterns specific to Tomcat for maximum performance:</p> - -<pre> -# Advanced server.xml optimizations for large-scale OpenAPI deployments - -<!-- Custom Valve for OpenAPI Request Optimization --> -<Valve className="org.apache.axis2.tomcat.OpenApiHttp2OptimizationValve" - largeSpecThreshold="1048576" <!-- 1MB threshold --> - compressionLevel="6" <!-- Balanced compression --> - cacheEnabled="true" <!-- Cache generated specs --> - cacheTimeout="300" /> <!-- 5 minute cache --> - -<!-- Resource Optimization for Swagger UI --> -<Context> - <Resources className="org.apache.catalina.webresources.StandardRoot"> - <PreResources className="org.apache.catalina.webresources.DirResourceSet" - base="${catalina.base}/openapi-cache" - webAppMount="/openapi-cache" - internalPath="/" /> - </Resources> - - <!-- HTTP/2 Push for OpenAPI Resources --> - <Valve className="org.apache.catalina.valves.rewrite.RewriteValve" /> -</Context> - -# rewrite.config - HTTP/2 Server Push for OpenAPI assets -RewriteEngine on -RewriteCond %{HTTP:Connection} Upgrade -RewriteCond %{HTTP:Upgrade} h2c -RewriteRule ^/swagger-ui/(.*) /swagger-ui/$1 [E=push-resource] - -# Server Push Rules for OpenAPI UI Performance -RewriteRule ^/api-docs$ - [E=push:/swagger-ui/swagger-ui-bundle.js] -RewriteRule ^/api-docs$ - [E=push:/swagger-ui/swagger-ui-standalone-preset.js] -RewriteRule ^/api-docs$ - [E=push:/swagger-ui/swagger-ui.css] -</pre> - -<h2>Performance Benchmarking</h2> - -<h3>Test Environment Setup</h3> - -<p>Benchmark your OpenAPI + HTTP/2 implementation:</p> - -<pre> -# JMeter Test Plan for OpenAPI + HTTP/2 Performance -Thread Group: 50 concurrent users -Ramp-up: 10 seconds -Loop Count: 100 iterations - -Test Scenarios: -1. Large OpenAPI spec download (5MB specification) -2. Swagger UI complete loading (all assets) -3. Large JSON API response (50MB analytics data) -4. Concurrent API endpoint testing (10 simultaneous calls) - -Metrics Collected: -- Response time (95th percentile) -- Throughput (requests per second) -- Memory usage (heap and direct) -- Connection count and reuse -</pre> - -<h3>Expected Performance Results</h3> - -<table border="1"> -<tr><th>Test Scenario</th><th>HTTP/1.1 Baseline</th><th>HTTP/2 Performance</th><th>Improvement</th></tr> -<tr><td>OpenAPI Spec Download (5MB)</td><td>3.2s</td><td>2.0s</td><td>38% faster</td></tr> -<tr><td>Swagger UI Complete Load</td><td>4.5s</td><td>2.8s</td><td>38% faster</td></tr> -<tr><td>Large JSON Response (50MB)</td><td>8.7s</td><td>5.2s</td><td>40% faster</td></tr> -<tr><td>Concurrent API Calls (10x)</td><td>12.3s</td><td>7.8s</td><td>37% faster</td></tr> -<tr><td>Memory Usage</td><td>2.1GB peak</td><td>1.7GB peak</td><td>19% less memory</td></tr> -<tr><td>Connection Count</td><td>45-60 connections</td><td>8-12 connections</td><td>80% fewer connections</td></tr> -</table> - -<h2>Advanced Enterprise Patterns</h2> - -<h3>Large API Catalog Management</h3> - -<p>Enterprise organizations often manage dozens or hundreds of API services. HTTP/2 multiplexing -provides significant benefits for API discovery and management:</p> - -<pre> -// Enterprise API Gateway Pattern with HTTP/2 -@OpenApiConfiguration( - title = "Enterprise API Gateway", - description = "HTTP/2 optimized API catalog with 200+ enterprise services", - version = "3.0.0", - servers = { - @Server(url = "https://api.enterprise.com";, description = "Production HTTP/2 Gateway"), - @Server(url = "https://staging-api.enterprise.com";, description = "Staging Environment") - } -) -public class EnterpriseApiGateway { - - @GetMapping("/api-catalog") - @OpenApiOperation( - summary = "Get complete API catalog", - description = "HTTP/2 optimized delivery of enterprise API catalog (10MB+ specification)", - responses = { - @ApiResponse(responseCode = "200", - description = "Complete API catalog with HTTP/2 optimization") - } - ) - public ApiCatalogResponse getApiCatalog( - @RequestParam(defaultValue = "false") boolean includeSchemas, - @RequestParam(defaultValue = "10") int pageSize) { - - // HTTP/2 multiplexing enables efficient delivery of large catalogs - return catalogService.generateComprehensiveCatalog(includeSchemas, pageSize); - } -} -</pre> - -<h3>Real-Time API Analytics</h3> - -<p>HTTP/2 streaming capabilities enable real-time API analytics and monitoring:</p> - -<pre> -// Real-time API metrics with HTTP/2 streaming -@RestController -@OpenApiTag(name = "Analytics", description = "Real-time API performance analytics") -public class ApiAnalyticsController { - - @GetMapping("/analytics/real-time") - @OpenApiOperation( - summary = "Stream real-time API metrics", - description = "HTTP/2 streaming for continuous analytics delivery" - ) - public ResponseEntity<StreamingResponseBody> streamRealTimeMetrics() { - - StreamingResponseBody stream = outputStream -> { - try { - // HTTP/2 streaming enables real-time data delivery - metricsService.streamMetrics(outputStream); - } catch (Exception e) { - log.error("Error streaming analytics", e); - } - }; - - return ResponseEntity.ok() - .header("Content-Type", "application/json") - .header("Cache-Control", "no-cache") - .header("Connection", "keep-alive") // HTTP/2 multiplexing - .body(stream); - } -} -</pre> - -<h2>Security Integration</h2> - -<h3>HTTP/2 + OAuth2 Optimization</h3> - -<p>HTTP/2 provides security benefits for OAuth2-protected APIs through connection reuse -and reduced TLS handshake overhead:</p> - -<pre> -# Security Configuration for HTTP/2 + OpenAPI -openapi.security.oauth2.authorizationUrl=https://auth.enterprise.com/oauth2/authorize -openapi.security.oauth2.tokenUrl=https://auth.enterprise.com/oauth2/token -openapi.security.oauth2.scopes=read:api,write:api,admin:api - -# HTTP/2 Security Optimizations -openapi.security.http2.connectionReuse=true # Reuse authenticated connections -openapi.security.http2.tlsSessionCache=300 # 5-minute TLS session cache -openapi.security.http2.alpnNegotiation=true # Secure protocol negotiation -</pre> - -<h2>Monitoring and Observability</h2> - -<h3>HTTP/2 + OpenAPI Metrics</h3> - -<p>Monitor the performance benefits of HTTP/2 + OpenAPI integration:</p> - -<pre> -// Custom metrics for HTTP/2 + OpenAPI performance -@Component -public class OpenApiHttp2Metrics { - - private final MeterRegistry meterRegistry; - private final Timer specDeliveryTimer; - private final Counter http2RequestCounter; - private final Gauge connectionPoolGauge; - - public OpenApiHttp2Metrics(MeterRegistry meterRegistry) { - this.meterRegistry = meterRegistry; - this.specDeliveryTimer = Timer.builder("openapi.spec.delivery.time") - .description("Time to deliver OpenAPI specification") - .tag("protocol", "http2") - .register(meterRegistry); - - this.http2RequestCounter = Counter.builder("http2.requests.total") - .description("Total HTTP/2 requests processed") - .tag("api.type", "openapi") - .register(meterRegistry); - - this.connectionPoolGauge = Gauge.builder("http2.connections.active") - .description("Active HTTP/2 connections") - .register(meterRegistry, this, OpenApiHttp2Metrics::getActiveConnections); - } - - public void recordSpecDelivery(long deliveryTimeMs, String specSize) { - specDeliveryTimer.record(deliveryTimeMs, TimeUnit.MILLISECONDS); - Tags.of("spec.size.category", categorizeSpecSize(specSize)); - } -} -</pre> - -<h3>Performance Monitoring Dashboard</h3> - -<p>Create monitoring dashboards to track HTTP/2 + OpenAPI benefits:</p> - -<pre> -# Grafana Dashboard Queries for HTTP/2 + OpenAPI Performance - -# OpenAPI Specification Delivery Time -rate(openapi_spec_delivery_time_seconds[5m]) by (protocol, spec_size_category) - -# HTTP/2 Connection Efficiency -http2_connections_active / http1_connections_active - -# Large Response Processing Time -histogram_quantile(0.95, rate(api_response_time_bucket{size="large"}[5m])) by (protocol) - -# Memory Usage Comparison -(jvm_memory_used_bytes{protocol="http2"} / jvm_memory_used_bytes{protocol="http1"}) * 100 - -# Swagger UI Load Time -rate(swagger_ui_load_time_seconds[5m]) by (protocol) -</pre> - -<h2>Migration Strategy</h2> - -<h3>Phase 1: Parallel Deployment</h3> - -<ol> - <li><strong>Deploy HTTP/2 transport alongside HTTP/1.1</strong> - <ul> - <li>Configure dual transport support in axis2.xml</li> - <li>Test OpenAPI functionality with both protocols</li> - <li>Monitor performance differences</li> - </ul> - </li> - <li><strong>Validate OpenAPI + HTTP/2 integration</strong> - <ul> - <li>Test large specification delivery</li> - <li>Verify Swagger UI performance</li> - <li>Ensure security integration works correctly</li> - </ul> - </li> -</ol> - -<h3>Phase 2: Gradual Migration</h3> - -<ol> - <li><strong>Migrate high-traffic APIs first</strong> - <ul> - <li>Focus on APIs with large responses (>10MB)</li> - <li>Migrate APIs with complex OpenAPI specifications</li> - <li>Monitor performance improvements</li> - </ul> - </li> - <li><strong>Optimize configuration based on usage patterns</strong> - <ul> - <li>Tune HTTP/2 parameters for your specific workload</li> - <li>Adjust OpenAPI configuration for optimal performance</li> - <li>Implement monitoring and alerting</li> - </ul> - </li> -</ol> - -<h3>Phase 3: Full HTTP/2 Adoption</h3> - -<ol> - <li><strong>Complete migration to HTTP/2</strong> - <ul> - <li>Migrate remaining APIs to HTTP/2 transport</li> - <li>Deprecate HTTP/1.1 transport where possible</li> - <li>Optimize WildFly deployment configuration</li> - </ul> - </li> - <li><strong>Advanced optimizations</strong> - <ul> - <li>Implement advanced HTTP/2 features (server push for proactive caching)</li> - <li>Optimize for specific enterprise use cases</li> - <li>Create custom monitoring and analytics</li> - </ul> - </li> -</ol> - - -<h2>Troubleshooting</h2> - -<h3>Common Issues and Solutions</h3> - -<table border="1"> -<tr><th>Issue</th><th>Symptoms</th><th>Solution</th></tr> -<tr> - <td><strong>HTTP/2 not negotiated</strong></td> - <td>Falling back to HTTP/1.1</td> - <td>Ensure HTTPS is enabled and ALPN is configured correctly</td> -</tr> -<tr> - <td><strong>Large OpenAPI spec timeout</strong></td> - <td>Specification loading fails</td> - <td>Increase HTTP/2 window size and adjust timeout parameters</td> -</tr> -<tr> - <td><strong>Swagger UI assets not loading</strong></td> - <td>UI appears broken or incomplete</td> - <td>Verify HTTP/2 multiplexing is working and check CORS headers</td> -</tr> -<tr> - <td><strong>Performance not improved</strong></td> - <td>No visible performance gains</td> - <td>Ensure client supports HTTP/2 and verify configuration</td> -</tr> -</table> - -<h3>Debug Configuration</h3> - -<pre> -# Enable HTTP/2 + OpenAPI debugging -log4j.logger.org.apache.axis2.transport.h2=DEBUG -log4j.logger.org.apache.axis2.openapi=DEBUG -log4j.logger.org.apache.axis2.transport.http=INFO - -# JVM parameters for HTTP/2 debugging --Dorg.apache.axis2.http2.debug=true --Dorg.apache.axis2.openapi.performance.monitoring=true --Dorg.apache.axis2.http2.frameLogging=true -</pre> - -<h2>Summary</h2> - -<p>Apache Axis2's integration of HTTP/2 with OpenAPI provides significant benefits:</p> - -<ul> - <li><strong>Native HTTP/2 Transport</strong>: Complete HTTP/2 implementation with OpenAPI optimization</li> - <li><strong>Proven Performance Benefits</strong>: 30-40% improvements in real-world scenarios</li> - <li><strong>Enterprise Ready</strong>: Production-ready with WildFly and Tomcat integration and comprehensive monitoring</li> - <li><strong>Modern Architecture</strong>: Built for modern web standards and high-performance requirements</li> - <li><strong>Deployment Flexibility</strong>: Multiple deployment options with intelligent configuration defaults</li> -</ul> - -<p>By implementing HTTP/2 + OpenAPI integration, organizations can achieve significant performance improvements -while positioning their technology stack with modern, standardized protocols that provide long-term benefits.</p> - -<div style="background-color: #e8f5e8; border: 1px solid #4CAF50; padding: 15px; margin: 15px 0;"> -<strong>📈 Next Steps:</strong> -<ol> - <li>Deploy a pilot HTTP/2 + OpenAPI service using the quick start configuration</li> - <li>Benchmark performance improvements in your specific environment</li> - <li>Plan migration strategy based on your API catalog and usage patterns</li> - <li>Optimize configuration based on your specific performance requirements and deployment environment</li> -</ol> -</div> - </body> </html> diff --git a/src/site/xdoc/docs/spring-boot-starter.xml b/src/site/xdoc/docs/spring-boot-starter.xml index 83f0a7836e..0c25a501b5 100644 --- a/src/site/xdoc/docs/spring-boot-starter.xml +++ b/src/site/xdoc/docs/spring-boot-starter.xml @@ -51,6 +51,7 @@ for details and rationale.</p> <li><a href="#openapi_mcp">7. OpenAPI and MCP Support</a></li> <li><a href="#migration">8. Migration from Manual Configuration</a></li> <li><a href="#containers">9. Container Support</a></li> +<li><a href="#http2">10. HTTP/2 and Streaming</a></li> </ul> <!-- ============================================================ --> @@ -410,5 +411,43 @@ identical in structure to the configuration used by the legacy userguide <p>See <a href="#deployment_model">Section 0</a> for the full container compatibility matrix and the rationale for WAR-only deployment.</p> +<!-- ============================================================ --> +<a name="http2"/> +<h2>10. HTTP/2 and Streaming</h2> + +<p>Axis2/Java has <strong>built-in HTTP/2 support at the serialization +layer</strong>, not just the transport layer. Unlike most frameworks where +the servlet container handles HTTP/2 transparently and the serialization +is unaware of the protocol, Axis2 integrates HTTP/2 awareness into the +JSON message formatter pipeline:</p> + +<ul> + <li><strong>Dedicated HTTP/2 transport module</strong> + (<code>modules/transport-h2</code>) — ALPN negotiation, per-stream + flow control, adaptive buffering, compression optimization, and + HTTP/1.1 fallback. See + <a href="http2-integration-guide.html">HTTP/2 Integration Guide</a>.</li> + <li><strong>Streaming JSON formatters</strong> — flush every 64 KB + during serialization, converting a single buffered response into a + stream of HTTP/2 DATA frames. A 50MB response arrives at the client + as ~780 incremental frames, with the first frame arriving within + milliseconds. See + <a href="json-streaming-formatter.html">Streaming JSON Formatter</a>.</li> + <li><strong>Field selection</strong> — callers add + <code>?fields=status,result</code> to any service URL and the + response includes only those fields, filtered during serialization + with zero overhead when not used. See + <a href="json-streaming-formatter.html#Field_Selection">Field Selection</a>.</li> + <li><strong>C parity</strong> — the same streaming architecture exists + in Axis2/C via Apache httpd <code>mod_h2</code>. Both + implementations use the same 64 KB flush interval, producing + identical HTTP/2 DATA frame patterns.</li> +</ul> + +<p>For a detailed comparison of Axis2's HTTP/2 architecture with +Spring MVC, JAX-RS, gRPC, and other frameworks, see the +<a href="http2-integration-guide.html#How_Axis2_HTTP2_Differs_From_Other_Frameworks">framework comparison</a> +in the HTTP/2 Integration Guide.</p> + </body> </html> diff --git a/src/site/xdoc/docs/tomcat-http2-integration-guide.xml b/src/site/xdoc/docs/tomcat-http2-integration-guide.xml index b5d2c5516a..1ac7bf40c1 100644 --- a/src/site/xdoc/docs/tomcat-http2-integration-guide.xml +++ b/src/site/xdoc/docs/tomcat-http2-integration-guide.xml @@ -294,75 +294,6 @@ export CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.coyote.http2.Http2Protocol.jmxMetrics=true" </pre> -<h2>Performance Comparison: Tomcat 11 vs WildFly 32</h2> - -<h3>1. Configuration Complexity</h3> - -<table border="1"> -<tr><th>Aspect</th><th>Tomcat 11</th><th>WildFly 32</th><th>Winner</th></tr> -<tr> - <td><strong>Lines of Config</strong></td> - <td>~50 lines (server.xml)</td> - <td>~150 lines (standalone.xml)</td> - <td>✅ <strong>Tomcat</strong>: 3x simpler</td> -</tr> -<tr> - <td><strong>SSL Setup Time</strong></td> - <td>2-5 minutes</td> - <td>15-30 minutes</td> - <td>✅ <strong>Tomcat</strong>: 6x faster</td> -</tr> -<tr> - <td><strong>HTTP/2 Parameters</strong></td> - <td>6 key parameters</td> - <td>12+ complex parameters</td> - <td>✅ <strong>Tomcat</strong>: Simpler</td> -</tr> -<tr> - <td><strong>Deployment Model</strong></td> - <td>Standard WAR deployment</td> - <td>Complex module system</td> - <td>✅ <strong>Tomcat</strong>: No conflicts</td> -</tr> -</table> - -<h3>2. Performance Benchmarks</h3> - -<div style="background-color: #e8f5e8; border: 1px solid #4CAF50; padding: 10px; margin: 10px 0;"> -<strong>🎯 Tomcat 11 + Axis2 + Enhanced Moshi H2 Performance Results:</strong> -<ul> - <li><strong>Large JSON Processing</strong>: 45-65% faster than WildFly 32</li> - <li><strong>HTTP/2 Concurrent Streams</strong>: 20% better stream management efficiency</li> - <li><strong>Memory Usage</strong>: 30% lower baseline memory consumption</li> - <li><strong>SSL/TLS Handshake</strong>: 15% faster HTTPS connection establishment</li> - <li><strong>JSON Compression</strong>: 25% better compression ratios for JSON responses</li> -</ul> -</div> - -<h3>3. Real-World Performance Tests</h3> - -<pre> -Benchmark Environment: -- 4 CPU cores, 8GB RAM -- 100MB JSON payloads -- 50 concurrent connections -- HTTP/2 with Enhanced Moshi H2 - -Results (Average Response Time): -┌─────────────────────────────────────────────────────────┐ -│ Tomcat 11 + HTTP/2 + Enhanced Moshi H2: 8.2 seconds │ -│ WildFly 32 + HTTP/2 + Enhanced Moshi H2: 11.7 seconds │ -│ Improvement: 30% faster JSON processing │ -└─────────────────────────────────────────────────────────┘ - -Memory Usage: -┌─────────────────────────────────────────────────────────┐ -│ Tomcat 11 Baseline: 480MB heap usage │ -│ WildFly 32 Baseline: 720MB heap usage │ -│ Memory Advantage: 33% less memory consumption │ -└─────────────────────────────────────────────────────────┘ -</pre> - <h2>Production Deployment Guide</h2> <h3>1. Step-by-Step Deployment</h3> @@ -467,167 +398,6 @@ jstat -gc -t $(pgrep -f tomcat) 5s netstat -an | grep :8443 | grep ESTABLISHED | wc -l </pre> -<h2>Advanced Production Optimizations</h2> - -<h3>1. Load Balancing with HTTP/2</h3> - -<h4>Apache HTTP Server + mod_h2 Configuration</h4> -<pre> -# Load balancer configuration for HTTP/2 -LoadModule http2_module modules/mod_h2.so - -<VirtualHost *:443> - ServerName your-domain.com - - # Enable HTTP/2 - Protocols h2 http/1.1 - H2Direct on - H2MaxSessionStreams 200 - H2WindowSize 65536 - - # Proxy to Tomcat cluster - ProxyPreserveHost On - ProxyPassMatch ^/(.*)$ balancer://tomcat-cluster/$1 - - <Proxy balancer://tomcat-cluster> - BalancerMember https://tomcat1:8443 - BalancerMember https://tomcat2:8443 - ProxySet hcmethod=GET - ProxySet hcuri=/health-check - </Proxy> -</VirtualHost> -</pre> - -<h3>2. Container Deployment (Docker)</h3> - -<h4>Production Dockerfile</h4> -<pre> -FROM tomcat:11-jdk17-openjdk - -# Copy optimized server.xml -COPY server.xml /usr/local/tomcat/conf/ - -# Copy SSL certificates -COPY ssl/ /usr/local/tomcat/ssl/ - -# Copy Axis2 application -COPY your-axis2-app.war /usr/local/tomcat/webapps/ - -# JVM optimization for HTTP/2 -ENV CATALINA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200" -ENV CATALINA_OPTS="${CATALINA_OPTS} -Dorg.apache.coyote.http2.Http2Protocol.maxConcurrentStreams=200" -ENV CATALINA_OPTS="${CATALINA_OPTS} -Daxis2.json.moshi.h2.enabled=true" - -# Expose HTTP/2 ports -EXPOSE 8080 8443 - -CMD ["catalina.sh", "run"] -</pre> - -<h4>Docker Compose for Production</h4> -<pre> -version: '3.8' -services: - axis2-http2: - build: . - ports: - - "8080:8080" - - "8443:8443" - environment: - - JAVA_OPTS=-Xms2g -Xmx4g - volumes: - - ./logs:/usr/local/tomcat/logs - - ./ssl:/usr/local/tomcat/ssl - networks: - - axis2-network - - nginx-lb: - image: nginx:alpine - ports: - - "443:443" - volumes: - - ./nginx.conf:/etc/nginx/nginx.conf - - ./ssl:/etc/nginx/ssl - depends_on: - - axis2-http2 - networks: - - axis2-network - -networks: - axis2-network: - driver: bridge -</pre> - -<h2>Migration from WildFly to Tomcat 11</h2> - -<h3>Migration Checklist</h3> - -<table border="1"> -<tr><th>Migration Step</th><th>WildFly 32</th><th>Tomcat 11 Equivalent</th><th>Status</th></tr> -<tr> - <td><strong>HTTP/2 Configuration</strong></td> - <td>standalone.xml undertow subsystem</td> - <td>server.xml Connector configuration</td> - <td>✅ Simpler in Tomcat</td> -</tr> -<tr> - <td><strong>SSL Configuration</strong></td> - <td>applicationSSC security domain</td> - <td>Direct certificate files in Connector</td> - <td>✅ More straightforward</td> -</tr> -<tr> - <td><strong>Thread Pool</strong></td> - <td>Undertow worker configuration</td> - <td>Executor thread pool</td> - <td>✅ Cleaner configuration</td> -</tr> -<tr> - <td><strong>Deployment Model</strong></td> - <td>WAR in deployments/ directory</td> - <td>WAR in webapps/ directory</td> - <td>✅ Standard approach</td> -</tr> -<tr> - <td><strong>Monitoring</strong></td> - <td>WildFly management console</td> - <td>JMX + access logs</td> - <td>✅ Industry standard</td> -</tr> -</table> - -<h3>Performance Benefits of Migration</h3> - -<div style="background-color: #e8f5e8; border: 1px solid #4CAF50; padding: 15px; margin: 10px 0;"> -<h4>✅ Expected Performance Improvements After Migration</h4> -<ul> - <li><strong>30-45% faster JSON processing</strong> with Enhanced Moshi H2 integration</li> - <li><strong>25% reduced memory usage</strong> compared to WildFly baseline</li> - <li><strong>50% easier configuration management</strong> and deployment process</li> - <li><strong>Zero classloader conflicts</strong> - eliminates WildFly module system issues</li> - <li><strong>Better HTTP/2 stream efficiency</strong> - Tomcat's native implementation advantages</li> -</ul> -</div> - -<h2>Conclusion: Tomcat 11 Superior Choice for Axis2 HTTP/2</h2> - -<p><strong>✅ VERDICT: Apache Tomcat 11 provides superior HTTP/2 + Axis2 integration compared to WildFly 32</strong></p> - -<h3>Key Advantages Summary</h3> - -<ol> - <li><strong>Simplified Configuration</strong>: 75% less configuration complexity</li> - <li><strong>Better Performance</strong>: 30-45% faster JSON processing with HTTP/2</li> - <li><strong>Lower Resource Usage</strong>: 30% less memory consumption</li> - <li><strong>Easier SSL Setup</strong>: Native certificate support without complex security domains</li> - <li><strong>Zero Integration Issues</strong>: No classloader conflicts or module system complexity</li> - <li><strong>Production Ready</strong>: Battle-tested HTTP/2 implementation with excellent monitoring</li> -</ol> - -<p><strong>For enterprises evaluating HTTP/2 + Axis2 deployment</strong>, Tomcat 11 provides the optimal balance of performance, simplicity, and reliability. The Enhanced Moshi H2 integration delivers exceptional JSON processing performance while maintaining the familiar Tomcat deployment model.</p> - -<p><strong>Migration Recommendation</strong>: Organizations currently using WildFly for Axis2 applications should strongly consider migrating to Tomcat 11 to realize significant performance improvements and operational simplification benefits.</p> - </div> </body> diff --git a/src/site/xdoc/docs/wildfly-http2-integration-guide.xml b/src/site/xdoc/docs/wildfly-http2-integration-guide.xml index 1c3c2a441e..c8e944f535 100644 --- a/src/site/xdoc/docs/wildfly-http2-integration-guide.xml +++ b/src/site/xdoc/docs/wildfly-http2-integration-guide.xml @@ -21,12 +21,16 @@ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd";> <properties> - <title>WildFly + Axis2 HTTP/2 Integration - what works, what didn't, and lessons learned</title> + <title>WildFly + Axis2 HTTP/2 Integration Guide</title> </properties> <body> -<h1>WildFly + Axis2 HTTP/2 Integration - Failed Attempts and Lessons Learned</h1> +<h1>WildFly + Axis2 HTTP/2 Integration Guide</h1> + +<p><strong>Tested on:</strong> WildFly 32 (OpenJDK 17, 21) and WildFly 39 +(OpenJDK 21, 25). Configuration examples below use WildFly 32 syntax; +WildFly 39 is compatible with the same configuration.</p> <div style="background-color: #ffe8e8; border: 1px solid #ff4444; padding: 10px; margin: 10px 0;"> @@ -490,524 +494,43 @@ curl -k --http2 --location 'https://localhost:8443/services/YourService' \ # - No class loader conflicts </pre> -<h2>Buffer Size Configuration Analysis & Potential Clashes</h2> - -<p><strong>⚠️ CRITICAL ANALYSIS</strong>: While the configurations are coordinated, there are potential efficiency issues and clashes that need attention:</p> - -<h3>1. Buffer Size Alignment Analysis (WildFly 32)</h3> - -<table border="1"> -<tr><th>Layer</th><th>Current Configuration</th><th>Recommended Configuration</th><th>Impact</th></tr> -<tr> - <td><strong>WildFly 32 Buffers</strong></td> - <td><code>buffer-size="2048"</code> (2KB)</td> - <td><code>buffer-size="32768"</code> (32KB)</td> - <td rowspan="4">✅ <strong>ALIGNED</strong>: All layers using 32KB for optimal performance</td> -</tr> -<tr> - <td><strong>WildFly HTTP/2 Frames</strong></td> - <td>Missing <code>http2-max-frame-size</code></td> - <td><code>http2-max-frame-size="32768"</code></td> -</tr> -<tr> - <td><strong>transport-h2</strong></td> - <td>Default (~8KB)</td> - <td><code>streamingBufferSize="32768"</code></td> -</tr> -<tr> - <td><strong>Enhanced Moshi H2</strong></td> - <td>Default processing</td> - <td><code>moshiStreamingBufferSize="32768"</code></td> -</tr> -</table> - -<p><strong>❌ CRITICAL ISSUE</strong>: Your current 2KB buffer configuration severely limits performance for large JSON payloads. The recommended 32KB alignment provides optimal performance while conserving memory.</p> - -<h3>2. Memory Amplification Risk</h3> - -<pre> -Memory Usage Analysis (Per Large Request): -┌─────────────────────────────────────────────────────────────┐ -│ WildFly Layer: 100 streams × 64KB window = 6.4MB │ -│ transport-h2: 50 connections × 10 routes = 500 streams │ -│ Enhanced Moshi: Async processing + field optimization │ -│ │ -│ 🚨 POTENTIAL TOTAL: 100 streams × 64KB × 3 layers = 19MB │ -│ For 50 connections: 19MB × 50 = 950MB just for buffers │ -└─────────────────────────────────────────────────────────────┘ -</pre> - -<p><strong>Risk</strong>: Memory amplification across layers can consume significant heap space, especially with large payloads and high concurrency.</p> +<h2>Troubleshooting</h2> -<h3>3. Flow Control Interference</h3> +<p>Common issues and resolution:</p> <table border="1"> -<tr><th>Flow Control Layer</th><th>Managed By</th><th>Scope</th><th>Potential Conflict</th></tr> +<tr><th>Symptom</th><th>Cause</th><th>Fix</th></tr> <tr> - <td><strong>HTTP/2 Protocol Level</strong></td> - <td>WildFly</td> - <td>Inbound requests</td> - <td rowspan="3">⚠️ Multiple layers managing flow control independently can cause backpressure conflicts</td> + <td>HTTP/1.1 used despite <code>enable-http2="true"</code></td> + <td>Missing ALPN or TLS < 1.2</td> + <td>Ensure OpenJDK 11+ and <code>ssl-context</code> configured with TLS 1.2+</td> </tr> <tr> - <td><strong>HTTP/2 Client Level</strong></td> - <td>transport-h2</td> - <td>Outbound requests</td> -</tr> -<tr> - <td><strong>Application Level</strong></td> - <td>Enhanced Moshi H2</td> - <td>JSON processing</td> -</tr> -</table> - -<h3>4. Timeout Coordination Issues</h3> - -<table border="1"> -<tr><th>Layer</th><th>Connection Timeout</th><th>Processing Timeout</th><th>Clash Risk</th></tr> -<tr> - <td><strong>WildFly</strong></td> - <td>N/A (server)</td> - <td>300s (5 min)</td> - <td>✅ Good for large payloads</td> -</tr> -<tr> - <td><strong>transport-h2</strong></td> - <td>30s</td> - <td>300s (5 min)</td> - <td>⚠️ <strong>30s connection timeout too short for large payload processing</strong></td> -</tr> -<tr> - <td><strong>Enhanced Moshi H2</strong></td> - <td>N/A</td> - <td>CompletableFuture timeout</td> - <td>⚠️ No explicit timeout coordination</td> -</tr> -</table> - -<h3>5. Optimal Configuration Recommendations</h3> - -<h4>Fix Buffer Size Alignment</h4> -<pre> -<!-- WildFly: Increase frame size to match buffers --> -<https-listener name="https" socket-binding="https" - enable-http2="true" - http2-max-frame-size="65536" <!-- Increase to 64KB --> - http2-initial-window-size="65536" <!-- Keep 64KB --> - http2-max-concurrent-streams="100"/> - -<!-- OR transport-h2: Reduce buffer size to match WildFly --> -<parameter name="streamingBufferSize">32768</parameter> <!-- Reduce to 32KB --> -<parameter name="moshiStreamingBufferSize">32768</parameter> <!-- Reduce to 32KB --> -</pre> - -<h4>Memory-Optimized Configuration</h4> -<pre> -<!-- Conservative memory settings for 2GB heap --> -<https-listener name="https" socket-binding="https" - enable-http2="true" - http2-max-frame-size="32768" <!-- 32KB frames --> - http2-initial-window-size="32768" <!-- 32KB window --> - http2-max-concurrent-streams="50" <!-- Reduce streams --> - max-post-size="52428800"/> <!-- 50MB max --> - -<!-- Coordinated transport-h2 settings --> -<parameter name="maxConcurrentStreams">50</parameter> <!-- Match WildFly --> -<parameter name="initialWindowSize">32768</parameter> <!-- Match WildFly --> -<parameter name="connectionTimeout">60000</parameter> <!-- Increase to 60s --> -<parameter name="streamingBufferSize">32768</parameter> <!-- Match frame size --> - -<!-- Coordinated Moshi settings --> -<parameter name="moshiStreamingBufferSize">32768</parameter> <!-- Match frame size --> -<parameter name="AsyncProcessingThreshold">2097152</parameter> <!-- Increase to 2MB --> -</pre> - -<h4>Performance-Optimized Configuration</h4> -<pre> -<!-- High-performance settings for larger heaps (4GB+) --> -<https-listener name="https" socket-binding="https" - enable-http2="true" - http2-max-frame-size="65536" <!-- 64KB frames --> - http2-initial-window-size="131072" <!-- 128KB window --> - http2-max-concurrent-streams="200" <!-- More streams --> - max-post-size="104857600"/> <!-- 100MB max --> - -<!-- High-performance transport-h2 --> -<parameter name="maxConcurrentStreams">200</parameter> <!-- Match WildFly --> -<parameter name="initialWindowSize">131072</parameter> <!-- 128KB window --> -<parameter name="streamingBufferSize">65536</parameter> <!-- 64KB buffers --> - -<!-- High-performance Moshi --> -<parameter name="moshiStreamingBufferSize">65536</parameter> <!-- 64KB buffers --> -<parameter name="AsyncProcessingThreshold">524288</parameter> <!-- Lower to 512KB --> -</pre> - -<h3>6. Deployment Recommendations</h3> - -<table border="1"> -<tr><th>Environment</th><th>Memory</th><th>Configuration</th><th>Expected Performance</th></tr> -<tr> - <td><strong>Memory-Constrained</strong></td> - <td>≤ 2GB</td> - <td>32KB buffers, 50 streams</td> - <td>Stable, +30% improvement</td> + <td>502 Bad Gateway on large responses</td> + <td>Reverse proxy timeout before data flows</td> + <td>Use streaming JSON formatter (<code>FlushingOutputStream</code>) — flushes every 64 KB</td> </tr> <tr> - <td><strong>Balanced Production</strong></td> - <td>2-4GB</td> - <td>64KB buffers, 100 streams</td> - <td>Good performance, +45% improvement</td> + <td>ClassLoader conflicts with log4j</td> + <td>WildFly's jboss-logmanager conflicts with WAR's log4j-core</td> + <td>Add <code>jboss-deployment-structure.xml</code> excluding <code>org.apache.logging.log4j.api</code></td> </tr> <tr> - <td><strong>High-Performance</strong></td> - <td>4GB+</td> - <td>64KB+ buffers, 200+ streams</td> - <td>Maximum throughput, +60% improvement</td> + <td>Buffer alignment warnings</td> + <td>WildFly buffer size (2KB default) mismatched with Axis2 flush interval (64KB)</td> + <td>Set <code>buffer-size="32768"</code> in WildFly's Undertow config to align with Axis2</td> </tr> </table> -<h2>Failed Integration Attempts and Root Cause Analysis</h2> - -<h3>1. The Fundamental Problem: Axis2 Axiom Integration Requirements</h3> - -<p><strong>Core Issue</strong>: Apache Axis2 requires all incoming JSON data to be converted to **OMElement** objects (Apache Axiom's XML Object Model) for processing by web services. This conversion must happen <strong>within Axis2's processing pipeline</strong>, not at the WildFly container level.</p> - -<pre> -Key Axis2 Processing Requirements: -┌─────────────────────────────────────────────────────────┐ -│ 1. JSON Input → Axiom OMElement Objects │ -│ 2. OMElement → SOAP Processing → Web Service Methods │ -│ 3. Response Objects → OMElement → JSON Output │ -└─────────────────────────────────────────────────────────┘ - -WildFly HTTP/2 Integration Challenge: -┌─────────────────────────────────────────────────────────┐ -│ WildFly Layer: HTTP/2 → Raw JSON Bytes │ -│ ❌ DISCONNECT: No direct path to Axis2 OMElement │ -│ Axis2 Layer: JSON Bytes → OMElement Conversion │ -└─────────────────────────────────────────────────────────┘ -</pre> - -<p><strong>Why WildFly Integration Failed</strong>: WildFly's HTTP/2 processing operates at the container level with <code>HttpServerExchange</code> and raw byte streams, while Axis2 requires specialized JSON-to-OMElement conversion within its own <code>MessageBuilder</code> architecture. The two systems operate at different abstraction levels with incompatible processing models.</p> - -<h3>2. Axis2 JSON Processing Architecture Conflicts</h3> - -<p><strong>The Deeper Problem</strong>: Axis2's JSON processing requires custom <code>MessageBuilder</code> and <code>MessageFormatter</code> implementations that convert between JSON and Axiom OMElement objects:</p> - -<pre> -Axis2 JSON Processing Pipeline: -InputStream → JsonReader → XMLStreamReader → OMElement → Web Service - -Required Integration Points: -- JsonBuilder.processDocument() → OMElement -- JsonFormatter.writeTo() → OMElement → JSON -- Deep integration with SOAPFactory, OMAbstractFactory -- Custom XMLStreamReader implementation for JSON conversion -</pre> - -<p><strong>WildFly Integration Impossibility</strong>: WildFly HTTP/2 integration would require:</p> -<ul> - <li><strong>Bypassing Axis2's MessageBuilder architecture</strong> - Breaking core JSON processing</li> - <li><strong>Custom OMElement creation at container level</strong> - Violating separation of concerns</li> - <li><strong>Deep coupling between WildFly and Axis2 internals</strong> - Architectural violation</li> - <li><strong>Duplicating JSON-to-XML conversion logic</strong> - Maintenance nightmare</li> -</ul> - -<h3>3. The Subsequent org.xnio.XnioWorker LinkageError</h3> - -<p><strong>Secondary Issue</strong>: After discovering the Axiom integration challenges, attempts to create hybrid integration classes led to class loader conflicts:</p> - -<pre> -java.lang.LinkageError: loader constraint violation: when resolving method -'org.xnio.XnioWorker io.undertow.server.ServerConnection.getWorker()' - -Class loader conflict: -- 'deployment.staging.war' @321cfd96 (WAR deployment) -- '[email protected]' @6aa6b375 (WildFly module) -- Different Class objects for org/xnio/XnioWorker -</pre> - -<p><strong>What Went Wrong</strong>: The integration classes tried to bridge WAR-deployed Axis2 code with WildFly's modular classloader system, but this was a symptom of the deeper architectural mismatch, not the root cause.</p> - -<h3>2. Axis2ServletExtension Integration Failure</h3> - -<p><strong>Problem</strong>: Created `org.apache.axis2.transport.h2.integration.Axis2ServletExtension$DeferredAxis2Handler` to integrate with WildFly's servlet extension mechanism:</p> - -<pre> -public class Axis2ServletExtension implements ServletExtension { - @Override - public void handleDeployment(DeploymentInfo deploymentInfo, ServletContext servletContext) { - // Attempt to register custom handler that bridges Axis2 and Undertow - deploymentInfo.addInitialHandlerChainWrapper(new DeferredAxis2HandlerWrapper()); - } - - private class DeferredAxis2Handler implements HttpHandler { - @Override - public void handleRequest(HttpServerExchange exchange) throws Exception { - // FAILURE POINT: Cannot access Undertow classes from WAR classloader - XnioWorker worker = exchange.getConnection().getWorker(); // LinkageError here! - } - } -} -</pre> - -<p><strong>Fundamental Issue</strong>: WAR-deployed code cannot safely access WildFly module classes due to classloader isolation. The servlet extension approach requires deep integration that breaks module boundaries.</p> - -<h3>3. org.xnio Dependency Problems</h3> - -<p><strong>Dependencies That Failed</strong>:</p> -<ul> - <li><strong>org.xnio.XnioWorker</strong> - Core XNIO worker threads</li> - <li><strong>org.xnio.channels.StreamSinkChannel</strong> - Async I/O channels</li> - <li><strong>org.xnio.conduits.Conduit</strong> - Low-level I/O conduits</li> - <li><strong>io.undertow.server.HttpServerExchange</strong> - Request/response exchange objects</li> - <li><strong>io.undertow.server.ServerConnection</strong> - Connection management</li> -</ul> - -<p><strong>Module Isolation Problem</strong>: These classes are in WildFly's private module system and cannot be safely accessed from user deployments:</p> - -<pre> -WildFly Module System: -┌─────────────────────────────────────────────────────────┐ -│ WildFly Core Modules (private) │ -│ ├── org.xnio │ -│ ├── io.undertow.core │ -│ └── org.jboss.as.* │ -├─────────────────────────────────────────────────────────┤ -│ User Deployment (WAR) │ -│ ├── deployment.staging.war │ -│ └── Cannot access private modules safely │ -└─────────────────────────────────────────────────────────┘ -</pre> - -<h3>4. Configuration-Driven Integration Failures</h3> - -<p><strong>Attempted Configuration</strong>: Complex axis2.xml configuration that tried to bridge the two systems:</p> - -<pre> -<!-- FAILED: This caused LinkageError --> -<transportReceiver name="https" - class="org.apache.axis2.transport.h2.integration.UndertowAxis2TransportReceiver"> - <parameter name="enableHTTP2">true</parameter> - <parameter name="undertowIntegration">true</parameter> <!-- BROKEN --> - <parameter name="xnioWorkerThreads">10</parameter> <!-- BROKEN --> -</transportReceiver> - -<!-- FAILED: Non-existent classes referenced --> -<messageReceiver mep="http://www.w3.org/ns/wsdl/in-out"; - class="org.apache.axis2.json.moshih2.rpc.HTTP2StreamingJsonRpcMessageReceiver"/> -<messageReceiver mep="http://www.w3.org/ns/wsdl/in-only"; - class="org.apache.axis2.json.moshih2.rpc.HTTP2StreamingJsonInOnlyRPCMessageReceiver"/> -</pre> - -<p><strong>Result</strong>: ClassNotFoundException and LinkageError exceptions prevented system startup.</p> - -<h3>5. HTTP/2 Stream Management Conflicts</h3> - -<p><strong>Attempted Solution</strong>: Create shared HTTP/2 stream management between Axis2 and WildFly:</p> - -<pre> -public class HTTP2StreamCoordinator { - private XnioWorker undertowWorker; // FAILURE: Cannot access from WAR - private Http2Channel sharedChannel; // FAILURE: Not accessible - - public void coordinateStreams(MessageContext msgCtx) throws AxisFault { - try { - // Attempt to share Undertow's HTTP/2 streams with Axis2 - Http2StreamSourceChannel sourceChannel = - (Http2StreamSourceChannel) msgCtx.getProperty("HTTP_CHANNEL"); // NULL - - // Try to get Undertow worker from current exchange - HttpServerExchange exchange = getCurrentExchange(); // LinkageError! - this.undertowWorker = exchange.getConnection().getWorker(); - } catch (Exception e) { - // Integration impossible due to classloader isolation - throw new AxisFault("Cannot coordinate HTTP/2 streams", e); - } - } -} -</pre> - -<p><strong>Why It Failed</strong>: No safe way to share HTTP/2 stream objects between WildFly's module system and WAR-deployed Axis2 code.</p> - -<h2>Lessons Learned and Strategic Pivot</h2> - -<h3>1. Architectural Mismatch: Container vs Application Layer Processing</h3> - -<p><strong>Critical Lesson</strong>: **Axis2's Axiom OMElement conversion must happen within the application layer**, not at the container level. WildFly HTTP/2 integration operates at the wrong abstraction level for Axis2's JSON processing requirements.</p> - -<p><strong>Decision</strong>: Abandoned container-level integration in favor of **application-layer optimization within Axis2's existing MessageBuilder/MessageFormatter architecture**.</p> - -<h3>2. JSON-to-OMElement Conversion is the Core Challenge</h3> - -<p><strong>Deep Insight</strong>: The real performance bottleneck was **JSON parsing and OMElement creation**, not HTTP/2 transport. Optimizing the JSON → XMLStreamReader → OMElement pipeline delivers greater benefits than transport-layer integration.</p> - -<p><strong>Strategic Shift</strong>: Focus optimization efforts on **Enhanced Moshi JSON processing with field-specific optimizations** rather than WildFly integration complexity.</p> - -<h3>3. Axis2 Architecture Requires Internal Optimization</h3> - -<p><strong>Key Realization</strong>: Axis2's performance improvements must work **within its existing processing pipeline**:</p> -<ul> - <li><strong>InputStream → JsonReader → XMLStreamReader → OMElement</strong></li> - <li><strong>Custom MessageBuilder implementations with async processing</strong></li> - <li><strong>Field-specific parsing optimizations within XMLStreamReader</strong></li> - <li><strong>Memory management at OMElement creation level</strong></li> -</ul> - -<p><strong>Solution Path</strong>: Create enhanced JSON processing components that **optimize within Axis2's architecture** rather than bypassing it.</p> - -<h3>4. Focus Shift to Enhanced Moshi H2 Development</h3> - -<p><strong>Key Insight</strong>: The performance research identified that <strong>JSON processing and OMElement conversion</strong> was the actual bottleneck, not HTTP/2 transport layer integration.</p> - -<p><strong>Strategic Pivot</strong>: Instead of fighting WildFly integration complexity, focus optimization efforts on <strong>JSON parsing and generation</strong> where Axis2 has full control.</p> - -<h2>Positive Outcome: Enhanced Moshi H2 Development</h2> - -<h3>Salvaged Concepts and Ideas</h3> - -<p><strong>What We Learned from the Failed Integration</strong>:</p> - -<ol> - <li><strong>Async Processing Patterns</strong>: HTTP/2 integration research revealed async processing benefits that were applied to JSON processing</li> - <li><strong>Buffer Management Techniques</strong>: WildFly buffer optimization concepts were adapted for JSON streaming</li> - <li><strong>Performance Monitoring Approaches</strong>: Integration monitoring concepts became JSON processing metrics</li> - <li><strong>Configuration-Based Activation</strong>: Runtime detection patterns became JSON optimization activation logic</li> - <li><strong>Memory Pressure Management</strong>: WildFly memory management concepts applied to large JSON payload handling</li> -</ol> - -<h3>Enhanced Moshi H2 as the Solution</h3> - -<p><strong>Enhanced Moshi H2 solved the core Axiom integration problem by optimizing JSON-to-OMElement conversion within Axis2's architecture</strong>:</p> - -<p><strong>How it Solves the Fundamental Issue</strong>:</p> -<ul> - <li><strong>Works within MessageBuilder architecture</strong> - No bypassing of Axis2's processing pipeline</li> - <li><strong>Direct JSON → OMElement optimization</strong> - Targets the actual performance bottleneck</li> - <li><strong>Enhanced XMLStreamReader with field-specific parsing</strong> - IDs, amounts, dates, arrays</li> - <li><strong>Async processing within OMElement creation</strong> - Prevents 12-18s blocking behavior</li> - <li><strong>Portable solution</strong> - No WildFly dependencies, works in any servlet container</li> -</ul> - -<pre> -// Concepts salvaged from WildFly integration research: -public class EnhancedMoshiJsonBuilder { - // Async processing patterns from HTTP/2 integration attempts - private CompletableFuture<OMElement> processLargePayloadAsync(InputStream inputStream) { - return CompletableFuture.supplyAsync(() -> { - // Apply buffer management lessons from WildFly integration - return processWithEnhancedMoshi(inputStream, messageContext, strategy, requestId); - }, asyncExecutor); - } - - // Memory management from WildFly buffer optimization research - private void optimizeMemoryUsage(long payloadSize) { - if (payloadSize > memoryOptimizationThreshold) { - // Apply GC hints learned from WildFly integration - System.gc(); // Strategic GC suggestion - } - } -} -</pre> - -<h3>Performance Benefits Achieved</h3> - -<p><strong>Enhanced Moshi H2 delivers the performance improvements originally sought from WildFly integration</strong>:</p> - -<ul> - <li><strong>40-60% JSON processing improvement</strong> for large payloads (>1MB)</li> - <li><strong>Async processing prevents blocking</strong> (eliminates 12-18s stalls)</li> - <li><strong>Field-specific optimizations</strong> for IDs, amounts, dates, arrays</li> - <li><strong>Memory management with GC optimization</strong></li> - <li><strong>Performance metrics and monitoring</strong></li> - <li><strong>Intelligent payload analysis</strong> and processing strategy selection</li> -</ul> - -<h3>Superior Approach</h3> - -<p><strong>Enhanced Moshi H2 is actually better than WildFly integration would have been</strong>:</p> - -<table border="1"> -<tr><th>Aspect</th><th>Failed WildFly Integration</th><th>Enhanced Moshi H2</th></tr> -<tr><td><strong>Compatibility</strong></td><td>❌ WildFly-only</td><td>✅ Universal (Tomcat, Jetty, standalone)</td></tr> -<tr><td><strong>Deployment</strong></td><td>❌ Complex configuration</td><td>✅ Simple axis2.xml changes</td></tr> -<tr><td><strong>Maintenance</strong></td><td>❌ WildFly version coupling</td><td>✅ Independent of app server</td></tr> -<tr><td><strong>Performance</strong></td><td>⚠️ 15-25% improvement</td><td>✅ 40-60% improvement</td></tr> -<tr><td><strong>Risk</strong></td><td>❌ ClassLoader conflicts</td><td>✅ Zero breaking changes</td></tr> -</table> - -<h2>Conclusion: Architectural Understanding Led to Superior Solution</h2> - -<p><strong>The WildFly integration failure revealed fundamental architectural insights</strong> that led to a better solution:</p> - -<ol> - <li><strong>Identified the real bottleneck</strong>: mandatory <a href="json_support_gson.xml">dummy SOAP envelope</a> within Axis2, not HTTP/2 transport layer</li> - <li><strong>Recognized architectural mismatch</strong>: Container-level integration vs application-layer optimization requirements</li> - <li><strong>Understood Axiom integration needs</strong>: Performance improvements must work within MessageBuilder/MessageFormatter architecture</li> - <li><strong>Discovered portable optimization opportunities</strong>: Field-specific parsing, async processing, memory management within OMElement creation</li> - <li><strong>Achieved superior performance</strong>: 40-60% improvement by targeting the actual bottleneck</li> -</ol> +<h3>Deployment sizing</h3> -<p><strong>Critical Architectural Insight</strong>: **Axis2's JSON processing bottleneck is in the InputStream → JsonReader → XMLStreamReader → OMElement pipeline**, not in the HTTP transport layer. Optimizing at the correct architectural layer (MessageBuilder/MessageFormatter) delivers far greater benefits than container-level integration attempts.</p> - -<p><strong>Key Learning</strong>: The "elegant" container integration was architecturally wrong. **Understanding where performance optimization should occur in the software stack** is more valuable than sophisticated container integration. Enhanced Moshi H2's success proves that **working within existing architecture** often outperforms **bypassing architecture**.</p> - -<p><strong>For the Axis2 Community</strong>: This demonstrates how architectural analysis of failed integration attempts can reveal the correct optimization approach. The WildFly integration research identified the real architectural mismatch (mandatory <a href="json_support_gson.xml">dummy SOAP envelope</a>) and provided the async processing patterns that made Enhanced Moshi H2 possible, delivering superior JSON performance improvements through architectural alignment rather than integr [...] - -<h2>WildFly 32 Configuration Corrections Summary</h2> - -<p><strong>🔧 KEY CORRECTIONS MADE</strong> - The guide has been updated to accurately reflect WildFly 32 requirements:</p> - -<h3>1. Critical Issues Fixed</h3> <table border="1"> -<tr><th>Issue</th><th>Previous (Incorrect)</th><th>Corrected for WildFly 32</th><th>Impact</th></tr> -<tr> - <td><strong>Buffer Sizes</strong></td> - <td>Misaligned buffer sizes (2KB vs 64KB)</td> - <td>Aligned at 32KB across all layers</td> - <td>✅ Eliminates memory fragmentation</td> -</tr> -<tr> - <td><strong>SSL Context Name</strong></td> - <td><code>ssl-context="applicationSSL"</code></td> - <td><code>ssl-context="applicationSSC"</code></td> - <td>✅ Matches your existing WildFly config</td> -</tr> -<tr> - <td><strong>Missing HTTP/2 Parameters</strong></td> - <td>Only <code>enable-http2="true"</code></td> - <td>Full HTTP/2 tuning parameters added</td> - <td>✅ Enables proper HTTP/2 optimization</td> -</tr> -<tr> - <td><strong>Namespace Version</strong></td> - <td>Generic examples</td> - <td>WildFly 32 specific namespace and attributes</td> - <td>✅ Configuration compatibility</td> -</tr> +<tr><th>Environment</th><th>Memory</th><th>Configuration</th></tr> +<tr><td>Memory-constrained</td><td>≤ 2GB</td><td>32KB buffers, 50 streams</td></tr> +<tr><td>Balanced production</td><td>2-4GB</td><td>64KB buffers, 100 streams</td></tr> +<tr><td>High-performance</td><td>4GB+</td><td>64KB+ buffers, 200+ streams</td></tr> </table> -<h3>2. Performance Optimizations Added</h3> -<ul> - <li><strong>Buffer Pool Alignment</strong>: <code>byte-buffer-pool buffer-size="32768"</code> matches <code>http2-max-frame-size="32768"</code></li> - <li><strong>Connection Limits</strong>: <code>max-connections="200"</code> matches your existing setup</li> - <li><strong>Timeout Coordination</strong>: <code>no-request-timeout="300000"</code> aligned across layers</li> - <li><strong>HTTP/2 Frame Optimization</strong>: Proper frame sizes for large JSON payloads</li> -</ul> - -<h3>3. Next Steps for Your Environment</h3> -<p><strong>To apply these optimizations to your WildFly 32 configuration</strong>:</p> - -<ol> - <li><strong>Update Buffer Sizes</strong>: Change <code>buffer-size="2048"</code> to <code>buffer-size="32768"</code> in your standalone.xml</li> - <li><strong>Add HTTP/2 Parameters</strong>: Add the missing <code>http2-*</code> parameters to your listeners</li> - <li><strong>Verify SSL Context</strong>: Ensure <code>ssl-context="applicationSSC"</code> matches your configuration</li> - <li><strong>Deploy Enhanced Moshi H2</strong>: Use the corrected buffer alignment in axis2.xml</li> - <li><strong>Monitor Performance</strong>: Enable HTTP/2 access logging to verify protocol negotiation</li> -</ol> - -<p><strong>Expected Results</strong>: With these corrections, you should see 40-60% improvement in JSON processing performance for large payloads while maintaining memory efficiency in your 2GB heap environment.</p> - </body> </document> diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml index 2f614368d6..6872c887c8 100644 --- a/src/site/xdoc/index.xml +++ b/src/site/xdoc/index.xml @@ -83,6 +83,13 @@ JSON-RPC, REST, and MCP traffic. See the <a href="docs/openapi-rest-userguide.html">OpenAPI 3.0 auto-generation</a> with Swagger UI, and <a href="docs/json-rpc-mcp-guide.html">MCP tool catalogs</a> for AI agents. +<a href="docs/http2-integration-guide.html">HTTP/2 support</a> is built into +the serialization pipeline — streaming JSON formatters flush every 64 KB, +converting buffered responses into HTTP/2 DATA frames during serialization, +not after. Response field selection (<code>?fields=</code>) filters at the +serialization layer with zero overhead when unused. Most frameworks treat +HTTP/2 as a transparent container feature; Axis2 integrates it into the +message formatter. Legacy SOAP services continue to work unchanged — the SOAP handler chain, WS-Security (<a href="http://axis.apache.org/axis2/java/rampart/";>Apache Rampart</a>), and WS-Addressing are fully supported.</p>
