Axis2/Java HTTP/2 Integration Guide

🏢 WildFly Users: If you're using WildFly application server, please refer to the WildFly + Axis2 HTTP/2 Integration Guide for optimized configuration that provides enhanced performance through cooperative integration with Undertow.

Quick start — pick your path

Just want the config? → 2 parameters in axis2.xml
Streaming large responses? → Streaming JSON Formatter (64 KB flush + ?fields= field selection)
WildFly? → WildFly HTTP/2 guide | Tomcat? → Tomcat HTTP/2 guide
Why is Axis2 different? → framework comparison (below)

Overview

Apache Axis2/Java has native HTTP/2 support via a dedicated transport module (modules/transport-h2) built on Apache HttpComponents 5.x. The architecture supports both HTTP/1.1 and HTTP/2 as independent transport implementations, 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+).

Note: sections below titled "Phase" or "Proposed" reflect the original design process and are retained for architectural context. The implementation is complete — see modules/transport-h2 and org.apache.axis2.json.streaming.

How Axis2 HTTP2 Differs From Other Frameworks

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.

Axis2/Java takes a fundamentally different approach: HTTP/2 awareness is built into the serialization pipeline itself, not just the transport layer.

Dedicated HTTP/2 transport module (modules/transport-h2) — a standalone module with ALPN protocol negotiation (ALPNProtocolSelector), per-stream flow control (H2FlowControlManager, ProgressiveFlowControl), adaptive buffering (AdaptiveBufferManager), compression optimization (CompressionOptimizer), and HTTP/1.1 fallback (H2FallbackManager). This is not a wrapper around the servlet container's HTTP/2 — it is an independent implementation using Apache HttpComponents 5.x.
Streaming JSON formatters (MoshiStreamingMessageFormatter, JSONStreamingMessageFormatter) — flush every 64 KB via FlushingOutputStream, 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 (FieldFilteringMessageFormatter). See Streaming JSON Formatter.
C parity — the same architecture exists in Axis2/C via Apache httpd mod_h2 with ap_rflush() 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.

For comparison with other frameworks:

Framework	HTTP/2 approach	Serialization-layer awareness	Streaming during serialization
Spring MVC / Spring WebFlux	Servlet container handles HTTP/2 transparently	No — ResponseEntity buffers in full	WebFlux reactive streams possible, but not integrated into message formatters
JAX-RS (Jersey, RESTEasy)	Servlet container handles HTTP/2 transparently	No — MessageBodyWriter buffers in full by default	StreamingOutput possible but manual
gRPC	Mandatory HTTP/2 (the protocol is built on it)	Yes — protobuf serialization is streaming-native	Yes — but gRPC is a protocol, not an add-on
Django REST Framework	ASGI server handles HTTP/2; framework is oblivious	No	No
Apache Axis2/Java	Dedicated transport-h2 module + ALPN negotiation + flow control	Yes — FlushingOutputStream in the JSON formatter pipeline	Yes — 64 KB incremental flush, field filtering during serialization, C/Java parity

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.

Architecture Strategy: Dual-Protocol Design

Core Design Principle

Independent Protocol Implementations: HTTP/1.1 and HTTP/2 are implemented as separate, independent transport modules to ensure:

Clean Separation: No shared code paths that could introduce compatibility issues
Protocol Selection: Runtime choice between HTTP/1.1 or HTTP/2 (not simultaneous)
Risk Mitigation: HTTP/1.1 remains completely unchanged as fallback
Future Maintenance: Each protocol can evolve independently

Module Structure

modules/
├── transport/
│   └── http/          # Existing HTTP/1.1 implementation (unchanged)
│       ├── src/main/java/org/apache/axis2/transport/http/
│       │   ├── impl/httpclient5/     # Current HttpClient 5.x HTTP/1.1
│       │   ├── server/               # HTTP/1.1 server components
│       │   └── *.java               # Core HTTP/1.1 transport classes
│       └── src/test/java/           # HTTP/1.1 tests
│
└── transport-h2/      # Independent HTTP/2 module (new)
    ├── pom.xml         # Independent Maven module
    ├── src/main/java/org/apache/axis2/transport/h2/
    │   ├── impl/httpclient5/     # HTTP/2-specific HttpClient 5.x async
    │   ├── server/               # HTTP/2 server components
    │   └── *.java               # HTTP/2 transport classes
    └── src/test/java/           # HTTP/2-specific tests

Package Mapping Strategy

HTTP/1.1 Packages (Unchanged):

org.apache.axis2.transport.http.*
org.apache.axis2.transport.http.impl.httpclient5.*
org.apache.axis2.transport.http.server.*

HTTP/2 Packages (New Independent Module):

org.apache.axis2.transport.h2.*
org.apache.axis2.transport.h2.impl.httpclient5.*
org.apache.axis2.transport.h2.server.*

Protocol Selection Configuration

Axis2 Configuration (axis2.xml):

<!-- HTTP/1.1 Transport (Default) -->
<transportSender name="http" class="org.apache.axis2.transport.http.impl.httpclient5.HTTPClient5TransportSender">
    <parameter name="PROTOCOL">HTTP/1.1</parameter>
</transportSender>

<!-- HTTP/2 Transport (Independent Module) -->
<transportSender name="h2" class="org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender">
    <parameter name="PROTOCOL">HTTP/2.0</parameter>
    <parameter name="maxConcurrentStreams">100</parameter>
    <parameter name="initialWindowSize">2097152</parameter>
</transportSender>

Runtime Protocol Selection:

// Application chooses protocol at service configuration
MessageContext msgContext = new MessageContext();
msgContext.setProperty(Constants.Configuration.TRANSPORT_NAME, "h2");    // HTTP/2
// msgContext.setProperty(Constants.Configuration.TRANSPORT_NAME, "http"); // HTTP/1.1

Deployment Modes:

HTTP/1.1 Only: Deploy only the existing transport/http module
HTTP/2 Only: Deploy only the new transport-h2 module
Dual Support: Deploy both modules, select per service/operation

Implementation Benefits

Advantages ✅

1. Risk Mitigation

Zero Impact on HTTP/1.1: Existing implementation remains completely unchanged
Independent Development: HTTP/2 features can be developed without affecting stable HTTP/1.1
Easy Rollback: Can disable HTTP/2 module if issues arise
Gradual Migration: Services can migrate to HTTP/2 individually

2. Clean Architecture

Clear Separation: No conditional logic mixing HTTP/1.1 and HTTP/2 code paths
Dedicated Optimization: Each protocol can be optimized independently
Maintainability: Future changes to one protocol don't affect the other
Testing Isolation: Separate test suites prevent cross-protocol issues

3. Deployment Flexibility

Protocol Choice: Applications can choose optimal protocol per use case
Performance Testing: Easy A/B testing between protocols
Incremental Adoption: Organizations can adopt HTTP/2 at their own pace
Backward Compatibility: Legacy systems continue using HTTP/1.1 seamlessly

Disadvantages ⚠️

1. Code Duplication

File Count: ~56 Java files duplicated (2x maintenance burden)
Bug Fixes: Security fixes need to be applied to both modules
Feature Parity: New features may need implementation in both protocols

2. JAR Size Impact

Binary Size: ~40-50% increase in transport module size
Memory Footprint: Both protocol implementations loaded (even if only one used)
Deployment Overhead: Larger WAR/EAR files

HTTP/2 Configuration Guide

Simplified HTTP/2 Transport Configuration

🎯 Intelligent Defaults: All HTTP/2 and Enhanced Moshi H2 parameters now have production-ready intelligent defaults. Minimal configuration required!
Note: Enhanced GSON H2 support also available (Moshi preferred for performance)

1. Minimal HTTP/2 Transport Configuration (Recommended):

<!-- Minimal HTTP/2 configuration - intelligent defaults handle the rest -->
<transportSender name="h2" class="org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender">
    <parameter name="PROTOCOL">HTTP/2.0</parameter>
</transportSender>

2. Optional Parameter Override (Advanced):

<!-- Override defaults only if needed for specific requirements -->
<transportSender name="h2" class="org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender">
    <parameter name="PROTOCOL">HTTP/2.0</parameter>
    <!-- Optional: Override intelligent defaults if required -->
    <parameter name="maxConcurrentStreams">100</parameter>        <!-- Default: 100 -->
    <parameter name="initialWindowSize">2097152</parameter>       <!-- Default: 2097152 (2MB: avoids flow-control round trips) -->
    <parameter name="maxConnectionsTotal">50</parameter>          <!-- Default: 50 -->
    <parameter name="connectionTimeout">30000</parameter>        <!-- Default: 30000 (30s) -->
    <parameter name="responseTimeout">300000</parameter>         <!-- Default: 300000 (5m) -->
</transportSender>

2. Service-Level HTTP/2 Configuration:

// Enable HTTP/2 for specific service operations
ServiceClient client = new ServiceClient();
client.getOptions().setProperty(Constants.Configuration.TRANSPORT_NAME, "h2");
client.getOptions().setTo(new EndpointReference("https://example.com/service"));

3. Large Payload Optimization:

Streaming for large payloads is enabled by selecting a streaming message formatter (e.g. MoshiStreamingMessageFormatter) in axis2.xml. No programmatic property flags are required — the formatter handles chunked HTTP/2 DATA frames and flow control automatically.

Performance Tuning (Optional Overrides)

✅ Automatic Optimization: Intelligent defaults are already optimized for:

Memory-Constrained Environments - Conservative connection limits for smaller deployments
Enterprise Big Data Processing - 64KB buffers for 50MB+ JSON payloads
Enhanced Moshi H2 Integration - Async processing thresholds and memory management (GSON H2 also supported)

Default Intelligent Configuration (Automatic):

<!-- These values are automatically applied - no configuration needed -->
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)

Override Only If Required (Advanced Tuning):

<!-- Example: Custom tuning for specific enterprise requirements -->
<parameter name="maxConcurrentStreams">200</parameter>     <!-- Higher concurrency for powerful servers -->
<parameter name="initialWindowSize">131072</parameter>     <!-- 128KB for very large payloads -->

Performance Expectations

Expected Benefits

HTTP/2 provides structural improvements over HTTP/1.1. Actual gains depend on payload size, network conditions, and JVM configuration:

Connection multiplexing — many concurrent streams over a single TCP connection, eliminating the 6-8 connection limit of HTTP/1.1
Header compression — HPACK reduces per-request overhead, especially for APIs with large or repetitive headers
Streaming — large JSON responses can be flushed incrementally via HTTP/2 DATA frames, reducing time-to-first-byte
Fewer connections — multiplexing typically reduces connection count by 80%+

Memory Optimization Strategy

Connection Pooling:
- HTTP/1.1: 50 connections × 2MB = 100MB overhead
- HTTP/2: 10 connections × 1MB = 10MB overhead
- Savings: 90MB memory
Request Queuing:
- HTTP/1.1: Per-connection queuing
- HTTP/2: Stream-based queuing with backpressure
- Result: Better memory predictability
JSON Streaming:
- HTTP/1.1: Full payload buffering (50MB × 4 concurrent = 200MB)
- HTTP/2: Streaming with 8MB buffers (8MB × 4 = 32MB)
- Savings: 168MB memory

Recommended Adoption Path

HTTP/2 and HTTP/1.1 coexist as independent transport implementations. A typical rollout:

Start with high-payload services — services returning 10MB+ JSON responses benefit most from streaming (FlushingOutputStream prevents reverse proxy timeouts).
Enable globally — once validated, switch the axis2.xml formatter to FieldFilteringMessageFormatter (wraps the streaming Moshi formatter). All services benefit; small responses have zero overhead.
HTTP/1.1 fallback remains available — the original transport is unchanged and can be restored by reverting the axis2.xml formatter class.

Security Considerations

HTTPS-Only Enforcement

HTTP/2 transport requires HTTPS (RFC 7540 compliance)
HTTP URLs will be rejected with clear error messages
Ensure SSL certificates are properly configured

TLS Configuration (Intelligent Defaults)

🔒 Security Defaults: TLS and ALPN settings are automatically configured with secure defaults. Manual configuration is only required for specialized security requirements.

Automatic TLS Configuration:

<!-- These security settings are automatically applied -->
supportedProtocols = "TLSv1.2,TLSv1.3"                    (Modern TLS versions)
supportedCipherSuites = "TLS_AES_256_GCM_SHA384,..."       (Secure cipher suites)
enableALPN = true                                          (Required for HTTP/2)

Override Only for Specialized Requirements:

<!-- Example: Custom security policy requirements -->
<parameter name="supportedProtocols">TLSv1.3</parameter>  <!-- TLS 1.3 only -->
<parameter name="supportedCipherSuites">TLS_AES_256_GCM_SHA384</parameter> <!-- Specific cipher -->

Intelligent Defaults Benefits

🎯 Configuration Simplification

Before (Complex Configuration): Required 20+ parameters for optimal performance

After (Intelligent Defaults): Single parameter for HTTP/2 enablement

Key Improvements

Aspect	Before	After	Benefit
Configuration Size	20+ parameters	1 parameter	95% reduction
Setup Time	30+ minutes	2 minutes	93% faster
Error Probability	High (manual tuning)	Low (tested defaults)	Increased reliability
Performance	Variable	Optimized automatically	Consistent performance
Maintenance	Manual parameter updates	Automatic optimization	Zero maintenance

Production-Ready Defaults

Memory-Constrained Optimization: Defaults are conservative and work across deployment sizes
Large Payload Support: Automatic 64KB buffer alignment for 50MB+ JSON
Enterprise Integration: Enhanced Moshi H2 parameters pre-configured
Security Hardening: Modern TLS and cipher suite defaults
Performance Monitoring: Built-in metrics and optimization recommendations

Migration Path

Immediate: Replace complex configuration with minimal setup
Validation: Test with intelligent defaults
Optimization: Override specific parameters only if needed
Monitoring: Use built-in recommendations for fine-tuning

Monitoring and Metrics

Key Performance Indicators

Request latency improvement vs HTTP/1.1
JSON processing time for large payloads
Memory usage (target: 20% reduction in peak usage)
Connection efficiency (multiplexing reduces connection count)

JVM Parameters

HTTP/2 and streaming are enabled entirely through axis2.xml by selecting the appropriate message receiver and formatter classes (e.g. EnhancedMoshiJsonFormatter, MoshiStreamingMessageFormatter). No JVM system properties are required for HTTP/2 support.

Testing Strategy

Primary Focus: JSON Web Services Testing (90% Effort)

Since HTTP/2 transport is primarily designed for JSON-based web services, testing strategy prioritizes JSON over SOAP.

Phase 1: Core HTTP/2 Transport Tests

HTTPS-Only Validation: Ensure HTTP URLs rejected with clear error messages
Async Client Creation: Verify HTTP/2 client configuration and connection pooling
Request Interface Compliance: All Request interface methods work correctly
Entity Conversion: AxisRequestEntity → HTTP/2 SimpleHttpRequest conversion
Error Handling: Proper AxisFault generation for HTTP/2 specific issues

Phase 2: HTTP/2 + JSON Integration Tests

Large JSON Payload Tests (50MB+): Core business requirement
JSON-RPC over HTTP/2: Verify HTTP/2 multiplexing benefits
Performance Benchmarks: HTTP/1.1 vs HTTP/2 comparison
Memory usage under load

Phase 3: HTTP/2 Specific Feature Tests

Connection Multiplexing: Test concurrent requests over single HTTP/2 connection
Security Enforcement: Verify HTTP URLs rejected properly
Flow Control: Large payload streaming optimization

Secondary Focus: SOAP Compatibility Tests (10% Effort - Optional)

Limited Business Case Analysis:

Factor	Assessment	Rationale
Market Reality	SOAP usage declining	New services predominantly use REST/JSON APIs
Legacy Focus	Most SOAP on HTTP/1.1	SOAP organizations slow to adopt new protocols
Technical Benefits	Marginal for SOAP	SOAP/XML verbose - limited HTTP/2 binary efficiency gains
Testing ROI	Low value/high effort	Limited adoption likelihood

Success Criteria

Overall Project Success

✅ Performance: 30% latency reduction, 40% JSON processing improvement
✅ Memory: Reduced peak memory usage via streaming
✅ Stability: No regression in existing functionality
✅ Scalability: Support for 100+ concurrent streams
✅ Production: Successful deployment with modern JVM and garbage collection

Summary

The independent transport-h2 module approach provides optimal balance between performance improvements and deployment safety for Axis2. This dual-protocol architecture allows organizations to:

Evaluate HTTP/2 benefits without risk to existing HTTP/1.1 services
Migrate incrementally at their own pace
Optimize performance for large JSON payload processing
Maintain compatibility across diverse deployment environments

🏢 WildFly Users: Don't forget to check the WildFly + Axis2 HTTP/2 Integration Guide for enhanced performance through cooperative integration with Undertow HTTP/2 infrastructure.