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 <[email protected]> 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) <[email protected]> --- 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"
