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-c-core.git
The following commit(s) were added to refs/heads/master by this push:
new 7aee3eee1 More http/2 docs
7aee3eee1 is described below
commit 7aee3eee1b0c846282028f0093aab014e797bb84
Author: Robert Lazarski <[email protected]>
AuthorDate: Sun Dec 14 03:32:27 2025 -1000
More http/2 docs
---
docs/HTTP2_AXIS2_DOT_XML.md | 187 +++++++++++++++++++++++++++++
docs/HTTP2_SERVICES_DOT_XML.md | 267 +++++++++++++++++++++++++++++++++++++++++
2 files changed, 454 insertions(+)
diff --git a/docs/HTTP2_AXIS2_DOT_XML.md b/docs/HTTP2_AXIS2_DOT_XML.md
new file mode 100644
index 000000000..81754ae86
--- /dev/null
+++ b/docs/HTTP2_AXIS2_DOT_XML.md
@@ -0,0 +1,187 @@
+# HTTP/2 and axis2.xml Configuration: Axis2/C vs Axis2/Java
+
+## Executive Summary
+
+**No axis2.xml changes are required for HTTP/2 and JSON support in Axis2/C.**
This document explains why Axis2/C differs from Axis2/Java in this regard and
provides a comprehensive comparison of the architectural approaches.
+
+## Key Difference: No Configuration Changes Required
+
+Unlike Axis2/Java, **Axis2/C automatically detects and handles HTTP/2 with
JSON content without requiring any axis2.xml configuration changes**. The
request processing is determined at runtime through intelligent header analysis
rather than static configuration.
+
+## Axis2/C: Runtime Detection Approach
+
+### Automatic Protocol and Content-Type Detection
+
+Axis2/C uses the `axis2_apache2_request_processor_is_json_http2_request()`
function in
`/home/robert/repos/axis-axis2-c-core/src/core/transport/http/server/apache2/axis2_apache2_request_processor_factory.c:253-283`
to automatically detect:
+
+1. **HTTP/2 Protocol Detection**: Checks `request->protocol` for "HTTP/2" or
"HTTP/2.0" strings
+2. **JSON Content-Type Detection**: Analyzes Content-Type header for:
+ - `application/json`
+ - `text/json`
+ - `application/hal+json`
+ - `application/vnd.api+json`
+
+```c
+AXIS2_EXTERN axis2_bool_t AXIS2_CALL
+axis2_apache2_request_processor_is_json_http2_request(request_rec* request)
+{
+ const axis2_char_t* content_type = NULL;
+ const axis2_char_t* protocol = NULL;
+
+ if (!request) return AXIS2_FALSE;
+
+ /* Check protocol version */
+ protocol = request->protocol;
+ if (!protocol || (!strstr(protocol, "HTTP/2") && !strstr(protocol,
"HTTP/2.0")))
+ {
+ return AXIS2_FALSE;
+ }
+
+ /* Check content type */
+ content_type = apr_table_get(request->headers_in, "Content-Type");
+ if (!content_type)
+ {
+ content_type = apr_table_get(request->headers_in, "content-type");
+ }
+
+ if (!content_type) return AXIS2_FALSE;
+
+ /* JSON content type detection */
+ return (strstr(content_type, "application/json") != NULL ||
+ strstr(content_type, "text/json") != NULL ||
+ strstr(content_type, "application/hal+json") != NULL ||
+ strstr(content_type, "application/vnd.api+json") != NULL) ?
+ AXIS2_TRUE : AXIS2_FALSE;
+}
+```
+
+### Intelligent Processor Selection
+
+The factory method at `axis2_apache2_request_processor_factory.c:66-135`
implements a decision matrix:
+
+1. **HTTP/2 + JSON Content-Type** → JSON Processor (thread-safe)
+2. **HTTP/2 + Any Content-Type** → JSON Processor (assume modern client)
+3. **HTTP/1.1 + SOAP Content-Type** → SOAP Processor (legacy compatibility)
+4. **HTTP/1.1 + JSON Content-Type** → SOAP Processor (safe fallback)
+5. **Default/Unknown** → SOAP Processor (maximum compatibility)
+
+### Usage Example
+
+Simply send an HTTP/2 request with the appropriate Content-Type header:
+
+```bash
+curl -k --http2 -H "Content-Type: application/json" \
+ -X POST -d '{"getCameraStatus":[]}' \
+ https://localhost:8443/axis2/services/CameraControlService
+```
+
+No axis2.xml configuration is needed - the system automatically routes to the
appropriate processor.
+
+## Axis2/Java: Static Configuration Approach
+
+### Why Axis2/Java Requires axis2.xml Changes
+
+Based on the Spring Boot user guide
(`/home/robert/repos/axis-axis2-java-core/src/site/xdoc/docs/json-springboot-userguide.xml`),
Axis2/Java requires explicit axis2.xml configuration because it uses a
**static configuration model** where message processors are pre-configured
rather than dynamically selected.
+
+### Required Axis2/Java Configuration Components
+
+#### 1. Message Formatters
+```xml
+<message name="requestMessage">
+ <messageFormatter contentType="application/json"
+ class="org.apache.axis2.json.moshi.JsonFormatter"/>
+</message>
+```
+
+#### 2. Message Receivers
+Required classes mentioned in the Java documentation:
+- `JsonRpcMessageReceiver`
+- `JsonInOnlyRPCMessageReceiver`
+
+#### 3. Message Builders
+- `JsonBuilder`
+
+#### 4. Dispatchers and Handlers
+- `JSONBasedDefaultDispatcher`
+- `JSONMessageHandler`
+
+#### 4. HTTP/2 Transport Sender
+```xml
+<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">65536</parameter>
+ <parameter name="serverPushEnabled">false</parameter>
+ <parameter name="connectionTimeout">30000</parameter>
+ <parameter name="responseTimeout">300000</parameter>
+ <parameter name="streamingBufferSize">65536</parameter>
+ <parameter name="memoryPressureThreshold">0.8</parameter>
+ <!-- Enterprise Big Data Configuration -->
+ <parameter name="enableStreamingOptimization">true</parameter>
+ <parameter name="enableMemoryOptimization">true</parameter>
+ <parameter name="largePayloadThreshold">52428800</parameter> <!-- 50MB -->
+</transportSender>
+```
+
+## Architectural Comparison
+
+### Axis2/C Advantages
+
+1. **Zero Configuration**: No axis2.xml modifications required
+2. **Runtime Flexibility**: Dynamic processor selection based on actual
request characteristics
+3. **Backward Compatibility**: Existing SOAP services continue working
unchanged
+4. **Intelligent Routing**: HTTP/2 requests automatically get optimized
processing
+5. **Thread Safety**: HTTP/2 requests automatically use thread-safe processors
+
+### Axis2/Java Advantages
+
+1. **Explicit Control**: Developers can precisely control message processing
pipeline
+2. **Performance Optimization**: Pre-configured processors avoid runtime
decision overhead
+3. **Enterprise Features**: Rich configuration options for big data processing
(50MB+ payloads)
+4. **Monitoring**: Built-in performance metrics and optimization indicators
+
+## Implementation Details
+
+### Axis2/C Request Flow
+
+1. **Request Reception**: Apache HTTP server receives request
+2. **Header Analysis**: Factory analyzes HTTP protocol version and
Content-Type header
+3. **Processor Selection**: Factory selects appropriate processor (JSON vs
SOAP)
+4. **Processing**: Selected processor handles the request with appropriate
optimizations
+5. **Response Generation**: Response format matches request expectations
+
+### Axis2/Java Request Flow
+
+1. **Configuration Loading**: axis2.xml defines processing pipeline at startup
+2. **Request Reception**: Pre-configured message receivers handle requests
+3. **Format Detection**: Content-Type header routes to appropriate formatter
+4. **Processing**: Fixed pipeline processes the request
+5. **Response Generation**: Pre-configured formatters generate response
+
+## Best Practices
+
+### For Axis2/C Development
+
+1. **No Configuration Changes**: Simply use HTTP/2 with appropriate
Content-Type headers
+2. **Test Both Protocols**: Verify services work with both HTTP/1.1 and HTTP/2
+3. **Monitor Logs**: Check processor selection in debug logs
+4. **Content-Type Headers**: Ensure clients send `Content-Type:
application/json`
+
+### For Axis2/Java Migration to Axis2/C
+
+1. **Remove axis2.xml HTTP/2 Configuration**: Not needed in Axis2/C
+2. **Simplify Deployment**: No message formatter/receiver configuration
required
+3. **Test Runtime Detection**: Verify automatic processor selection works as
expected
+4. **Update Documentation**: Inform clients that configuration is not needed
+
+## Conclusion
+
+The fundamental difference between Axis2/C and Axis2/Java lies in their
architectural philosophy:
+
+- **Axis2/Java**: Static configuration with explicit control through axis2.xml
+- **Axis2/C**: Dynamic runtime detection with zero configuration
+
+This makes Axis2/C significantly easier to deploy for HTTP/2 and JSON
scenarios while maintaining full backward compatibility with existing SOAP
services. The intelligent request processor factory ensures that each request
type gets appropriate handling without any manual configuration.
+
+For HTTP/2 and JSON support, developers can focus on service implementation
rather than configuration management, as the framework handles protocol and
content-type detection transparently.
\ No newline at end of file
diff --git a/docs/HTTP2_SERVICES_DOT_XML.md b/docs/HTTP2_SERVICES_DOT_XML.md
new file mode 100644
index 000000000..f929e599d
--- /dev/null
+++ b/docs/HTTP2_SERVICES_DOT_XML.md
@@ -0,0 +1,267 @@
+# HTTP/2 JSON services.xml Configuration: Runtime Message Receiver Invocation
+
+## Executive Summary
+
+This document explains how the `axis2_json_rpc_msg_recv` messageReceiver
defined in `services.xml` gets automatically invoked at runtime when HTTP/2
requests with `Content-Type: application/json` are received by Axis2/C services.
+
+## Key Concept: Configuration-Driven Runtime Dispatch
+
+Unlike the axis2.xml file (which requires no changes for HTTP/2), the
**services.xml file defines the specific messageReceiver that handles JSON
requests for each operation**. The runtime system automatically invokes the
correct messageReceiver based on the HTTP headers and request characteristics.
+
+## Example: Camera Control Service Configuration
+
+From `./samples/user_guide/camera-control-service/services.xml`:
+
+```xml
+<operation name="startRecording">
+ <description>
+ Start camera recording with specified parameters.
+ Accepts clip_name, quality, duration, and format parameters.
+ </description>
+ <messageReceiver class="axis2_json_rpc_msg_recv"/>
+
+ <!-- REST-style HTTP mapping -->
+ <parameter name="httpMethod">POST</parameter>
+ <parameter name="httpPath">/startRecording</parameter>
+ <parameter name="contentType">application/json</parameter>
+ <parameter name="responseType">application/json</parameter>
+</operation>
+```
+
+## Runtime Invocation Flow: From HTTP Headers to Message Receiver
+
+### 1. HTTP Request Reception
+When a client sends an HTTP/2 JSON request:
+
+```bash
+curl -k --http2 -H "Content-Type: application/json" \
+ -X POST -d
'{"startRecording":[{"clip_name":"meeting_001","quality":"1080p"}]}' \
+ https://localhost:8443/axis2/services/CameraControlService
+```
+
+### 2. Request Processor Factory Selection
+The Apache2 request processor factory
(`axis2_apache2_request_processor_factory.c:66-135`) analyzes:
+- **HTTP Protocol**: Detects "HTTP/2.0" in `request->protocol`
+- **Content-Type Header**: Detects "application/json" in request headers
+- **Decision**: Routes to JSON processor (thread-safe, optimized for HTTP/2)
+
+### 3. Service and Operation Resolution
+The HTTP transport layer:
+1. **Service Identification**: Extracts service name from URL path
(`/axis2/services/CameraControlService`)
+2. **Operation Identification**: Extracts operation from JSON payload
(`"startRecording"`)
+3. **Operation Lookup**: Finds the matching `<operation
name="startRecording">` in services.xml
+
+### 4. Message Receiver Retrieval
+In `engine.c:311`, the engine calls:
+
+```c
+receiver = axis2_op_get_msg_recv(op, env);
+```
+
+This retrieves the messageReceiver configured in services.xml:
+
+```xml
+<messageReceiver class="axis2_json_rpc_msg_recv"/>
+```
+
+### 5. Message Receiver Invocation
+In `engine.c:318-319`, the engine invokes:
+
+```c
+status = axis2_msg_recv_receive(receiver, env, msg_ctx,
+ axis2_msg_recv_get_derived(receiver, env));
+```
+
+### 6. JSON Processing Execution
+The `axis2_json_rpc_msg_recv` receiver
(`src/core/receivers/axis2_json_rpc_msg_recv.c`):
+1. **Bypasses AXIOM/SOAP**: Revolutionary AXIOM-free processing
+2. **Direct JSON Parsing**: Uses json-c library for pure JSON processing
+3. **Service Function Invocation**: Directly calls the C service function
+4. **JSON Response Generation**: Returns JSON response without XML conversion
+
+## Configuration Parameters in services.xml
+
+### Operation-Level messageReceiver
+Each operation explicitly defines its message receiver:
+
+```xml
+<operation name="startRecording">
+ <messageReceiver class="axis2_json_rpc_msg_recv"/>
+</operation>
+
+<operation name="stopRecording">
+ <messageReceiver class="axis2_json_rpc_msg_recv"/>
+</operation>
+
+<operation name="getStatus">
+ <messageReceiver class="axis2_json_rpc_msg_recv"/>
+</operation>
+```
+
+### HTTP/2 Transport Configuration
+Service-level HTTP/2 optimization parameters:
+
+```xml
+<parameter name="transport.h2">
+ <parameter name="enableHTTP2">true</parameter>
+ <parameter name="enableStreaming">true</parameter>
+ <parameter name="enableMemoryOptimization">true</parameter>
+ <parameter name="maxFrameSize">16384</parameter>
+ <parameter name="maxConcurrentStreams">50</parameter>
+</parameter>
+```
+
+### JSON Processing Configuration
+Pure JSON processing without SOAP/XML dependencies:
+
+```xml
+<parameter name="maxJSONPayloadSize">1048576</parameter>
+<parameter name="jsonProcessingMode">pure-jsonc</parameter>
+```
+
+### REST-Style HTTP Mapping
+Each operation can define HTTP-specific parameters:
+
+```xml
+<parameter name="httpMethod">POST</parameter>
+<parameter name="httpPath">/startRecording</parameter>
+<parameter name="contentType">application/json</parameter>
+<parameter name="responseType">application/json</parameter>
+```
+
+## Message Receiver Types and Selection
+
+### axis2_json_rpc_msg_recv
+- **Purpose**: Revolutionary AXIOM-free JSON processing
+- **Use Case**: HTTP/2 JSON requests with Content-Type: application/json
+- **Features**:
+ - Zero SOAP/XML dependencies
+ - Direct JSON-to-service-function invocation
+ - HTTP/2 streaming optimized
+ - Thread-safe processing
+
+### Traditional SOAP Message Receivers
+- **axis2_raw_xml_in_out_msg_recv**: Traditional SOAP processing
+- **axis2_rpc_msg_recv**: RPC-style SOAP processing
+- **Use Case**: HTTP/1.1 SOAP requests with Content-Type: text/xml
+
+## Runtime Decision Matrix
+
+The system automatically selects the appropriate processing path:
+
+| HTTP Protocol | Content-Type | Request Processor | Message Receiver Used |
+|---------------|--------------|-------------------|---------------------|
+| HTTP/2.0 | application/json | JSON Processor | axis2_json_rpc_msg_recv |
+| HTTP/2.0 | text/xml | JSON Processor* | axis2_json_rpc_msg_recv |
+| HTTP/1.1 | application/json | SOAP Processor |
axis2_raw_xml_in_out_msg_recv** |
+| HTTP/1.1 | text/xml | SOAP Processor | axis2_raw_xml_in_out_msg_recv |
+
+\* HTTP/2 assumes modern client capabilities
+\** Falls back to traditional processing for safety
+
+## Advanced Configuration: Multiple Message Receivers
+
+Services can define different message receivers for different operations:
+
+```xml
+<service name="HybridService">
+ <!-- JSON operation for modern HTTP/2 clients -->
+ <operation name="processJson">
+ <messageReceiver class="axis2_json_rpc_msg_recv"/>
+ <parameter name="contentType">application/json</parameter>
+ </operation>
+
+ <!-- SOAP operation for legacy HTTP/1.1 clients -->
+ <operation name="processSoap">
+ <messageReceiver class="axis2_raw_xml_in_out_msg_recv"/>
+ <parameter name="contentType">text/xml</parameter>
+ </operation>
+</service>
+```
+
+## Implementation Details: axis2_json_rpc_msg_recv
+
+### Revolutionary Architecture
+From `src/core/receivers/axis2_json_rpc_msg_recv.c:19-30`:
+
+```c
+/**
+ * @file axis2_json_rpc_msg_recv.c
+ * @brief Revolutionary JsonRpcMessageReceiver - AXIOM-FREE Core Framework
Component
+ *
+ * This is the Axis2/C equivalent of Axis2/Java's JsonRpcMessageReceiver.
+ * Revolutionary: Completely bypasses AXIOM/SOAP - pure JSON processing only.
+ *
+ * Key Revolutionary Features:
+ * - Zero AXIOM dependencies (no XML processing at all)
+ * - Direct JSON-to-service-function invocation
+ * - Framework-level component (not service-specific)
+ * - HTTP/2 streaming optimized
+ */
+```
+
+### Key Features
+1. **AXIOM-Free Processing**: No SOAP/XML conversion overhead
+2. **Direct Function Invocation**: Bypasses XML processing pipeline
+3. **JSON-C Integration**: Pure JSON parsing and generation
+4. **HTTP/2 Optimization**: Streaming and memory-efficient processing
+5. **Thread Safety**: Designed for HTTP/2 concurrent request handling
+
+## Best Practices
+
+### Service Configuration
+1. **Consistent Message Receiver**: Use `axis2_json_rpc_msg_recv` for all JSON
operations
+2. **HTTP/2 Parameters**: Enable HTTP/2 optimization parameters at service
level
+3. **REST Mapping**: Define HTTP method and path parameters for REST-style
access
+4. **Content Type Specification**: Explicitly specify `application/json`
content types
+
+### Operation Definition
+```xml
+<operation name="operationName">
+ <description>Clear description of operation functionality</description>
+ <messageReceiver class="axis2_json_rpc_msg_recv"/>
+ <parameter name="httpMethod">POST</parameter>
+ <parameter name="httpPath">/operationName</parameter>
+ <parameter name="contentType">application/json</parameter>
+ <parameter name="responseType">application/json</parameter>
+</operation>
+```
+
+### JSON Payload Design
+```json
+{
+ "operationName": [{
+ "arg0": {
+ "parameter1": "value1",
+ "parameter2": "value2"
+ }
+ }]
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+1. **Wrong Message Receiver**: Using SOAP receiver for JSON requests
+2. **Missing Content-Type**: Not specifying `application/json` header
+3. **HTTP/2 Not Enabled**: Client not using HTTP/2 protocol
+4. **Operation Mismatch**: JSON operation name not matching services.xml
+
+### Debug Verification
+Check engine logs for message receiver selection:
+```
+🏭 REQUEST PROCESSOR FACTORY: Creating JSON HTTP/2 processor for thread-safe
processing
+🚀 JSON Message Receiver: Processing HTTP/2 JSON request for operation
'startRecording'
+```
+
+## Conclusion
+
+The services.xml messageReceiver configuration provides fine-grained control
over how individual operations process requests. By configuring
`axis2_json_rpc_msg_recv` for operations, services get:
+
+1. **Automatic HTTP/2 Detection**: Runtime system automatically routes HTTP/2
+ JSON requests to JSON processor
+2. **Operation-Specific Processing**: Each operation can have its own message
receiver and parameters
+3. **Zero Configuration Overhead**: No axis2.xml changes needed - all
configuration in services.xml
+4. **Revolutionary Performance**: AXIOM-free processing provides significant
performance benefits
+5. **Backward Compatibility**: SOAP operations continue working alongside JSON
operations
+
+This design enables seamless hybrid services that support both modern HTTP/2
JSON clients and legacy SOAP clients with a single service configuration.
\ No newline at end of file
