SOAP Web Service Standards

Contract-First Design and File Storage

• Adopt a contract-first approach: WSDL and XSD files are the absolute source of truth. Java code is always generated

from the contract, never the reverse.

• Store all external WSDL and XSD files strictly in:
• src/main/resources/wsdl/
• src/main/resources/xsd/
• Group schema files by external provider and API version using subdirectories (e.g., wsdl/providerName/v2/).
• Do not modify third-party WSDL or XSD files directly to fix naming issues. Use JAXB binding files (.xjb) for all

customisations.

JAXB Binding Files and Translation Documentation

• Use JAXB binding files to map non-English element names to English Java equivalents during code generation:

<jaxb:bindings version="3.0"
    xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <jaxb:bindings schemaLocation="service.xsd" node="/xs:schema">
    <jaxb:bindings node="//xs:element[@name='Faktura']">
      <jaxb:class name="Invoice"/>
    </jaxb:bindings>
    <jaxb:bindings node="//xs:element[@name='Kwota']">
      <jaxb:property name="amount"/>
    </jaxb:bindings>
  </jaxb:bindings>
</jaxb:bindings>

• Log every translation applied via binding files in docs/TRANSLATIONS.md at the project root using the following

structure:

• Document the WS-Security profile variant required by each integration partner in docs/TRANSLATIONS.md alongside the

translation table.

Code Generation, Gradle Kotlin DSL

• Autogenerated classes must be output strictly to the Gradle build directory to prevent source tree pollution. Use

layout.buildDirectory for dynamic target paths.

• Never commit autogenerated classes to version control. Add build/ to .gitignore.
• Configure sourceSets to automatically mark the generation output directory as a generated source root.
• Prefer raw JavaExec tasks with isolated dependency configurations (jaxb, cxfTools) over outdated third-party

Gradle plugins.

Example: XSD to Java (XJC):

val generatedJaxbDir = layout.buildDirectory.dir("generated/sources/jaxb")

tasks.register<JavaExec>("genJaxb") {
    description = "Generate JAXB classes from XSD"
    group = "jaxb"
    val xsdFile = file("src/main/resources/xsd/schema.xsd")
    val bindingFile = file("src/main/resources/xsd/bindings.xjb")
    val outputDir = generatedJaxbDir.get().asFile
    inputs.file(xsdFile); inputs.file(bindingFile); outputs.dir(outputDir)
    classpath = configurations["jaxb"]
    mainClass.set("com.sun.tools.xjc.XJCFacade")
    args("-d", outputDir.absolutePath, "-p", "com.example.generated.model",
         "-encoding", "UTF-8", "-no-header", "-b", bindingFile.absolutePath,
         xsdFile.absolutePath)
    doFirst { outputDir.mkdirs() }
}

Example: WSDL to Java (Apache CXF):

val generatedWsdlDir = layout.buildDirectory.dir("generated/sources/wsdl")

tasks.register<JavaExec>("generateFromWsdl") {
    group = "wsdl2java"; description = "Generate classes from WSDL"
    mainClass.set("org.apache.cxf.tools.wsdlto.WSDLToJava")
    classpath = configurations["cxfTools"]
    val outputDir = generatedWsdlDir.get().asFile
    outputs.dir(outputDir)
    args("-d", outputDir.absolutePath, "-p", "com.example.generated.wsdl",
         "-client", "-wsdlLocation", "classpath:wsdl/service.wsdl",
         "src/main/resources/wsdl/service.wsdl")
}

SourceSet configuration:

sourceSets {
    main { java { srcDir(generatedJaxbDir); srcDir(generatedWsdlDir) } }
}
tasks.withType<JavaCompile> { dependsOn("genJaxb", "generateFromWsdl") }

Security Practices

#### XXE Prevention

• Disable Document Type Definitions (DTDs) and external entity processing on all XML unmarshallers to prevent XXE

injection attacks:

SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
spf.setFeature("http://xml.org/sax/features/external-general-entities", false);
spf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);

#### TLS Enforcement

• Enforce TLS/HTTPS for all SOAP endpoint communications. Reject plain HTTP connections.
• Set explicit connect and read timeouts on the underlying HTTP client to prevent thread starvation from unresponsive

SOAP servers.

#### Connection Pooling

• Configure HTTP connection pooling (Apache HttpClient PoolingHttpClientConnectionManager or CXF's HTTPConduit) for

the underlying transport layer to improve throughput under concurrent load.

SOAP Service Singleton

• Instantiate the heavy SOAP Service class once (as a Spring Bean or application-scoped singleton) to avoid the high

cost of repeatedly parsing the WSDL on every request.

• Inject the Service singleton and obtain Port instances from it per-request, or pool and reuse Port instances in

a thread-safe manner.

WS-Security

• Use WS-Security (WSS4J / Spring-WS Wss4jSecurityInterceptor) when the integration partner requires message-level

security beyond transport TLS.

• For username/password authentication, use UsernameToken with PasswordDigest mode. Never transmit passwords in

plaintext in the SOAP header.

• For high-security integrations, use X.509 certificate signing and encryption of the SOAP body. Store private keys in a

KMS or Java KeyStore (PKCS12). Never store private keys in plaintext files.

• Configure Wss4jSecurityInterceptor example:

Wss4jSecurityInterceptor interceptor = new Wss4jSecurityInterceptor();
interceptor.setSecurementActions("UsernameToken");
interceptor.setSecurementUsername("serviceUser");
interceptor.setSecurementPassword(passwordFromVault);
interceptor.setSecurementPasswordType(WSConstants.PW_DIGEST);

SOAP Fault Taxonomy

• Always catch SOAPFaultException at the service client boundary and map it to a typed application exception before

propagating to business logic. Never let raw SOAPFaultException reach an HTTP API response.

• Log the full fault code, fault string, and detail element at WARN level after redacting any PII in the detail

element. Use ERROR level only for unexpected system faults.

• Distinguish two categories of faults in integration documentation:
• Business faults: invalid invoice number, unknown customer ID, insufficient balance. Non-retryable.
• System faults: service unavailable, timeout, internal server error. Retryable with backoff.
• Translate all faults to a standardised error envelope before returning to the caller.

Message Logging with PII Redaction

• Log all outbound SOAP requests and inbound responses at DEBUG level using a Spring-WS PayloadLoggingInterceptor or

a custom ClientInterceptor.

• Before writing to logs, redact:
• Authentication credentials in WS-Security headers
• PII fields (names, addresses, tax IDs, NINs)
• Financial data (account numbers, card numbers)
• In production, enable full message logging only when a debug flag is active via environment variable. Do not log

complete SOAP envelopes by default.

Resilience4j, Retry and Circuit Breaker

• Wrap all outbound SOAP client calls with a Resilience4j circuit breaker and retry policy.
• Configure exponential backoff with jitter on retry. Maximum of 3 retries for transient faults.
• Retryable conditions: HTTP 5xx responses, SOAPFaultException with a system fault code, connection timeouts.
• Non-retryable conditions: business fault codes (invalid input, authorisation failure).

RetryConfig retryConfig = RetryConfig.custom()
    .maxAttempts(3)
    .waitDuration(Duration.ofMillis(500))
    .intervalFunction(IntervalFunction.ofExponentialRandomBackoff(500, 2.0, 0.5))
    .retryOnException(e -> e instanceof SoapSystemFaultException)
    .build();

Testing SOAP Integrations

• Use WireMock (WireMockExtension for JUnit 5) to stub SOAP endpoints in unit and integration tests. Never call real

external SOAP services in automated tests.

• Store WireMock response stubs (raw SOAP XML files) under src/test/resources/wiremock/ versioned alongside the WSDL.
• Use SoapUI or ReadyAPI for exploratory integration testing against the real partner endpoint during development and

certification.

• Write at least one test for each fault taxonomy category: expected business fault, unexpected system fault, timeout,

and malformed response.

MTOM for Binary Payloads

• Use MTOM (Message Transmission Optimization Mechanism) for transmitting binary payloads (PDFs, images, signed

documents) larger than 10 KB to avoid base64 encoding overhead.

• Configure javax.xml.ws.soap.MTOMFeature on the service port when MTOM is required:

MTOMFeature mtomFeature = new MTOMFeature(true, 10240); // threshold 10 KB
MyService port = service.getMyServicePort(mtomFeature);

• Enforce a maximum attachment size limit on the server side and validate MIME types of received attachments to prevent

abuse.

WSDL Versioning

• Treat the WSDL as an immutable contract once published. Changes require a new WSDL version in a new subdirectory

(e.g., wsdl/providerName/v2/).

• Additive changes (new optional XSD elements) are permitted without a version bump only if they do not break existing

generated code.

• Coordinate WSDL version upgrades with the integration partner before updating the dependency in build.gradle.kts.
• Keep the previous WSDL version's generated client code available until all consumers have migrated.