SOAP Message Mapper

Overview

The SoapMessageMapper is a runtime service that provides bidirectional transformation between JSON payloads and SOAP 1.1/1.2 XML envelopes. It serves as a bridge, enabling REST/JSON API consumers to interact with backend SOAP services.

The primary functions of this component are:

• Request Transformation: Building a complete SOAP envelope from a JSON payload, an operation name, and a target namespace. This includes support for WSDL-driven contracts, rpc and document binding styles, and injecting standard or custom SOAP headers.
• Response Transformation: Parsing a SOAP response envelope (including SOAP Faults) into a structured JSON payload. This process is highly configurable, with fine-grained controls for data type conversion, null handling, array formatting, and more.
• WS-Security: Injecting various WS-Security headers into a request envelope, including UsernameToken (with password text or digest), BinarySecurityToken (e.g., X.509), and complex XML-DSIG signatures.

The SoapMessageMapper is configured on a per-request basis using ThreadLocal variables. A calling component, such as a runtime controller, resolves system-level, operation-level, and field-level settings and uses the public setResolved... methods to configure the mapper's behavior for a single transaction.

How it Works

The SoapMessageMapper uses a combination of WSDL-derived contract mappings and configurable heuristics to perform transformations.

JSON to SOAP Transformation

The buildEnvelopeFromJson method orchestrates the creation of a SOAP request.

1. Parse Input: The incoming JSON payload string is parsed into a Java object structure (Map, List, String, etc.). To preserve precision, numbers are parsed as BigDecimal or BigInteger.
2. Extract Sidecar Headers: A reserved _soapHeaders object in the root of the JSON payload is extracted. Its values are used to populate declared soap:header blocks. The _soapHeaders key is then stripped from the payload to prevent it from being serialized into the soap:Body.
3. Apply Request Mapping:
   • If a WSDL-derived contract is provided, the encodeRequestNode method recursively traverses the contract and the JSON payload, transforming the JSON into a Java object structure that mirrors the target XML. This process enforces contract rules, such as choice groups and data constraints, and applies request-side data handling for booleans and nulls.
   • If no contract is provided, a simpler rule-based or auto-normalization mapping is applied.
4. Build DOM: A new XML DOM Document is created.
5. Construct Envelope: The soapenv:Envelope, soapenv:Header, and soapenv:Body elements are created.
6. Inject Headers: If the operation's metadata includes soap:header declarations (operationHeaders), the corresponding values from the _soapHeaders sidecar are serialized into the soapenv:Header.
7. Shape Body: The structure of the soapenv:Body depends on the WSDL binding style:
   • document (default): The body's direct child is the message element (e.g., <GreetRequest>).
   • rpc: The body contains a wrapper element named after the operation (e.g., <Greet>), which in turn contains the parameter elements.
8. Serialize Payload: The appendValue method recursively walks the transformed Java object structure and creates the corresponding XML elements and attributes within the soapenv:Body. This step also handles xsi:nil="true" for null values and can qualify child elements with a namespace if the contract specifies elementFormDefault="qualified".
9. Return XML: The final DOM is serialized to a UTF-8 XML string.

SOAP to JSON Transformation

The parseSoapResponse method transforms a backend SOAP response into a JSON-like structure. The process is illustrated in the diagram below.

flowchart TD
    subgraph SOAP to JSON Flow
        A[SOAP Response XML] --> B{Parse XML};
        B --> C{"Repair missing namespaces?"};
        C -- Yes --> D[Inject standard xmlns];
        C -- No --> E;
        D --> E[Create DOM];
        E --> F{Fault element present?};
        F -- Yes --> G[Extract Fault Details];
        F -- No --> H{RPC/encoded style?};
        H -- Yes --> I[Throw UnsupportedSoapFormatException];
        H -- No --> J[Capture SOAP Headers];
        J --> K[Select Payload Root];
        K --> L{Response Contract provided?};
        L -- Yes --> M[Apply Contract Mapping (`decodeResponseNode`)];
        L -- No --> N[Apply Heuristics (`elementToValue`)];
        subgraph M
            direction LR
            M1[Data Conversion]
            M2[Constraint Validation]
            M3[Null/Empty Handling]
        end
        M --> O[Apply Field Casing & Ordering];
        N --> O;
        O --> P[Return Success/Fault Mapping];
        G --> P;
    end
    I --> Q((Error));

1. Parse XML: The input XML string is parsed into a DOM Document. The parser first attempts a direct parse. If it fails due to a namespace error, parseSoapXmlWithNamespaceRepair attempts to inject missing standard xmlns declarations (e.g., for soapenv, xsi) and retries the parse.
2. Check for Faults: The mapper looks for a <soap:Fault> element in the soap:Body or soap:Header. If found, extractSoapFaultDetails parses its contents (supporting both SOAP 1.1 and 1.2 structures) into a map, which is returned in a SoapResponseMapping.
3. Check for Unsupported Formats: It detects if the response uses SOAP RPC/Section 5 encoding (soap:encodingStyle) and throws an UnsupportedSoapFormatException if so, as this format is not supported.
4. Capture Headers: If header propagation is enabled, the contents of the soap:Header are captured, filtered by allow/deny lists, and stored for the caller.
5. Transform Payload:
   • With Contract: If a contract is provided, applyContractResponseMapping is used. It calls decodeResponseNode to recursively walk the contract and the DOM, transforming the XML into a Java object structure. This path applies the full suite of configured data conversions for datetimes, numbers, booleans, nulls, arrays, and more.
   • Without Contract: If no contract is available, elementToValue performs a heuristic-based transformation. It converts elements to maps and lists, handles xsi:nil, and resolves multi-ref href attributes. It also applies a wrapper-flattening heuristic to simplify list structures.
6. Apply Post-Processing: After the primary transformation, two final steps are applied to the resulting map:
   • Field Casing: applyFieldCasingRecursively transforms JSON key names to the configured case (e.g., camelCase, snake_case).
   • Field Ordering: applyFieldOrderingRecursively sorts the keys in each JSON object according to the configured mode (as-schema, alphabetical, preserve-source).
7. Return Result: The final Java object structure is returned in a SoapResponseMapping object.

WS-Security Injection

The injectWsSecurity... methods modify a SOAP envelope string by parsing it into a DOM, adding a wsse:Security header, and injecting the specified tokens and/or signature.

• injectWsSecurityUsernameToken adds a wsse:UsernameToken with credentials.
• injectWsSecurityBinaryToken adds a wsse:BinarySecurityToken.
• injectWsSecuritySignedBinaryToken is the most complex, performing a full XML-DSIG signing process. It constructs Reference elements for the parts to be signed (e.g., soap:Body, wsu:Timestamp), builds a SignedInfo block, creates a KeyInfo block according to the specified style (e.g., DirectReference, ThumbprintSHA1), and uses XMLSignatureFactory to generate and insert the ds:Signature.

Caching

To optimize performance, the SoapMessageMapper uses an internal LRU cache, compiledNodeCache, for WSDL contract metadata. When a contract-driven transformation occurs, the parsed and structured contract nodes (NodeMetadata) are cached. Subsequent requests using the same contract can retrieve the compiled metadata from the cache, avoiding the cost of recompiling it. The cache key (IdentityKey) uses reference equality, making lookups fast. The cache is bounded to a maximum of 500 entries.

Configuration and Data Handling

The behavior of the SoapMessageMapper is controlled on a per-request basis by setting ThreadLocal variables. The caller uses the public setResolved... methods before invoking a transformation and must call the corresponding clear... method (or clearAllConversionDefaults) in a finally block to prevent state from leaking between requests.

Binding Style

The SOAP body structure is determined by the WSDL binding style, which can be either document or rpc.

Per-Operation Headers

For request generation, custom SOAP headers can be supplied in the JSON payload under a reserved _soapHeaders key. These values are used to populate soap:header blocks declared in the operation's WSDL.

The _soapHeaders key must be a JSON object at the root of the request payload. Each key in this object corresponds to the local name of a declared header block.

{
  "_soapHeaders": {
    "SessionID": "abc-123",
    "TransactionContext": {
      "ID": "xyz-789"
    }
  },
  "payload": {
    "user": "test"
  }
}

Response Data Formatting

The following sections detail the configuration options for transforming data from a SOAP response to JSON. Each feature is controlled by a resolvedMode (the default for the operation) and a fieldOverrides map (for per-field exceptions).

Array Collapse

Controls how arrays with a single element are represented in the output JSON.

Numeric Handling

Controls how numeric values from SOAP are represented in the output JSON.

Whitespace Handling

Controls how whitespace in string-based XSD types (e.g., xsd:string, xsd:token) is handled.

Binary Data Handling

Controls the encoding of xsd:base64Binary and xsd:hexBinary fields in the output JSON.

Duration Handling

Controls the formatting of xsd:duration fields.

Datetime Handling

Controls the formatting of xsd:date, xsd:dateTime, and xsd:time fields.

Format Modes

Timezone Modes

Null Value Handling

Controls how null or empty values are represented in both request and response transformations. There are separate settings for the request and response directions.

Field Name Casing

Controls the case of keys in the output JSON object.

JSON Field Ordering

Controls the order of keys in the output JSON object.

xsi:type Discriminator Handling

Controls how xsi:type attributes on polymorphic elements are handled in the output JSON.

Other Response-Side Behaviors

• Required-but-Empty Handling: setResolvedRequiredHandling controls behavior when a required field is present but empty in the SOAP response. The default permissive mode allows it, while fail-with-502 causes a RequiredFieldEmptyException.
• SOAP Header Propagation: setResolvedHeaderPropagation controls whether SOAP headers from the response are captured. The drop mode ignores them. The expose-as-meta mode places them in a _meta object in the JSON response. expose-as-http-headers is also a mode, though its implementation is handled by the caller.

API Reference

The SoapMessageMapper exposes several public methods for transformation and WS-Security injection.

buildEnvelopeFromJson(...)

Builds a SOAP envelope from a JSON payload. Several overloads exist; the most comprehensive signature allows for fine-grained control over data handling.

public String buildEnvelopeFromJson(
    String operationName,
    String namespace,
    String soapVersion,
    String jsonPayload,
    Map<String, Object> requestMapping,
    Map<String, String> fieldEncodings,
    String resolvedBoolMode,
    Map<String, String> fieldBooleanOverrides,
    String resolvedNullRequestModeValue,
    Map<String, String> fieldNullOverrides
);

• operationName: The name of the SOAP operation.
• namespace: The target namespace for the operation element.
• soapVersion: "1.1" or "1.2".
• jsonPayload: The request payload as a JSON string.
• requestMapping: The WSDL-derived contract or rule-based mapping.
• fieldEncodings: Per-field encoding rules for the request.
• resolvedBoolMode: Default boolean handling ("as-bool" or "as-int").
• fieldBooleanOverrides: Per-field boolean handling overrides.
• resolvedNullRequestModeValue: Default null handling for the request.
• fieldNullOverrides: Per-field null handling overrides.

Returns: A String containing the complete SOAP envelope.

parseSoapResponse(...)

Parses a SOAP response into a SoapResponseMapping object.

public SoapResponseMapping parseSoapResponse(
    String xml,
    Map<String, Object> responseMapping,
    Map<String, String> fieldEncodings,
    String resolvedBoolMode,
    Map<String, String> fieldBooleanOverrides,
    String resolvedNullResponseModeValue,
    Map<String, String> fieldNullOverrides
);

• xml: The SOAP response envelope as an XML string.
• responseMapping: The WSDL-derived contract or rule-based mapping.
• fieldEncodings: Per-field decoding rules for the response.
• resolvedBoolMode: Default boolean handling.
• fieldBooleanOverrides: Per-field boolean handling overrides.
• resolvedNullResponseModeValue: Default null handling for the response.
• fieldNullOverrides: Per-field null handling overrides.

Returns: A SoapResponseMapping object, which contains a boolean fault flag and the payload as a Map<String, Object>.

injectWsSecurityUsernameToken(...)

Injects a wsse:UsernameToken into a SOAP envelope.

public String injectWsSecurityUsernameToken(
    String soapEnvelope,
    String username,
    String password,
    boolean passwordDigest,
    boolean includeTimestamp,
    // ... and many other optional parameters for fine-tuning
);

This method supports numerous optional parameters to control aspects like wsu:Id attributes, mustUnderstand headers, element order, and timestamp creation/TTL.

injectWsSecuritySignedBinaryToken(...)

Injects a wsse:BinarySecurityToken and an XML-DSIG Signature into a SOAP envelope. This is the most complex injection method, with a large number of parameters to control every aspect of the signature creation process.

Troubleshooting

See Also

• RuntimeController: The typical caller of SoapMessageMapper.
• ContractPatternValidator: A component used for validating string values against regex patterns from XSDs.
• EncodingRegistry: Manages custom field encoding/decoding strategies.
• OASIS WS-Security Specifications
• W3C XML Signature Syntax and Processing

All SOAP-to-REST docs