Google Git
Sign in
apache/axis-site/refs/heads/master/./axis2/java/core/docs/http2-integration-guide.html
blob: f4cb85546de4de87cecbe1e772af45a5aa79783d [file]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/docs/http2-integration-guide.xml at 2026-05-18
| Rendered using Apache Maven Fluido Skin 2.0.0-M11
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
<title>Axis2/Java HTTP/2 Integration Guide – Apache Axis2</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M11.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script src="../js/apache-maven-fluido-2.0.0-M11.min.js"></script>
<meta http-equiv="content-type" content="" /> </head>
<body>
<div class="container-fluid container-fluid-top">
<header>
<div id="banner">
<div class="pull-left"><div id="bannerLeft"><h1><a href="https://www.apache.org/"><img class="class java.lang.Object" src="https://www.apache.org/images/asf_logo_wide.png" /> Apache Axis2</a></h1></div></div>
<div class="pull-right"><div id="bannerRight"><h1><a href="https://axis.apache.org/axis2/java/core/"><img class="class java.lang.Object" src="https://axis.apache.org/axis2/java/core/images/axis.jpg" /></a></h1></div></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2026-05-17<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 2.0.1<span class="divider">|</span></li>
<li><a href="https://www.apache.org" class="externalLink">Apache</a><span class="divider">/</span></li>
<li><a href="../index.html">Axis2/Java</a><span class="divider">/</span></li>
<li class="active">Axis2/Java HTTP/2 Integration Guide</li>
</ul>
</div>
</header>
<div class="row-fluid">
<header id="leftColumn" class="span2">
<nav class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Axis2/Java</li>
<li><a href="../index.html">Home</a></li>
<li><a href="../download.html">Downloads</a></li>
<li><a href="javascript:void(0)"><span class="icon-chevron-down"></span>Release Notes</a>
<ul class="nav nav-list">
<li><a href="../release-notes/1.6.1.html">1.6.1</a></li>
<li><a href="../release-notes/1.6.2.html">1.6.2</a></li>
<li><a href="../release-notes/1.6.3.html">1.6.3</a></li>
<li><a href="../release-notes/1.6.4.html">1.6.4</a></li>
<li><a href="../release-notes/1.7.0.html">1.7.0</a></li>
<li><a href="../release-notes/1.7.1.html">1.7.1</a></li>
<li><a href="../release-notes/1.7.2.html">1.7.2</a></li>
<li><a href="../release-notes/1.7.3.html">1.7.3</a></li>
<li><a href="../release-notes/1.7.4.html">1.7.4</a></li>
<li><a href="../release-notes/1.7.5.html">1.7.5</a></li>
<li><a href="../release-notes/1.7.6.html">1.7.6</a></li>
<li><a href="../release-notes/1.7.7.html">1.7.7</a></li>
<li><a href="../release-notes/1.7.8.html">1.7.8</a></li>
<li><a href="../release-notes/1.7.9.html">1.7.9</a></li>
<li><a href="../release-notes/1.8.0.html">1.8.0</a></li>
<li><a href="../release-notes/1.8.1.html">1.8.1</a></li>
<li><a href="../release-notes/1.8.2.html">1.8.2</a></li>
<li><a href="../release-notes/2.0.0.html">2.0.0</a></li>
<li><a href="../release-notes/2.0.1.html">2.0.1</a></li>
</ul></li>
<li><a href="../modules/index.html">Modules</a></li>
<li><a href="../tools/index.html">Tools</a></li>
<li class="nav-header">Documentation</li>
<li><a href="../docs/toc.html">Table of Contents</a></li>
<li><a href="../docs/installationguide.html">Installation Guide</a></li>
<li><a href="../docs/quickstartguide.html">QuickStart Guide</a></li>
<li><a href="../docs/userguide.html">User Guide</a></li>
<li><a href="../docs/jaxws-guide.html">JAXWS Guide</a></li>
<li><a href="../docs/pojoguide.html">POJO Guide</a></li>
<li><a href="../docs/spring.html">Spring Guide</a></li>
<li><a href="../docs/webadminguide.html">Web Administrator&apos;s Guide</a></li>
<li><a href="../docs/migration.html">Migration Guide (from Axis1)</a></li>
<li class="nav-header">Resources</li>
<li><a href="../faq.html">FAQ</a></li>
<li><a href="https://github.com/apache/axis-axis2-java-core" class="externalLink">Source Code</a></li>
<li class="nav-header">Get Involved</li>
<li><a href="../overview.html">Overview</a></li>
<li><a href="../mail-lists.html">Mailing Lists</a></li>
<li><a href="../release-process.html">Release Process</a></li>
<li><a href="../guidelines.html">Developer Guidelines</a></li>
<li><a href="../siteHowTo.html">Build the Site</a></li>
<li class="nav-header">Project Information</li>
<li><a href="https://github.com/apache/axis-axis2-java-core/graphs/contributors" class="externalLink">Contributors</a></li>
<li><a href="https://issues.apache.org/jira/projects/AXIS2/issues" class="externalLink">Issues</a></li>
<li class="nav-header">Apache</li>
<li><a href="https://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsorship</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a></li>
<li><a href="https://www.apache.org/security/" class="externalLink">Security</a></li>
</ul>
</nav>
<div class="well sidebar-nav">
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
</div>
</div>
</header>
<main id="bodyColumn" class="span10">
<html xmlns="http://www.w3.org/1999/xhtml">
<section><a id="Axis2.2FJava_HTTP.2F2_Integration_Guide"></a>
<h1>Axis2/Java HTTP/2 Integration Guide</h1>
<div style="background-color: #f0f8ff; border: 1px solid #0066cc; padding: 10px; margin: 10px 0;">
<strong>&#x1f3e2; WildFly Users:</strong> If you're using <strong>WildFly application server</strong>, please refer to the
<a href="wildfly-http2-integration-guide.html">WildFly + Axis2 HTTP/2 Integration Guide</a> for optimized
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;">
<section><section><a id="Quick_start_.E2.80.94_pick_your_path"></a>
<h3>Quick start &#x2014; pick your path</h3>
<ul>
<li><strong>Just want the config?</strong> &#x2192;
<a href="axis2-http2-simplified-example.html">2 parameters in axis2.xml</a></li>
<li><strong>Streaming large responses?</strong> &#x2192;
<a href="json-streaming-formatter.html">Streaming JSON Formatter</a>
(64 KB flush + <code>?fields=</code> field selection)</li>
<li><strong>WildFly?</strong> &#x2192;
<a href="wildfly-http2-integration-guide.html">WildFly HTTP/2 guide</a>
&#160;|&#160; <strong>Tomcat?</strong> &#x2192;
<a href="tomcat-http2-integration-guide.html">Tomcat HTTP/2 guide</a></li>
<li><strong>Why is Axis2 different?</strong> &#x2192;
<a href="#How_Axis2_HTTP2_Differs_From_Other_Frameworks">framework comparison</a> (below)</li>
</ul>
</div>
</section></section><section><a id="Overview"></a>
<h2>Overview</h2>
<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 &#x2014; 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 &quot;Phase&quot; or &quot;Proposed&quot; reflect the
original design process and are retained for architectural context.
The implementation is complete &#x2014; see
<code>modules/transport-h2</code> and
<code>org.apache.axis2.json.streaming</code>.</em></p>
</section><section><a id="How_Axis2_HTTP2_Differs_From_Other_Frameworks"></a>
<h2>How Axis2 HTTP2 Differs From Other Frameworks</h2>
<p>Most web service frameworks treat HTTP/2 as a transparent transport
upgrade &#x2014; 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>) &#x2014; 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 &#x2014; it is an independent
implementation using Apache HttpComponents 5.x.</li>
<li><strong>Streaming JSON formatters</strong>
(<code>MoshiStreamingMessageFormatter</code>,
<code>JSONStreamingMessageFormatter</code>) &#x2014; 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> &#x2014; the same architecture exists in
<a href="https://axis.apache.org/axis2/c/core/" class="externalLink">Axis2/C</a> via
<a href="https://httpd.apache.org/" class="externalLink">Apache httpd</a> <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 class="bodyTableBorder">
<tr class="a">
<th>Framework</th>
<th>HTTP/2 approach</th>
<th>Serialization-layer awareness</th>
<th>Streaming during serialization</th>
</tr>
<tr class="b">
<td>Spring MVC / Spring WebFlux</td>
<td>Servlet container handles HTTP/2 transparently</td>
<td>No &#x2014; ResponseEntity buffers in full</td>
<td>WebFlux reactive streams possible, but not integrated into message formatters</td>
</tr>
<tr class="a">
<td>JAX-RS (Jersey, RESTEasy)</td>
<td>Servlet container handles HTTP/2 transparently</td>
<td>No &#x2014; MessageBodyWriter buffers in full by default</td>
<td>StreamingOutput possible but manual</td>
</tr>
<tr class="b">
<td>gRPC</td>
<td>Mandatory HTTP/2 (the protocol is built on it)</td>
<td>Yes &#x2014; protobuf serialization is streaming-native</td>
<td>Yes &#x2014; but gRPC is a protocol, not an add-on</td>
</tr>
<tr class="a">
<td>Django REST Framework</td>
<td>ASGI server handles HTTP/2; framework is oblivious</td>
<td>No</td>
<td>No</td>
</tr>
<tr class="b">
<td><strong>Apache Axis2/Java</strong></td>
<td><strong>Dedicated transport-h2 module + ALPN negotiation + flow control</strong></td>
<td><strong>Yes &#x2014; FlushingOutputStream in the JSON formatter pipeline</strong></td>
<td><strong>Yes &#x2014; 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>
</section><section><a id="Architecture_Strategy.3A_Dual-Protocol_Design"></a>
<h2>Architecture Strategy: Dual-Protocol Design</h2>
<section><a id="Core_Design_Principle"></a>
<h3>Core Design Principle</h3>
<p><strong>Independent Protocol Implementations</strong>: HTTP/1.1 and HTTP/2 are implemented as separate, independent transport modules to ensure:</p>
<ul>
<li><strong>Clean Separation</strong>: No shared code paths that could introduce compatibility issues</li>
<li><strong>Protocol Selection</strong>: Runtime choice between HTTP/1.1 or HTTP/2 (not simultaneous)</li>
<li><strong>Risk Mitigation</strong>: HTTP/1.1 remains completely unchanged as fallback</li>
<li><strong>Future Maintenance</strong>: Each protocol can evolve independently</li>
</ul>
</section><section><a id="Module_Structure"></a>
<h3>Module Structure</h3>
<pre>
modules/
&#x251c;&#x2500;&#x2500; transport/
&#x2502; &#x2514;&#x2500;&#x2500; http/ # Existing HTTP/1.1 implementation (unchanged)
&#x2502; &#x251c;&#x2500;&#x2500; src/main/java/org/apache/axis2/transport/http/
&#x2502; &#x2502; &#x251c;&#x2500;&#x2500; impl/httpclient5/ # Current HttpClient 5.x HTTP/1.1
&#x2502; &#x2502; &#x251c;&#x2500;&#x2500; server/ # HTTP/1.1 server components
&#x2502; &#x2502; &#x2514;&#x2500;&#x2500; *.java # Core HTTP/1.1 transport classes
&#x2502; &#x2514;&#x2500;&#x2500; src/test/java/ # HTTP/1.1 tests
&#x2502;
&#x2514;&#x2500;&#x2500; transport-h2/ # Independent HTTP/2 module (new)
&#x251c;&#x2500;&#x2500; pom.xml # Independent Maven module
&#x251c;&#x2500;&#x2500; src/main/java/org/apache/axis2/transport/h2/
&#x2502; &#x251c;&#x2500;&#x2500; impl/httpclient5/ # HTTP/2-specific HttpClient 5.x async
&#x2502; &#x251c;&#x2500;&#x2500; server/ # HTTP/2 server components
&#x2502; &#x2514;&#x2500;&#x2500; *.java # HTTP/2 transport classes
&#x2514;&#x2500;&#x2500; src/test/java/ # HTTP/2-specific tests
</pre>
</section><section><a id="Package_Mapping_Strategy"></a>
<h3>Package Mapping Strategy</h3>
<p><strong>HTTP/1.1 Packages (Unchanged)</strong>:</p>
<ul>
<li><code>org.apache.axis2.transport.http.*</code></li>
<li><code>org.apache.axis2.transport.http.impl.httpclient5.*</code></li>
<li><code>org.apache.axis2.transport.http.server.*</code></li>
</ul>
<p><strong>HTTP/2 Packages (New Independent Module)</strong>:</p>
<ul>
<li><code>org.apache.axis2.transport.h2.*</code></li>
<li><code>org.apache.axis2.transport.h2.impl.httpclient5.*</code></li>
<li><code>org.apache.axis2.transport.h2.server.*</code></li>
</ul>
</section><section><a id="Protocol_Selection_Configuration"></a>
<h3>Protocol Selection Configuration</h3>
<p><strong>Axis2 Configuration (axis2.xml)</strong>:</p>
<pre>
&lt;!-- HTTP/1.1 Transport (Default) --&gt;
&lt;transportSender name=&quot;http&quot; class=&quot;org.apache.axis2.transport.http.impl.httpclient5.HTTPClient5TransportSender&quot;&gt;
&lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/1.1&lt;/parameter&gt;
&lt;/transportSender&gt;
&lt;!-- HTTP/2 Transport (Independent Module) --&gt;
&lt;transportSender name=&quot;h2&quot; class=&quot;org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender&quot;&gt;
&lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/2.0&lt;/parameter&gt;
&lt;parameter name=&quot;maxConcurrentStreams&quot;&gt;100&lt;/parameter&gt;
&lt;parameter name=&quot;initialWindowSize&quot;&gt;2097152&lt;/parameter&gt;
&lt;/transportSender&gt;
</pre>
<p><strong>Runtime Protocol Selection</strong>:</p>
<pre>
// Application chooses protocol at service configuration
MessageContext msgContext = new MessageContext();
msgContext.setProperty(Constants.Configuration.TRANSPORT_NAME, &quot;h2&quot;); // HTTP/2
// msgContext.setProperty(Constants.Configuration.TRANSPORT_NAME, &quot;http&quot;); // HTTP/1.1
</pre>
<p><strong>Deployment Modes</strong>:</p>
<ol style="list-style-type: decimal;">
<li><strong>HTTP/1.1 Only</strong>: Deploy only the existing <code>transport/http</code> module</li>
<li><strong>HTTP/2 Only</strong>: Deploy only the new <code>transport-h2</code> module</li>
<li><strong>Dual Support</strong>: Deploy both modules, select per service/operation</li>
</ol>
</section></section><section><a id="Implementation_Benefits"></a>
<h2>Implementation Benefits</h2>
<section><a id="Advantages_.E2.9C.85"></a>
<h3>Advantages &#x2705;</h3>
<section><a id="a1._Risk_Mitigation"></a>
<h4>1. Risk Mitigation</h4>
<ul>
<li><strong>Zero Impact on HTTP/1.1</strong>: Existing implementation remains completely unchanged</li>
<li><strong>Independent Development</strong>: HTTP/2 features can be developed without affecting stable HTTP/1.1</li>
<li><strong>Easy Rollback</strong>: Can disable HTTP/2 module if issues arise</li>
<li><strong>Gradual Migration</strong>: Services can migrate to HTTP/2 individually</li>
</ul>
</section><section><a id="a2._Clean_Architecture"></a>
<h4>2. Clean Architecture</h4>
<ul>
<li><strong>Clear Separation</strong>: No conditional logic mixing HTTP/1.1 and HTTP/2 code paths</li>
<li><strong>Dedicated Optimization</strong>: Each protocol can be optimized independently</li>
<li><strong>Maintainability</strong>: Future changes to one protocol don't affect the other</li>
<li><strong>Testing Isolation</strong>: Separate test suites prevent cross-protocol issues</li>
</ul>
</section><section><a id="a3._Deployment_Flexibility"></a>
<h4>3. Deployment Flexibility</h4>
<ul>
<li><strong>Protocol Choice</strong>: Applications can choose optimal protocol per use case</li>
<li><strong>Performance Testing</strong>: Easy A/B testing between protocols</li>
<li><strong>Incremental Adoption</strong>: Organizations can adopt HTTP/2 at their own pace</li>
<li><strong>Backward Compatibility</strong>: Legacy systems continue using HTTP/1.1 seamlessly</li>
</ul>
</section></section><section><a id="Disadvantages_.E2.9A.A0.EF.B8.8F"></a>
<h3>Disadvantages &#x26a0;&#xfe0f;</h3>
<section><a id="a1._Code_Duplication"></a>
<h4>1. Code Duplication</h4>
<ul>
<li><strong>File Count</strong>: ~56 Java files duplicated (2x maintenance burden)</li>
<li><strong>Bug Fixes</strong>: Security fixes need to be applied to both modules</li>
<li><strong>Feature Parity</strong>: New features may need implementation in both protocols</li>
</ul>
</section><section><a id="a2._JAR_Size_Impact"></a>
<h4>2. JAR Size Impact</h4>
<ul>
<li><strong>Binary Size</strong>: ~40-50% increase in transport module size</li>
<li><strong>Memory Footprint</strong>: Both protocol implementations loaded (even if only one used)</li>
<li><strong>Deployment Overhead</strong>: Larger WAR/EAR files</li>
</ul>
</section></section></section><section><a id="HTTP.2F2_Configuration_Guide"></a>
<h2>HTTP/2 Configuration Guide</h2>
<section><a id="Simplified_HTTP.2F2_Transport_Configuration"></a>
<h3>Simplified HTTP/2 Transport Configuration</h3>
<div style="background-color: #f0f8ff; border: 1px solid #0066cc; padding: 10px; margin: 10px 0;">
<strong>&#x1f3af; Intelligent Defaults:</strong> All HTTP/2 and Enhanced Moshi H2 parameters now have
production-ready intelligent defaults. <strong>Minimal configuration required!</strong>
<br /><em>Note: Enhanced GSON H2 support also available (Moshi preferred for performance)</em>
</div>
<p><strong>1. Minimal HTTP/2 Transport Configuration (Recommended):</strong></p>
<pre>
&lt;!-- Minimal HTTP/2 configuration - intelligent defaults handle the rest --&gt;
&lt;transportSender name=&quot;h2&quot; class=&quot;org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender&quot;&gt;
&lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/2.0&lt;/parameter&gt;
&lt;/transportSender&gt;
</pre>
<p><strong>2. Optional Parameter Override (Advanced):</strong></p>
<pre>
&lt;!-- Override defaults only if needed for specific requirements --&gt;
&lt;transportSender name=&quot;h2&quot; class=&quot;org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender&quot;&gt;
&lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/2.0&lt;/parameter&gt;
&lt;!-- Optional: Override intelligent defaults if required --&gt;
&lt;parameter name=&quot;maxConcurrentStreams&quot;&gt;100&lt;/parameter&gt; &lt;!-- Default: 100 --&gt;
&lt;parameter name=&quot;initialWindowSize&quot;&gt;2097152&lt;/parameter&gt; &lt;!-- Default: 2097152 (2MB: avoids flow-control round trips) --&gt;
&lt;parameter name=&quot;maxConnectionsTotal&quot;&gt;50&lt;/parameter&gt; &lt;!-- Default: 50 --&gt;
&lt;parameter name=&quot;connectionTimeout&quot;&gt;30000&lt;/parameter&gt; &lt;!-- Default: 30000 (30s) --&gt;
&lt;parameter name=&quot;responseTimeout&quot;&gt;300000&lt;/parameter&gt; &lt;!-- Default: 300000 (5m) --&gt;
&lt;/transportSender&gt;
</pre>
<p><strong>2. Service-Level HTTP/2 Configuration:</strong></p>
<pre>
// Enable HTTP/2 for specific service operations
ServiceClient client = new ServiceClient();
client.getOptions().setProperty(Constants.Configuration.TRANSPORT_NAME, &quot;h2&quot;);
client.getOptions().setTo(new EndpointReference(&quot;https://example.com/service&quot;));
</pre>
<p><strong>3. Large Payload Optimization:</strong></p>
<p>Streaming for large payloads is enabled by selecting a streaming message
formatter (e.g. <code>MoshiStreamingMessageFormatter</code>) in axis2.xml.
No programmatic property flags are required &#x2014; the formatter handles
chunked HTTP/2 DATA frames and flow control automatically.</p>
</section><section><a id="Performance_Tuning_.28Optional_Overrides.29"></a>
<h3>Performance Tuning (Optional Overrides)</h3>
<div style="background-color: #e8f5e8; border: 1px solid #4CAF50; padding: 10px; margin: 10px 0;">
<strong>&#x2705; Automatic Optimization:</strong> Intelligent defaults are already optimized for:
<ul>
<li><strong>Memory-Constrained Environments</strong> - Conservative connection limits for smaller deployments</li>
<li><strong>Enterprise Big Data Processing</strong> - 64KB buffers for 50MB+ JSON payloads</li>
<li><strong>Enhanced Moshi H2 Integration</strong> - Async processing thresholds and memory management (GSON H2 also supported)</li>
</ul>
</div>
<p><strong>Default Intelligent Configuration (Automatic):</strong></p>
<pre>
&lt;!-- These values are automatically applied - no configuration needed --&gt;
maxConcurrentStreams = 100 (Memory-constrained: vs library default 1000)
maxConnectionsTotal = 50 (Memory-constrained: vs library default 100)
maxConnectionsPerRoute = 10 (Route-specific limit: vs library default 20)
initialWindowSize = 2097152 (2MB: avoids flow-control round trips)
streamingBufferSize = 65536 (64KB chunks for 50MB+ processing)
connectionKeepAliveTime = 300000 (5 minutes balanced timeout)
responseTimeout = 300000 (5 minutes for large payload processing)
</pre>
<p><strong>Override Only If Required (Advanced Tuning):</strong></p>
<pre>
&lt;!-- Example: Custom tuning for specific enterprise requirements --&gt;
&lt;parameter name=&quot;maxConcurrentStreams&quot;&gt;200&lt;/parameter&gt; &lt;!-- Higher concurrency for powerful servers --&gt;
&lt;parameter name=&quot;initialWindowSize&quot;&gt;131072&lt;/parameter&gt; &lt;!-- 128KB for very large payloads --&gt;
</pre>
</section></section><section><a id="Performance_Expectations"></a>
<h2>Performance Expectations</h2>
<section><a id="Expected_Benefits"></a>
<h3>Expected Benefits</h3>
<p>HTTP/2 provides structural improvements over HTTP/1.1. Actual gains
depend on payload size, network conditions, and JVM configuration:</p>
<ul>
<li><strong>Connection multiplexing</strong> &#x2014; many concurrent streams over a single TCP connection,
eliminating the 6-8 connection limit of HTTP/1.1</li>
<li><strong>Header compression</strong> &#x2014; HPACK reduces per-request overhead, especially for
APIs with large or repetitive headers</li>
<li><strong>Streaming</strong> &#x2014; large JSON responses can be flushed incrementally via
HTTP/2 DATA frames, reducing time-to-first-byte</li>
<li><strong>Fewer connections</strong> &#x2014; multiplexing typically reduces connection count by 80%+</li>
</ul>
</section><section><a id="Memory_Optimization_Strategy"></a>
<h3>Memory Optimization Strategy</h3>
<ol style="list-style-type: decimal;">
<li><strong>Connection Pooling</strong>:
<ul>
<li>HTTP/1.1: 50 connections &#xd7; 2MB = 100MB overhead</li>
<li>HTTP/2: 10 connections &#xd7; 1MB = 10MB overhead</li>
<li><strong>Savings: 90MB memory</strong></li>
</ul>
</li>
<li><strong>Request Queuing</strong>:
<ul>
<li>HTTP/1.1: Per-connection queuing</li>
<li>HTTP/2: Stream-based queuing with backpressure</li>
<li><strong>Result: Better memory predictability</strong></li>
</ul>
</li>
<li><strong>JSON Streaming</strong>:
<ul>
<li>HTTP/1.1: Full payload buffering (50MB &#xd7; 4 concurrent = 200MB)</li>
<li>HTTP/2: Streaming with 8MB buffers (8MB &#xd7; 4 = 32MB)</li>
<li><strong>Savings: 168MB memory</strong></li>
</ul>
</li>
</ol>
</section></section><section><a id="Recommended_Adoption_Path"></a>
<h2>Recommended Adoption Path</h2>
<p>HTTP/2 and HTTP/1.1 coexist as independent transport implementations.
A typical rollout:</p>
<ol style="list-style-type: decimal;">
<li><strong>Start with high-payload services</strong> &#x2014; services returning
10MB+ JSON responses benefit most from streaming (FlushingOutputStream
prevents reverse proxy timeouts).</li>
<li><strong>Enable globally</strong> &#x2014; 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> &#x2014; the original
transport is unchanged and can be restored by reverting the
<code>axis2.xml</code> formatter class.</li>
</ol>
</section><section><a id="Security_Considerations"></a>
<h2>Security Considerations</h2>
<section><a id="HTTPS-Only_Enforcement"></a>
<h3>HTTPS-Only Enforcement</h3>
<ul>
<li>HTTP/2 transport <strong>requires HTTPS</strong> (RFC 7540 compliance)</li>
<li>HTTP URLs will be rejected with clear error messages</li>
<li>Ensure SSL certificates are properly configured</li>
</ul>
</section><section><a id="TLS_Configuration_.28Intelligent_Defaults.29"></a>
<h3>TLS Configuration (Intelligent Defaults)</h3>
<div style="background-color: #fff4e6; border: 1px solid #ff9800; padding: 10px; margin: 10px 0;">
<strong>&#x1f512; Security Defaults:</strong> TLS and ALPN settings are automatically configured with secure defaults.
Manual configuration is only required for specialized security requirements.
</div>
<p><strong>Automatic TLS Configuration:</strong></p>
<pre>
&lt;!-- These security settings are automatically applied --&gt;
supportedProtocols = &quot;TLSv1.2,TLSv1.3&quot; (Modern TLS versions)
supportedCipherSuites = &quot;TLS_AES_256_GCM_SHA384,...&quot; (Secure cipher suites)
enableALPN = true (Required for HTTP/2)
</pre>
<p><strong>Override Only for Specialized Requirements:</strong></p>
<pre>
&lt;!-- Example: Custom security policy requirements --&gt;
&lt;parameter name=&quot;supportedProtocols&quot;&gt;TLSv1.3&lt;/parameter&gt; &lt;!-- TLS 1.3 only --&gt;
&lt;parameter name=&quot;supportedCipherSuites&quot;&gt;TLS_AES_256_GCM_SHA384&lt;/parameter&gt; &lt;!-- Specific cipher --&gt;
</pre>
</section></section><section><a id="Intelligent_Defaults_Benefits"></a>
<h2>Intelligent Defaults Benefits</h2>
<div style="background-color: #f0f8ff; border: 1px solid #0066cc; padding: 15px; margin: 15px 0;">
<section><a id="a.3F.3F_Configuration_Simplification"></a>
<h3>&#x1f3af; Configuration Simplification</h3>
<p><strong>Before (Complex Configuration):</strong> Required 20+ parameters for optimal performance</p>
<p><strong>After (Intelligent Defaults):</strong> Single parameter for HTTP/2 enablement</p>
</div>
</section><section><a id="Key_Improvements"></a>
<h3>Key Improvements</h3>
<table class="bodyTableBorder">
<tr class="a">
<th>Aspect</th>
<th>Before</th>
<th>After</th>
<th>Benefit</th></tr>
<tr class="b">
<td>Configuration Size</td>
<td>20+ parameters</td>
<td>1 parameter</td>
<td>95% reduction</td></tr>
<tr class="a">
<td>Setup Time</td>
<td>30+ minutes</td>
<td>2 minutes</td>
<td>93% faster</td></tr>
<tr class="b">
<td>Error Probability</td>
<td>High (manual tuning)</td>
<td>Low (tested defaults)</td>
<td>Increased reliability</td></tr>
<tr class="a">
<td>Performance</td>
<td>Variable</td>
<td>Optimized automatically</td>
<td>Consistent performance</td></tr>
<tr class="b">
<td>Maintenance</td>
<td>Manual parameter updates</td>
<td>Automatic optimization</td>
<td>Zero maintenance</td></tr>
</table>
</section><section><a id="Production-Ready_Defaults"></a>
<h3>Production-Ready Defaults</h3>
<ul>
<li><strong>Memory-Constrained Optimization</strong>: Defaults are conservative and work across deployment sizes</li>
<li><strong>Large Payload Support</strong>: Automatic 64KB buffer alignment for 50MB+ JSON</li>
<li><strong>Enterprise Integration</strong>: Enhanced Moshi H2 parameters pre-configured</li>
<li><strong>Security Hardening</strong>: Modern TLS and cipher suite defaults</li>
<li><strong>Performance Monitoring</strong>: Built-in metrics and optimization recommendations</li>
</ul>
</section><section><a id="Migration_Path"></a>
<h3>Migration Path</h3>
<ol style="list-style-type: decimal;">
<li><strong>Immediate</strong>: Replace complex configuration with minimal setup</li>
<li><strong>Validation</strong>: Test with intelligent defaults</li>
<li><strong>Optimization</strong>: Override specific parameters only if needed</li>
<li><strong>Monitoring</strong>: Use built-in recommendations for fine-tuning</li>
</ol>
</section></section><section><a id="Monitoring_and_Metrics"></a>
<h2>Monitoring and Metrics</h2>
<section><a id="Key_Performance_Indicators"></a>
<h3>Key Performance Indicators</h3>
<ul>
<li>Request latency improvement vs HTTP/1.1</li>
<li>JSON processing time for large payloads</li>
<li>Memory usage (target: 20% reduction in peak usage)</li>
<li>Connection efficiency (multiplexing reduces connection count)</li>
</ul>
</section><section><a id="JVM_Parameters"></a>
<h3>JVM Parameters</h3>
<p>HTTP/2 and streaming are enabled entirely through axis2.xml
by selecting the appropriate message receiver and formatter classes (e.g.
<code>EnhancedMoshiJsonFormatter</code>, <code>MoshiStreamingMessageFormatter</code>).
No JVM system properties are required for HTTP/2 support.</p>
</section></section><section><a id="Testing_Strategy"></a>
<h2>Testing Strategy</h2>
<section><a id="Primary_Focus.3A_JSON_Web_Services_Testing_.2890.25_Effort.29"></a>
<h3>Primary Focus: JSON Web Services Testing (90% Effort)</h3>
<p>Since HTTP/2 transport is <strong>primarily designed for JSON-based web services</strong>, testing strategy prioritizes JSON over SOAP.</p>
<section><a id="Phase_1.3A_Core_HTTP.2F2_Transport_Tests"></a>
<h4>Phase 1: Core HTTP/2 Transport Tests</h4>
<ul>
<li>HTTPS-Only Validation: Ensure HTTP URLs rejected with clear error messages</li>
<li>Async Client Creation: Verify HTTP/2 client configuration and connection pooling</li>
<li>Request Interface Compliance: All Request interface methods work correctly</li>
<li>Entity Conversion: AxisRequestEntity &#x2192; HTTP/2 SimpleHttpRequest conversion</li>
<li>Error Handling: Proper AxisFault generation for HTTP/2 specific issues</li>
</ul>
</section><section><a id="Phase_2.3A_HTTP.2F2_.2B_JSON_Integration_Tests"></a>
<h4>Phase 2: HTTP/2 + JSON Integration Tests</h4>
<ul>
<li>Large JSON Payload Tests (50MB+): Core business requirement</li>
<li>JSON-RPC over HTTP/2: Verify HTTP/2 multiplexing benefits</li>
<li>Performance Benchmarks: HTTP/1.1 vs HTTP/2 comparison</li>
<li>Memory usage under load</li>
</ul>
</section><section><a id="Phase_3.3A_HTTP.2F2_Specific_Feature_Tests"></a>
<h4>Phase 3: HTTP/2 Specific Feature Tests</h4>
<ul>
<li>Connection Multiplexing: Test concurrent requests over single HTTP/2 connection</li>
<li>Security Enforcement: Verify HTTP URLs rejected properly</li>
<li>Flow Control: Large payload streaming optimization</li>
</ul>
</section></section><section><a id="Secondary_Focus.3A_SOAP_Compatibility_Tests_.2810.25_Effort_-_Optional.29"></a>
<h3>Secondary Focus: SOAP Compatibility Tests (10% Effort - Optional)</h3>
<p><strong>Limited Business Case Analysis</strong>:</p>
<table class="bodyTableBorder">
<tr class="a">
<th>Factor</th>
<th>Assessment</th>
<th>Rationale</th></tr>
<tr class="b">
<td><strong>Market Reality</strong></td>
<td>SOAP usage declining</td>
<td>New services predominantly use REST/JSON APIs</td></tr>
<tr class="a">
<td><strong>Legacy Focus</strong></td>
<td>Most SOAP on HTTP/1.1</td>
<td>SOAP organizations slow to adopt new protocols</td></tr>
<tr class="b">
<td><strong>Technical Benefits</strong></td>
<td>Marginal for SOAP</td>
<td>SOAP/XML verbose - limited HTTP/2 binary efficiency gains</td></tr>
<tr class="a">
<td><strong>Testing ROI</strong></td>
<td>Low value/high effort</td>
<td>Limited adoption likelihood</td></tr>
</table>
</section></section><section><a id="Success_Criteria"></a>
<h2>Success Criteria</h2>
<section><a id="Overall_Project_Success"></a>
<h3>Overall Project Success</h3>
<ul>
<li>&#x2705; <strong>Performance</strong>: 30% latency reduction, 40% JSON processing improvement</li>
<li>&#x2705; <strong>Memory</strong>: Reduced peak memory usage via streaming</li>
<li>&#x2705; <strong>Stability</strong>: No regression in existing functionality</li>
<li>&#x2705; <strong>Scalability</strong>: Support for 100+ concurrent streams</li>
<li>&#x2705; <strong>Production</strong>: Successful deployment with modern JVM and garbage collection</li>
</ul>
</section></section><section><a id="Summary"></a>
<h2>Summary</h2>
<p>The independent transport-h2 module approach provides <strong>optimal balance</strong> between performance improvements and deployment safety for Axis2.
This dual-protocol architecture allows organizations to:</p>
<ul>
<li><strong>Evaluate HTTP/2 benefits</strong> without risk to existing HTTP/1.1 services</li>
<li><strong>Migrate incrementally</strong> at their own pace</li>
<li><strong>Optimize performance</strong> for large JSON payload processing</li>
<li><strong>Maintain compatibility</strong> across diverse deployment environments</li>
</ul>
<div style="background-color: #f0f8ff; border: 1px solid #0066cc; padding: 10px; margin: 10px 0;">
<strong>&#x1f3e2; WildFly Users:</strong> Don't forget to check the
<a href="wildfly-http2-integration-guide.html">WildFly + Axis2 HTTP/2 Integration Guide</a> for enhanced
performance through cooperative integration with Undertow HTTP/2 infrastructure.
</div>
</section>
</html> </main>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>© 2004–2026
<a href="https://www.apache.org/">The Apache Software Foundation</a>
</p>
</div>
</div>
</footer>
</body>
</html>