docs: Remove non-existent HTTP/2 configuration properties from xdoc

robertlazarski · claude · robertlazarski · commit c3084075f3bb · 2026-05-11T02:49:14.000-10:00
The HTTP/2 transport documentation contained numerous configuration
parameters that do not exist in the codebase — they were aspirational
examples that never had backing implementations. This causes user
confusion and wasted debugging when the properties have no effect.

Removed across 3 xdoc files:

- JVM system properties: -Daxis2.http2.enabled, -Daxis2.http2.streaming.enabled,
  -Daxis2.openapi.http2.enabled, -Daxis2.openapi.cache.enabled,
  -Daxis2.openapi.compression.enabled
- Servlet init-params: enableHTTP2, tomcatHttp2Integration
- Context-params: axis2.http2.enabled, openapi.http2.optimization
- Client Options properties: HTTP2_ENABLED, HTTP2_STREAMING_ENABLED,
  HTTP2_MEMORY_OPTIMIZATION, HTTP2_MULTIPLEXING_ENABLED,
  HTTP2_PROCESSING_MODE, HTTP2_PERFORMANCE_MONITORING,
  HTTP2_METRICS_COLLECTION
- axis2.xml parameters: TomcatHttp2Integration, TomcatBufferAlignment,
  TomcatStreamAlignment, TomcatCompressionOptimization,
  OpenApiHttp2Enabled, OpenApiSpecCacheTimeout,
  OpenApiLargeSpecThreshold
- openapi.properties: openapi.enterprise.http2.enabled,
  openapi.enterprise.streaming.enabled,
  openapi.enterprise.memory.optimization

Replaced with accurate guidance: HTTP/2 is enabled by selecting the
H2TransportSender in axis2.xml and the appropriate streaming message
formatter class. No boolean flags, system properties, or servlet
init-params are required.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/site/xdoc/docs/http2-integration-guide.xml b/src/site/xdoc/docs/http2-integration-guide.xml
@@ -107,7 +107,8 @@ itself</strong>, not just the transport layer.</p>
       (<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
+      <a href="https://axis.apache.org/axis2/c/core/">Axis2/C</a> via
+      <a href="https://httpd.apache.org/">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
@@ -330,13 +331,10 @@ client.getOptions().setTo(new EndpointReference("https://example.com/service"));
 </pre>
 
 <p><strong>3. Large Payload Optimization:</strong></p>
-<pre>
-// Configure for big data processing (50MB+ JSON)
-MessageContext msgContext = new MessageContext();
-msgContext.setProperty("HTTP2_STREAMING_ENABLED", true);
-msgContext.setProperty("HTTP2_MEMORY_OPTIMIZATION", true);
-msgContext.setProperty("FLOW_CONTROL_WINDOW_SIZE", 2097152); // 2MB
-</pre>
+<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 — the formatter handles
+chunked HTTP/2 DATA frames and flow control automatically.</p>
 
 <h3>Performance Tuning (Optional Overrides)</h3>
 
@@ -515,9 +513,11 @@ enableALPN = true                                          (Required for HTTP/2)
 <pre>
 -XX:+UseZGC                           # Low-latency garbage collector
 -XX:MaxDirectMemorySize=512m          # Direct memory for HTTP/2 buffers
--Daxis2.http2.enabled=true           # Enable HTTP/2 transport
--Daxis2.http2.streaming.enabled=true # Enable streaming for large payloads
 </pre>
+<p><em>Note:</em> 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.</p>
 
 <h2>Testing Strategy</h2>
 
diff --git a/src/site/xdoc/docs/http2-transport-additions.xml b/src/site/xdoc/docs/http2-transport-additions.xml
@@ -271,24 +271,15 @@ options.setProperty("MAX_CONCURRENT_STREAMS", 20);
   <li><strong>Streaming Mode</strong> (50MB+): Memory-efficient streaming with chunked processing</li>
 </ul>
 
-<pre>
-// Configure payload-specific processing
-Options options = new Options();
-options.setProperty("HTTP2_PROCESSING_MODE", "streaming"); // or "multiplexing", "standard"
-options.setProperty("HTTP2_MEMORY_OPTIMIZATION", Boolean.TRUE);
-options.setProperty("HTTP2_STREAMING_ENABLED", Boolean.TRUE);
-</pre>
+<p>Streaming and memory optimization are controlled by the message formatter
+selected in axis2.xml (e.g. <code>MoshiStreamingMessageFormatter</code>).
+No client-side <code>Options</code> properties are required — the transport
+sender negotiates HTTP/2 framing and flow control automatically.</p>
 
 <h3>Performance Monitoring</h3>
 
-<p>HTTP/2 transport provides comprehensive performance metrics:</p>
-
-<pre>
-// Enable performance monitoring
-Options options = new Options();
-options.setProperty("HTTP2_PERFORMANCE_MONITORING", Boolean.TRUE);
-options.setProperty("HTTP2_METRICS_COLLECTION", Boolean.TRUE);
-</pre>
+<p>HTTP/2 transport performance can be monitored via JMX or application-level
+logging.  Enable JMX in the JVM startup flags (see the JVM Tuning section).</p>
 
 <p>Available metrics include:</p>
 <ul>
@@ -356,15 +347,12 @@ for web-app use cases with predictable resource dependencies:</p>
 
 <p>Individual services can specify HTTP/2 preferences in their services.xml:</p>
 
-<pre>
-&lt;service name="BigDataService"&gt;
-   &lt;parameter name="preferredTransport"&gt;h2&lt;/parameter&gt;
-   &lt;parameter name="enableHTTP2"&gt;true&lt;/parameter&gt;
-   &lt;parameter name="enableStreaming"&gt;true&lt;/parameter&gt;
-   &lt;parameter name="maxPayloadSize"&gt;104857600&lt;/parameter&gt; &lt;!-- 100MB --&gt;
-   &lt;parameter name="streamingThreshold"&gt;52428800&lt;/parameter&gt; &lt;!-- 50MB --&gt;
-&lt;/service&gt;
-</pre>
+<p>HTTP/2 is enabled at the transport level in axis2.xml, not per-service.
+Select the H2TransportSender in the <code>&lt;transportSender&gt;</code> section
+and configure its parameters there.  For streaming large payloads, use the
+streaming message formatter (e.g. <code>MoshiStreamingMessageFormatter</code>
+or <code>JSONStreamingMessageFormatter</code>) in the service's message
+receiver configuration.  No service-level parameters are required.</p>
 
 <h3>Client-Side HTTP/2 Usage for SOAP (for JSON, see curl and Apache HTTPComponents section)</h3>
 
@@ -382,13 +370,11 @@ Options options = new Options();
 options.setProperty(HTTPConstants.TRANSPORT_NAME, "h2");
 options.setTo(new EndpointReference("https://localhost:8443/services/BigDataService"));
 
-// HTTP/2 specific configurations
-options.setProperty("HTTP2_ENABLED", Boolean.TRUE);
-options.setProperty("HTTP2_STREAMING_ENABLED", Boolean.TRUE);
-options.setProperty("HTTP2_MEMORY_OPTIMIZATION", Boolean.TRUE);
-options.setProperty("HTTP2_MULTIPLEXING_ENABLED", Boolean.TRUE);
+// HTTP/2 is negotiated by the transport sender selected in axis2.xml.
+// No additional boolean flags are needed — the h2 transport handles
+// multiplexing, streaming, and flow control automatically.
 
-// Performance settings for large payloads
+// Timeout settings for large payloads
 options.setTimeOutInMilliSeconds(300000); // 5 minutes
 options.setProperty(HTTPConstants.CONNECTION_TIMEOUT, 30000);
 options.setProperty(HTTPConstants.SO_TIMEOUT, 300000);
diff --git a/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml b/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml
@@ -113,15 +113,14 @@ openapi.title=High-Performance Trading API
 openapi.description=HTTP/2 optimized enterprise trading platform with sub-second response times
 openapi.version=2.0.0-h2
 
-# HTTP/2 Performance Optimizations
-openapi.prettyPrint=false                    # Reduce JSON size for HTTP/2 streaming
+# OpenAPI UI settings (standard Swagger UI properties)
+openapi.prettyPrint=false                    # Reduce JSON size
 openapi.swaggerUi.deepLinking=true          # Enable efficient navigation
 openapi.swaggerUi.filter=true               # Optimize large API browsing
-openapi.enterprise.http2.enabled=true       # Enable HTTP/2 specific optimizations
 
-# Large Payload Support
-openapi.enterprise.streaming.enabled=true   # Enable streaming for large responses
-openapi.enterprise.memory.optimization=true # Optimize memory for concurrent requests
+# Note: HTTP/2 transport and streaming are configured in axis2.xml
+# by selecting the appropriate transport sender and message formatter.
+# No openapi.properties flags are needed for HTTP/2.
 </pre>
 
 <h3>3. Service Configuration</h3>
@@ -200,14 +199,10 @@ This results in up to 50% additional performance improvements in WildFly deploym
 
     &lt;display-name&gt;High-Performance OpenAPI + HTTP/2 Service&lt;/display-name&gt;
 
-    &lt;!-- Axis2 Servlet with HTTP/2 Support --&gt;
+    &lt;!-- Axis2 Servlet (HTTP/2 is configured in axis2.xml, not here) --&gt;
     &lt;servlet&gt;
         &lt;servlet-name&gt;AxisServlet&lt;/servlet-name&gt;
         &lt;servlet-class&gt;org.apache.axis2.transport.http.AxisServlet&lt;/servlet-class&gt;
-        &lt;init-param&gt;
-            &lt;param-name&gt;enableHTTP2&lt;/param-name&gt;
-            &lt;param-value&gt;true&lt;/param-value&gt;
-        &lt;/init-param&gt;
         &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
     &lt;/servlet&gt;
 
@@ -329,16 +324,10 @@ low overhead and simplified deployment, making it an excellent choice for high-p
 &lt;!-- axis2.xml - Tomcat 11 + HTTP/2 + OpenAPI Optimized Configuration --&gt;
 &lt;axisconfig name="AxisJava2.0-Tomcat11-HTTP2-OpenAPI"&gt;
 
-    &lt;!-- Tomcat HTTP/2 Integration Parameters --&gt;
-    &lt;parameter name="TomcatHttp2Integration"&gt;true&lt;/parameter&gt;
-    &lt;parameter name="TomcatBufferAlignment"&gt;65536&lt;/parameter&gt;             &lt;!-- Match http2MaxFrameSize --&gt;
-    &lt;parameter name="TomcatStreamAlignment"&gt;200&lt;/parameter&gt;               &lt;!-- Match maxConcurrentStreams --&gt;
-    &lt;parameter name="TomcatCompressionOptimization"&gt;true&lt;/parameter&gt;     &lt;!-- Leverage Tomcat compression --&gt;
-
-    &lt;!-- OpenAPI Configuration for HTTP/2 --&gt;
-    &lt;parameter name="OpenApiHttp2Enabled"&gt;true&lt;/parameter&gt;
-    &lt;parameter name="OpenApiSpecCacheTimeout"&gt;300&lt;/parameter&gt;            &lt;!-- 5 minutes --&gt;
-    &lt;parameter name="OpenApiLargeSpecThreshold"&gt;1048576&lt;/parameter&gt;      &lt;!-- 1MB threshold --&gt;
+    &lt;!-- HTTP/2 is negotiated by the transport sender below.
+         Tomcat's HTTP/2 connector (h2c/h2) is configured in server.xml,
+         not in axis2.xml.  No Tomcat-specific or OpenAPI-specific
+         parameters are needed here. --&gt;
 
     &lt;!-- HTTP/2 Transport Sender --&gt;
     &lt;transportSender name="h2"
@@ -378,28 +367,14 @@ low overhead and simplified deployment, making it an excellent choice for high-p
 
     &lt;display-name&gt;Enterprise OpenAPI + HTTP/2 on Tomcat 11&lt;/display-name&gt;
 
-    &lt;!-- Context Parameters for HTTP/2 + OpenAPI --&gt;
-    &lt;context-param&gt;
-        &lt;param-name&gt;axis2.http2.enabled&lt;/param-name&gt;
-        &lt;param-value&gt;true&lt;/param-value&gt;
-    &lt;/context-param&gt;
-    &lt;context-param&gt;
-        &lt;param-name&gt;openapi.http2.optimization&lt;/param-name&gt;
-        &lt;param-value&gt;true&lt;/param-value&gt;
-    &lt;/context-param&gt;
-
-    &lt;!-- Axis2 Servlet with Tomcat HTTP/2 Support --&gt;
+    &lt;!-- HTTP/2 and streaming are configured in axis2.xml via message receiver
+         and formatter class selection, not via web.xml context-params.
+         See the axis2.xml HTTP/2 transport configuration section. --&gt;
+
+    &lt;!-- Axis2 Servlet --&gt;
     &lt;servlet&gt;
         &lt;servlet-name&gt;AxisServlet&lt;/servlet-name&gt;
         &lt;servlet-class&gt;org.apache.axis2.transport.http.AxisServlet&lt;/servlet-class&gt;
-        &lt;init-param&gt;
-            &lt;param-name&gt;enableHTTP2&lt;/param-name&gt;
-            &lt;param-value&gt;true&lt;/param-value&gt;
-        &lt;/init-param&gt;
-        &lt;init-param&gt;
-            &lt;param-name&gt;tomcatHttp2Integration&lt;/param-name&gt;
-            &lt;param-value&gt;true&lt;/param-value&gt;
-        &lt;/init-param&gt;
         &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
         &lt;async-supported&gt;true&lt;/async-supported&gt;
     &lt;/servlet&gt;
@@ -428,10 +403,8 @@ export CATALINA_OPTS="$CATALINA_OPTS -Djava.net.preferIPv6Addresses=false"
 export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.coyote.http2.Http2Protocol.maxConcurrentStreams=200"
 export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.coyote.http2.Http2Protocol.initialWindowSize=131072"
 
-# OpenAPI Optimization
-export CATALINA_OPTS="$CATALINA_OPTS -Daxis2.openapi.http2.enabled=true"
-export CATALINA_OPTS="$CATALINA_OPTS -Daxis2.openapi.cache.enabled=true"
-export CATALINA_OPTS="$CATALINA_OPTS -Daxis2.openapi.compression.enabled=true"
+# Note: Axis2 HTTP/2 and OpenAPI are configured in axis2.xml, not via
+# system properties.  No -Daxis2.* flags are needed.
 
 # Performance Monitoring
 export CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote"
