You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ro...@apache.org on 2026/05/11 12:49:58 UTC
(axis-axis2-java-core) 04/06: docs: Remove non-existent HTTP/2 configuration properties from xdoc
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 c3084075f3bbfbca2751243edb716e5a311333d2
Author: Robert Lazarski <ro...@gmail.com>
AuthorDate: Sun May 10 14:45:41 2026 -1000
docs: Remove non-existent HTTP/2 configuration properties from xdoc
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) <no...@anthropic.com>
---
src/site/xdoc/docs/http2-integration-guide.xml | 20 +++----
src/site/xdoc/docs/http2-transport-additions.xml | 46 ++++++----------
.../docs/openapi-rest-advanced-http2-userguide.xml | 61 ++++++----------------
3 files changed, 43 insertions(+), 84 deletions(-)
diff --git a/src/site/xdoc/docs/http2-integration-guide.xml b/src/site/xdoc/docs/http2-integration-guide.xml
index ae62f203a8..e6b965b949 100644
--- 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
index de54bfe23f..bbbfb370ab 100644
--- 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>
-<service name="BigDataService">
- <parameter name="preferredTransport">h2</parameter>
- <parameter name="enableHTTP2">true</parameter>
- <parameter name="enableStreaming">true</parameter>
- <parameter name="maxPayloadSize">104857600</parameter> <!-- 100MB -->
- <parameter name="streamingThreshold">52428800</parameter> <!-- 50MB -->
-</service>
-</pre>
+<p>HTTP/2 is enabled at the transport level in axis2.xml, not per-service.
+Select the H2TransportSender in the <code><transportSender></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
index 4733685118..06163eeab1 100644
--- 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
<display-name>High-Performance OpenAPI + HTTP/2 Service</display-name>
- <!-- Axis2 Servlet with HTTP/2 Support -->
+ <!-- Axis2 Servlet (HTTP/2 is configured in axis2.xml, not here) -->
<servlet>
<servlet-name>AxisServlet</servlet-name>
<servlet-class>org.apache.axis2.transport.http.AxisServlet</servlet-class>
- <init-param>
- <param-name>enableHTTP2</param-name>
- <param-value>true</param-value>
- </init-param>
<load-on-startup>1</load-on-startup>
</servlet>
@@ -329,16 +324,10 @@ low overhead and simplified deployment, making it an excellent choice for high-p
<!-- axis2.xml - Tomcat 11 + HTTP/2 + OpenAPI Optimized Configuration -->
<axisconfig name="AxisJava2.0-Tomcat11-HTTP2-OpenAPI">
- <!-- Tomcat HTTP/2 Integration Parameters -->
- <parameter name="TomcatHttp2Integration">true</parameter>
- <parameter name="TomcatBufferAlignment">65536</parameter> <!-- Match http2MaxFrameSize -->
- <parameter name="TomcatStreamAlignment">200</parameter> <!-- Match maxConcurrentStreams -->
- <parameter name="TomcatCompressionOptimization">true</parameter> <!-- Leverage Tomcat compression -->
-
- <!-- OpenAPI Configuration for HTTP/2 -->
- <parameter name="OpenApiHttp2Enabled">true</parameter>
- <parameter name="OpenApiSpecCacheTimeout">300</parameter> <!-- 5 minutes -->
- <parameter name="OpenApiLargeSpecThreshold">1048576</parameter> <!-- 1MB threshold -->
+ <!-- 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. -->
<!-- HTTP/2 Transport Sender -->
<transportSender name="h2"
@@ -378,28 +367,14 @@ low overhead and simplified deployment, making it an excellent choice for high-p
<display-name>Enterprise OpenAPI + HTTP/2 on Tomcat 11</display-name>
- <!-- Context Parameters for HTTP/2 + OpenAPI -->
- <context-param>
- <param-name>axis2.http2.enabled</param-name>
- <param-value>true</param-value>
- </context-param>
- <context-param>
- <param-name>openapi.http2.optimization</param-name>
- <param-value>true</param-value>
- </context-param>
-
- <!-- Axis2 Servlet with Tomcat HTTP/2 Support -->
+ <!-- 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. -->
+
+ <!-- Axis2 Servlet -->
<servlet>
<servlet-name>AxisServlet</servlet-name>
<servlet-class>org.apache.axis2.transport.http.AxisServlet</servlet-class>
- <init-param>
- <param-name>enableHTTP2</param-name>
- <param-value>true</param-value>
- </init-param>
- <init-param>
- <param-name>tomcatHttp2Integration</param-name>
- <param-value>true</param-value>
- </init-param>
<load-on-startup>1</load-on-startup>
<async-supported>true</async-supported>
</servlet>
@@ -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"