SOAP، WSDL و SOA: یکپارچه‌سازی سازمانیSOAP, WSDL & SOA: Enterprise Integration

Open the job ads at banks, insurers, telcos and large enterprises and next to "REST" you will almost always find one more word: SOAP. Many newer engineers wave it away as "legacy". That mistake loses interviews — and worse, it means that the day you sit down in front of a two-thousand-line WSDL you will not know where to start.

Here is the truth: SOAP is not old, it is installed. Billions of transactions a day move over this protocol, because it was built for a world where "a written contract, a digital signature over part of the message, and guaranteed delivery" were not optional. This chapter builds SOAP from zero — not as a museum piece, but as a tool you must be able to debug in production tomorrow morning.

Part 0 — Two words to nail down first: "service" and "contract"

• Service: a business capability reachable across the network with a clear owner. "Get account balance" is a service; AccountRepository is an internal class, not a service.
• Contract: a formal, machine-readable description of the operations, their inputs and outputs, and the errors they can return. In the SOAP world that contract is a WSDL file.
• Loose coupling: the consumer depends only on the contract — not on your language, your database, or your library versions.

Part 1 — What SOA actually means

Picture a large enterprise: core banking, CRM, a card system, loans, reporting — each bought or built in a different decade, in a different language. Now the business says: "when a customer takes a loan, pull their credit score, read their balance from core, and record it in CRM."

The easy, fatal route is for each system to reach into another system's database or build a bespoke point-to-point link. Six systems means up to fifteen links; twenty systems means up to a hundred and ninety. That is integration spaghetti.

Diagram: point-to-point chaos versus a service layer — نمودار: آشفتگی نقطه‌به‌نقطه در برابر لایه‌ی سرویس.

flowchart LR
  subgraph Before["Point-to-point"]
    A1[Core Banking] --- B1[CRM]
    A1 --- C1[Cards]
    B1 --- C1
    C1 --- D1[Loans]
    A1 --- D1
  end
  subgraph After["Service layer"]
    A2[Core Banking] --> S[(Service contracts)]
    B2[CRM] --> S
    C2[Cards] --> S
    D2[Loans] --> S
  end

SOA (Service-Oriented Architecture) is the architectural answer: put every capability behind an explicit contract and talk only through that contract. Its four real pillars:

1. Explicit boundaries. A service call crosses a boundary: it is expensive, it can fail, it needs serialization. Never pretend a remote call is a local method call — that was exactly the mistake earlier RPC generations made.
2. Share schema, not class. Two services exchange a schema, not a JAR. If you must import someone's Java class to talk to them, you are not loosely coupled.
3. Autonomy. Each service deploys and scales independently and is allowed to fail without taking the rest down.
4. Policy-based compatibility. "To talk to me you must sign and send a timestamp" is expressed as a machine-readable policy (WS-Policy), not as an email to the other team.

Governance is the set of rules that decides who may define a service, how namespaces are named, how versions are published and retired, and what each SLA is. In classic SOAP a registry called UDDI was meant to be the phone book of services. It effectively died — nobody discovers services dynamically; in practice teams email a WSDL or drop it in a repo. But the idea of a central catalogue survived, and today it is called an API catalogue / developer portal.

SOA versus microservices

Boundaries, Saga and inter-service communication are covered in ms-foundations, ms-communication and ms-data; we do not repeat them here.

Part 2 — SOAP from zero

Separating Header from Body is what lets intermediaries process a message without understanding its business content — route it, log it, verify its signature. That out-of-band extensibility is what separates SOAP from a plain RPC. (SOAP originally stood for "Simple Object Access Protocol"; since 1.2 it is officially not an acronym any more — it was neither simple nor only about objects.)

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:acc="http://bank.example/accounts/v1">
  <soap:Header>
    <acc:CorrelationId soap:mustUnderstand="true"
                       soap:role="http://www.w3.org/2003/05/soap-envelope/role/next">
      7f3a9c22-1e44-4a0b-9a11-88b2c4d5e6f7
    </acc:CorrelationId>
  </soap:Header>
  <soap:Body>
    <acc:GetBalanceRequest>
      <acc:accountNumber>IR820540102680020817909002</acc:accountNumber>
      <acc:currency>IRR</acc:currency>
    </acc:GetBalanceRequest>
  </soap:Body>
</soap:Envelope>

• Envelope is the document root. Header is optional and holds zero or more header blocks. Body is mandatory and appears exactly once.
• mustUnderstand: if it is true and the targeted receiver does not recognise the block, it must fault and must not process the message.
• role (1.2) or actor (1.1) targets a block at a node. The three standard 1.2 URIs share the prefix http://www.w3.org/2003/05/soap-envelope/role/: next (every intermediary and the ultimate receiver), none (no node may process it), ultimateReceiver. Omitting role means the ultimate receiver. The 1.1 equivalent of next is http://schemas.xmlsoap.org/soap/actor/next.

Diagram: a SOAP message path through an intermediary node — نمودار: مسیر یک پیام SOAP از فرستنده تا گیرنده‌ی نهایی با یک گره میانی.

sequenceDiagram
  participant S as Initial sender
  participant I as Intermediary gateway
  participant R as Ultimate receiver
  S->>I: Envelope + Header(security, correlation)
  Note over I: Processes headers for role "next"<br/>Relays them, never touches Body
  I->>R: Envelope + remaining headers
  Note over R: Processes ultimateReceiver headers<br/>Executes the Body operation
  R-->>I: Response envelope
  I-->>S: Response envelope

Fault — the SOAP error model

In REST you use HTTP status codes. In SOAP the error lives inside the message: a Fault element inside Body. That is fundamental, because SOAP was designed to be transport-independent — over JMS or SMTP there is no HTTP status code at all.

<!-- SOAP 1.1 -->
<soap:Fault xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <faultcode>soap:Client</faultcode>
  <faultstring>Account number is not a valid IBAN</faultstring>
  <faultactor>http://bank.example/accounts</faultactor>
  <detail>
    <acc:ValidationError xmlns:acc="http://bank.example/accounts/v1">
      <acc:field>accountNumber</acc:field>
    </acc:ValidationError>
  </detail>
</soap:Fault>

<!-- SOAP 1.2 -->
<env:Fault xmlns:env="http://www.w3.org/2003/05/soap-envelope"
           xmlns:acc="http://bank.example/accounts/v1">
  <env:Code>
    <env:Value>env:Sender</env:Value>
    <env:Subcode><env:Value>acc:InvalidAccount</env:Value></env:Subcode>
  </env:Code>
  <env:Reason><env:Text xml:lang="en">Not a valid IBAN</env:Text></env:Reason>
  <env:Node>http://bank.example/accounts</env:Node>
  <env:Detail>
    <acc:ValidationError><acc:field>accountNumber</acc:field></acc:ValidationError>
  </env:Detail>
</env:Fault>

One practical warning: never dump a Java stack trace into <detail>. It leaks information (class names, file paths, library versions) and it breaks the contract, because nothing in your XSD defines it. detail must be a type declared in your schema (see appsec-owasp).

SOAP over HTTP — the raw message

POST /accounts/v1 HTTP/1.1
Host: soa.bank.example
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://bank.example/accounts/v1/GetBalance"

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetBalanceRequest xmlns="http://bank.example/accounts/v1">
      <accountNumber>IR820540102680020817909002</accountNumber>
    </GetBalanceRequest>
  </soap:Body>
</soap:Envelope>

# SOAP 1.1 — SOAPAction is its own header and the quotes are part of the value
curl -sS -X POST 'https://soa.bank.example/accounts/v1' \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: "http://bank.example/accounts/v1/GetBalance"' \
  --data-binary @request.xml

# SOAP 1.2 — the action rides inside Content-Type; there is no SOAPAction header
curl -sS -X POST 'https://soa.bank.example/accounts/v1' \
  -H 'Content-Type: application/soap+xml; charset=utf-8; action="http://bank.example/accounts/v1/GetBalance"' \
  --data-binary @request.xml

Why is SOAP a protocol and REST a style? SOAP has a formal specification that mandates message structure, a processing model, an error model and extension rules; a message is either valid or it is not. REST is a set of constraints (statelessness, uniform interface, resources, cacheability); no standard tells you what your error body looks like — we later filled that gap with application/problem+json (RFC 9457). REST design is covered in api-design.

Part 3 — XSD: the language that defines the shape of data

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:acc="http://bank.example/accounts/v1"
            targetNamespace="http://bank.example/accounts/v1"
            elementFormDefault="qualified" version="1.0">

  <xsd:simpleType name="Iban">                     <!-- a base type with a restriction -->
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:complexType name="Money">                   <!-- a type with children -->
    <xsd:sequence>
      <xsd:element name="amount"   type="xsd:decimal"/>
      <xsd:element name="currency" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>

  <xsd:element name="GetBalanceRequest">           <!-- a top-level element -->
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="accountNumber" type="acc:Iban"/>
        <xsd:element name="asOf" type="xsd:date" minOccurs="0"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>

  <xsd:element name="GetBalanceResponse">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="available" type="acc:Money"/>
        <xsd:element name="hold" type="acc:Money" minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

• targetNamespace declares which namespace this schema defines elements for. A namespace is just a unique URI-shaped identifier; it need not resolve to anything.
• elementFormDefault="qualified" means child elements must also carry the namespace.
• xsd:sequence enforces order, xsd:choice allows exactly one branch, xsd:all allows any order (heavily restricted in XSD 1.0).
• minOccurs="0" optional, maxOccurs="unbounded" repeating, nillable="true" means present-but-explicitly-null via xsi:nil="true" — different from absent.
• xsd:include pulls in a schema with the same namespace; xsd:import one with a different namespace. Put shared enterprise types (Money, Address) in their own versioned namespace and import them — but keep that set small, or every tiny change forces every service to rebuild.

Design note: always use xsd:decimal for money (never xsd:float/xsd:double), and give identifiers a pattern instead of a bare xsd:string, so bad data is rejected at the boundary rather than inside your logic.

To validate from Java, build a Schema via SchemaFactory and blank the XMLConstants.ACCESS_EXTERNAL_DTD and ACCESS_EXTERNAL_SCHEMA properties so the parser never touches the network or the filesystem.

Part 4 — Reading a WSDL line by line

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:acc="http://bank.example/accounts/v1"
    xmlns:tns="http://bank.example/accounts/v1/wsdl"
    targetNamespace="http://bank.example/accounts/v1/wsdl" name="AccountService">

  <wsdl:types>                                   <!-- 1) data types -->
    <xsd:schema targetNamespace="http://bank.example/accounts/v1/wsdl">
      <xsd:import namespace="http://bank.example/accounts/v1"
                  schemaLocation="accounts-v1.xsd"/>
    </xsd:schema>
  </wsdl:types>

  <wsdl:message name="GetBalanceRequest">        <!-- 2) abstract messages -->
    <wsdl:part name="parameters" element="acc:GetBalanceRequest"/>
  </wsdl:message>
  <wsdl:message name="GetBalanceResponse">
    <wsdl:part name="parameters" element="acc:GetBalanceResponse"/>
  </wsdl:message>

  <wsdl:portType name="AccountPortType">         <!-- 3) abstract interface -->
    <wsdl:operation name="GetBalance">
      <wsdl:input  message="tns:GetBalanceRequest"/>
      <wsdl:output message="tns:GetBalanceResponse"/>
    </wsdl:operation>
  </wsdl:portType>

  <wsdl:binding name="AccountSoapBinding" type="tns:AccountPortType">   <!-- 4) protocol -->
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="GetBalance">
      <soap:operation soapAction="http://bank.example/accounts/v1/GetBalance"/>
      <wsdl:input><soap:body use="literal"/></wsdl:input>
      <wsdl:output><soap:body use="literal"/></wsdl:output>
    </wsdl:operation>
  </wsdl:binding>

  <wsdl:service name="AccountService">           <!-- 5) the real address -->
    <wsdl:port name="AccountSoapPort" binding="tns:AccountSoapBinding">
      <soap:address location="https://soa.bank.example/accounts/v1"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

Diagram: WSDL structure, from abstract contract down to a concrete address — نمودار: ساختار WSDL از انتزاع تا آدرس واقعی.

flowchart TD
  T[types: XSD element definitions] --> M[message: named parts]
  M --> P["portType / interface: operations<br/>input, output, fault"]
  P --> B["binding: protocol + style + use<br/>soapAction per operation"]
  B --> S["service and port<br/>soap:address location"]

The top three layers are abstract, the bottom two concrete. The same portType can have two bindings (one SOAP over HTTP, one over JMS), and the same binding can be published at several port addresses. That is the separation of contract from transport.

Two binding attributes decide the shape of your message: style (document or rpc) and use (literal or encoded).

wrapped is a naming convention, not a WSDL value: you get the RPC benefit of reading the operation from the Body root and full XSD validation.

WSDL 1.1 vs 2.0: the root moved from definitions to description, portType became interface (with extends), port became endpoint, and message disappeared entirely (you reference the XSD element directly); the namespace became http://www.w3.org/ns/wsdl. WSDL 2.0 became a W3C Recommendation in 2007 but the market never adopted it — Java and .NET tooling has patchy support, and 99% of what you will meet is WSDL 1.1.

Part 5 — Contract-first versus code-first

Diagram: contract-first versus code-first generation paths — نمودار: دو مسیر تولید کد.

flowchart LR
  subgraph CF["Contract-first"]
    X[XSD + WSDL] -->|wsdl2java / wsimport| J1[Generated Java stubs]
    J1 --> I1[Your implementation]
  end
  subgraph CoF["Code-first"]
    J2["@WebService Java class"] -->|wsgen / runtime| W2["Generated WSDL"]
    W2 --> C2[Consumers]
  end

The code-first route with JAX-WS: annotate the class with @WebService(name=…, serviceName=…, targetNamespace=…), pin the message style with @SOAPBinding(style=DOCUMENT, use=LITERAL, parameterStyle=WRAPPED), and name every operation, parameter and result with @WebMethod(operationName=…, action=…), @WebParam(name=…, targetNamespace=…) and @WebResult. If you leave those names implicit, the framework derives them from your Java method and parameter names — meaning your contract is tied to local variable names. Since Jakarta EE 9 the packages moved from javax.jws to jakarta.jws (see java-ee-jakarta).

Bind the CXF plugin to the generate-sources phase, set sourceRoot to target/generated-sources/cxf, and point wsdlOptions/wsdlOption/wsdl at the WSDL file; extra switches (-p to map a namespace to a package, -validate) go inside extraargs. The same operations from the command line:

wsdl2java -d target/generated-sources -p example.accounts.gen \
          -validate src/main/resources/wsdl/accounts-v1.wsdl   # client + data types
wsdl2java -impl -server src/main/resources/wsdl/accounts-v1.wsdl   # server skeleton
xjc -d target/generated-sources -p example.accounts.gen accounts-v1.xsd   # XSD only

Part 6 — XML in Java: JAXB, performance and safety

JAXB (Jakarta XML Binding) bridges XML and Java objects: marshalling is object → XML, unmarshalling is XML → object. The mapping you should know by heart:

XML security: XXE and entity bombs

XXE (XML External Entity) is when an attacker declares an external entity in the input and your parser cheerfully reads a server file or calls an internal address:

<!DOCTYPE root [ <!ENTITY xxe SYSTEM "file:///etc/passwd"> ]>
<GetBalanceRequest xmlns="http://bank.example/accounts/v1">
  <accountNumber>&xxe;</accountNumber>
</GetBalanceRequest>

SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setNamespaceAware(true);
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);
spf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);

XMLReader reader = spf.newSAXParser().getXMLReader();
Object result = CTX.createUnmarshaller()
                   .unmarshal(new SAXSource(reader, new InputSource(inputStream)));

// If you use StAX instead:
XMLInputFactory xif = XMLInputFactory.newFactory();
xif.setProperty(XMLInputFactory.SUPPORT_DTD, false);
xif.setProperty(XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES, false);

Part 7 — Spring Web Services in practice

Spring-WS is deliberately contract-first only, and it works like Spring MVC with one difference: dispatching is by payload root, not by URL. Version 4.1.x sits on Spring Framework 6 and Jakarta EE 10; version 5.0.0 (November 2025) moved to Spring Framework 7, Spring Security 7 and Jakarta EE 11 (Servlet 6.1) with full JSpecify null-safety. Dependencies: spring-boot-starter-web-services plus wsdl4j.

The entry point is a MessageDispatcherServlet registered on /ws/*; always call setTransformWsdlLocations(true) on it so the address inside the published WSDL is rewritten with the real request host.

@EnableWs
@Configuration
public class WebServiceConfig implements WsConfigurer {

    @Bean(name = "accounts")     // the bean name becomes the path: /ws/accounts.wsdl
    public DefaultWsdl11Definition accountsWsdl() {
        DefaultWsdl11Definition wsdl = new DefaultWsdl11Definition();
        wsdl.setPortTypeName("AccountPortType");
        wsdl.setLocationUri("/ws");
        wsdl.setTargetNamespace("http://bank.example/accounts/v1/wsdl");
        wsdl.setSchema(new SimpleXsdSchema(new ClassPathResource("xsd/accounts-v1.xsd")));
        return wsdl;
    }

    @Override
    public void addInterceptors(List<EndpointInterceptor> interceptors) {
        PayloadValidatingInterceptor v = new PayloadValidatingInterceptor();
        v.setSchema(new ClassPathResource("xsd/accounts-v1.xsd"));
        v.setValidateRequest(true);
        v.setValidateResponse(true);
        interceptors.add(v);
    }
}

@Endpoint
public class AccountEndpoint {
    @PayloadRoot(namespace = "http://bank.example/accounts/v1",
                 localPart = "GetBalanceRequest")
    @ResponsePayload
    public GetBalanceResponse getBalance(@RequestPayload GetBalanceRequest request) {
        return balances.lookup(request.getAccountNumber());
    }
}

DefaultWsdl11Definition generates the WSDL from the XSD using a naming convention: an element suffixed Request is an input, its Response twin the output, and Fault the error. Dispatch is on the namespace + localPart of the Body root element — so ten operations can share one URL. To turn an exception into a fault, annotate the exception class with @SoapFault(faultCode = FaultCode.CLIENT, faultStringOrReason = "…"). On the client side, build a WebServiceTemplate with a Jaxb2Marshaller and an HttpComponents5MessageSender (which takes connectionTimeout and readTimeout) and call marshalSendAndReceive.

Part 8 — Apache CXF

CXF covers both JAX-WS (SOAP) and JAX-RS (REST) and has far deeper WS-* support. The stable line is 4.2.x (4.2.3 in mid-2026), targeting Jakarta EE 11 and JDK 17+; use org.apache.cxf:cxf-spring-boot-starter-jaxws with cxf.path=/services. On the server you create an EndpointImpl and publish it with setAddress("/accounts/v1"), setWsdlLocation("classpath:wsdl/accounts-v1.wsdl") and setPublishedEndpointUrl(...) — that last one is CXF's fix for the internal-pod-address-in-WSDL trap. On the client:

JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();
factory.setServiceClass(AccountPortType.class);
factory.setAddress("https://soa.bank.example/services/accounts/v1");
AccountPortType port = (AccountPortType) factory.create();

HTTPConduit conduit = (HTTPConduit) ClientProxy.getClient(port).getConduit();
HTTPClientPolicy policy = new HTTPClientPolicy();
policy.setConnectionTimeout(3_000);      // milliseconds
policy.setReceiveTimeout(10_000);
policy.setAllowChunking(false);          // some legacy servers cannot handle chunking
conduit.setClient(policy);

Part 9 — The WS-* specs a bank will ask about

"WS-*" is a family of specifications layered on SOAP, each solving one cross-cutting concern. They all live in the message header, which is why they work independently of transport.

9.1 WS-Security — security at the message level

TLS gives you transport-level security: encrypted from A to B, but plaintext the moment it lands on B. If the message crosses three gateways it is exposed at all three. WS-Security gives you message-level security: the signature and encryption sit on the content itself and survive to the final destination. Cryptographic fundamentals are in crypto-foundations and pki-tls-gpg.

<soap:Header>
  <wsse:Security soap:mustUnderstand="1"
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsu:Timestamp wsu:Id="TS-1">
      <wsu:Created>2026-08-13T09:15:00Z</wsu:Created>
      <wsu:Expires>2026-08-13T09:20:00Z</wsu:Expires>
    </wsu:Timestamp>
    <wsse:UsernameToken wsu:Id="UT-1">
      <wsse:Username>loan-service</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">s3cr3t</wsse:Password>
      <wsse:Nonce>5uW2rF0z2Q0yQ0uH2QW5wA==</wsse:Nonce>
      <wsu:Created>2026-08-13T09:15:00Z</wsu:Created>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

Switch the Type to …#PasswordDigest and the password value becomes Base64( SHA-1( nonce + created + password ) ).

The real power of WS-Security is signing and encrypting parts of the message: "encrypt only <CardNumber> and sign the whole Body". Configuring that in CXF with WSS4J (current line 4.0.x):

Map<String, Object> p = new HashMap<>();
p.put(ConfigurationConstants.ACTION, ConfigurationConstants.TIMESTAMP + " "
      + ConfigurationConstants.USERNAME_TOKEN + " " + ConfigurationConstants.SIGNATURE);
p.put(ConfigurationConstants.USER, "loan-service");
p.put(ConfigurationConstants.PASSWORD_TYPE, WSConstants.PW_TEXT);
p.put(ConfigurationConstants.PW_CALLBACK_REF, new ClientPasswordCallback());
p.put(ConfigurationConstants.SIGNATURE_USER, "loan-signing-key");
p.put(ConfigurationConstants.SIG_ALGO, "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256");
p.put(ConfigurationConstants.SIG_PROP_FILE, "client-crypto.properties");
p.put(ConfigurationConstants.SIGNATURE_PARTS,
      "{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body");
p.put(ConfigurationConstants.TTL_TIMESTAMP, "300");
client.getOutInterceptors().add(new WSS4JOutInterceptor(p));

client-crypto.properties points at the keystore via org.apache.wss4j.crypto.merlin.keystore.type=pkcs12, …keystore.file and …keystore.alias. In Spring-WS the same job is done by Wss4jSecurityInterceptor with validationActions="Timestamp UsernameToken Signature", timestampStrict=true and timeToLive=300.

Diagram: receiver-side WS-Security processing order — نمودار: ترتیب پردازش امنیت پیام در سمت گیرنده.

flowchart TD
  A[Raw envelope arrives] --> B{Timestamp valid and fresh?}
  B -- no --> F[Fault: InvalidSecurityToken]
  B -- yes --> C{Nonce already seen?}
  C -- yes --> F
  C -- no --> D[Verify signature over signed parts]
  D -- invalid --> F
  D -- valid --> E[Decrypt encrypted parts]
  E --> G[Authenticate UsernameToken or X.509 subject]
  G --> H[Dispatch to endpoint]

9.2 WS-Addressing

Over HTTP the "destination" is the URL and the reply comes back on the same connection. But what if the message travels over JMS? Or the reply must go somewhere else entirely? WS-Addressing moves that information out of the transport and into the message header. The namespace (W3C Recommendation, 2006) is http://www.w3.org/2005/08/addressing.

<soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <wsa:To>https://soa.bank.example/services/accounts/v1</wsa:To>
  <wsa:Action>http://bank.example/accounts/v1/GetBalance</wsa:Action>
  <wsa:MessageID>urn:uuid:7f3a9c22-1e44-4a0b-9a11-88b2c4d5e6f7</wsa:MessageID>
  <wsa:ReplyTo><wsa:Address>https://loans.bank.example/callbacks</wsa:Address></wsa:ReplyTo>
</soap:Header>

The response carries <wsa:RelatesTo> echoing the request's MessageID — standard, machine-readable correlation. Enable it in CXF with @Addressing(enabled = true, required = true) on the implementation class.

Diagram: asynchronous callback correlation with WS-Addressing — نمودار: پاسخ نامتقارن با WS-Addressing.

sequenceDiagram
  participant C as Consumer
  participant P as Provider
  participant CB as Callback endpoint
  C->>P: Request (MessageID=urn:uuid:A, ReplyTo=CB)
  P-->>C: HTTP 202 Accepted (no body)
  Note over P: Long-running processing
  P->>CB: Response (RelatesTo=urn:uuid:A)
  CB-->>P: HTTP 202 Accepted

9.3 WS-ReliableMessaging

Sender and receiver establish a sequence; every message carries a MessageNumber and the receiver returns a SequenceAcknowledgement. No ack, resend. The selectable guarantees are AtMostOnce, AtLeastOnce, ExactlyOnce and InOrder.

Diagram: lifecycle of a WS-RM sequence — نمودار: چرخه‌ی حیات یک sequence.

stateDiagram-v2
  [*] --> Creating: CreateSequence
  Creating --> Active: CreateSequenceResponse
  Active --> Active: Message(n) / Acknowledgement
  Active --> Retrying: ack timeout
  Retrying --> Active: ack received
  Retrying --> Faulted: max retries exceeded
  Active --> Terminated: TerminateSequence
  Faulted --> [*]
  Terminated --> [*]

9.4 MTOM — attachments without base64 bloat

A one-megabyte PDF inside XML must be base64-encoded: roughly 33% larger, and the whole string sits in memory. MTOM, using XOP, pulls the bytes out into a separate MIME part and leaves only a pointer in the XML; the whole message becomes a multipart/related; type="application/xop+xml":

<content>
  <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include"
               href="cid:statement@example"/>
</content>

The matching MIME part carries Content-ID: <statement@example> and the raw PDF bytes. In Java you simply declare the element as xsd:base64Binary with xmime:expectedContentTypes (it maps to a DataHandler) and put @MTOM(enabled = true, threshold = 4096) on the implementation.

Part 10 — SOAP versus REST

When does a bank still pick SOAP? (1) A partner or regulator mandates it — they hand you a WSDL and it is not negotiable; (2) an enforceable contract — an XSD that rejects a malformed message at the boundary has real operational value; (3) digital signatures and non-repudiation — when you must prove years later that a message came from a specific party unaltered; (4) existing investment — hundreds of deployed services, gateways, monitoring and runbooks.

In practice it is almost never "SOAP or REST", it is "SOAP and REST": you either build a REST facade over SOAP (a mobile app should not have to speak XML) or a SOAP facade over REST (your new services are REST but a legacy partner only speaks SOAP). In both cases the adapter must translate only — business logic must not accumulate inside it.

Part 11 — ESB and integration patterns

Canonical data model: instead of N×(N−1) translations, define one shared language so each system only translates to and from canonical — N² becomes 2N.

Apache Camel implements those patterns as code; the current LTS line is 4.22.x (August 2026).

public class PaymentRoute extends RouteBuilder {
    @Override
    public void configure() {
        errorHandler(deadLetterChannel("jms:queue:payments.dlq")
                .maximumRedeliveries(3).redeliveryDelay(2000).backOffMultiplier(2));

        from("cxf:bean:paymentSoapEndpoint")               // SOAP intake
            .idempotentConsumer(simple("${body.transactionId}"),
                    MemoryIdempotentRepository.memoryIdempotentRepository(10_000))
            .wireTap("jms:queue:audit.copy")               // Wire Tap
            .bean(PaymentNormaliser.class, "toCanonical")  // Message Translator
            .choice()                                      // Content-Based Router
                .when(simple("${body.channel} == 'INTERNAL'")).to("jms:queue:core.transfer")
                .when(simple("${body.amount} > 500000000")).to("jms:queue:aml.review")
                .otherwise().to("cxf:bean:interbankSoapClient")
            .end();
    }
}

Diagram: a realistic integration route composed of several EIPs — نمودار: یک مسیر یکپارچه‌سازی واقعی.

flowchart LR
  A[SOAP endpoint] --> B[Idempotent consumer]
  B --> C[Wire tap to audit]
  B --> D[Translator: legacy to canonical]
  D --> E{Content-based router}
  E -->|internal| F[Core transfer queue]
  E -->|high value| G[AML review queue]
  E -->|other| H[Interbank SOAP client]
  H -->|error after retries| I[(Dead letter queue)]

Traditional ESBs had three structural problems: a central bottleneck and single point of failure (one bad route takes the whole bus down); unclear ownership (business logic lived in the ESB's GUI console, with no code review and no automated tests); and an organisational bottleneck (every small change queued behind the integration team). The industry's answer was "smart endpoints, dumb pipes". That did not kill the patterns — Camel is alive and widely used, it is just a library inside your service instead of a central product.

Part 12 — Testing, debugging and operations

SoapUI (open-source line 5.x) is still the fastest way into an unfamiliar WSDL: New SOAP Project with the WSDL URL builds a sample request per operation; in Auth you configure WSS-Username Token or WSS Signature; the Raw tab shows the exact bytes on the wire and solves 90% of debugging sessions; and MockService generates a stand-in service from the same WSDL. Run that mock in CI — the day the counterparty changes their WSDL, the mock stops matching your code and you find out before production. Lighter Java alternatives: WireMock or Testcontainers (see testing). In Postman you build it by hand: POST, a raw → XML body, and the Content-Type and SOAPAction headers.

curl -v --http1.1 -X POST 'https://soa.bank.example/services/accounts/v1' \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: "http://bank.example/accounts/v1/GetBalance"' \
  --cert client.pem --key client.key --cacert ca.pem \
  --data-binary @request.xml | xmllint --format -

xmllint --noout --schema accounts-v1.xsd response-body.xml    # validate a saved response

A typical audit table — a trace of messages that stores no sensitive content:

CREATE TABLE soap_audit (
  id          bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  correlation text        NOT NULL,
  operation   text        NOT NULL,
  fault_code  text,
  duration_ms integer,
  created_at  timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX idx_audit_fault ON soap_audit (created_at DESC) WHERE fault_code IS NOT NULL;

CREATE TABLE soap_audit (
  id          NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  correlation VARCHAR2(64)  NOT NULL,
  operation   VARCHAR2(128) NOT NULL,
  fault_code  VARCHAR2(128),
  duration_ms NUMBER(10),
  created_at  TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL
);
-- Oracle has no partial index; this function-based index stores no fault-free rows
CREATE INDEX idx_audit_fault
  ON soap_audit (CASE WHEN fault_code IS NULL THEN NULL ELSE created_at END);

For monitoring (see observability) export: request rate per operation, p95 and p99 latency, fault rate broken down by code (a spike in Sender means a client broke, a spike in Receiver means you did), and days remaining until your signing certificate expires. Set hard limits too: in CXF the org.apache.cxf.stax.maxChildElements, maxElementDepth, maxTextLength and attachment-max-size properties stop denial-of-service by oversized payloads.

Part 13 — Financial message formats: ISO 8583 and ISO 20022

ISO 8583 is the card-transaction message standard (ATM, POS, bank switches). Unlike SOAP it is not textual and tag-based; it is binary and positional. It has three parts: an MTI (four digits encoding version, message class, function and origin — 0100 an authorisation request and 0110 its response, 0200 a financial request, 0400 a reversal); a bitmap (a 64-bit map saying which fields are present; bit 1 set means a second bitmap follows); and the data elements.

ISO 20022 is an XML-based financial messaging standard that replaces positional bitmaps with named, structured fields. Message names follow a pattern: pacs.008 (customer credit transfer), pacs.002 (status report), pain.001 (payment initiation), camt.053 (statement).

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.10">
  <FIToFICstmrCdtTrf>
    <GrpHdr><MsgId>MSG-20260813-0001</MsgId><NbOfTxs>1</NbOfTxs></GrpHdr>
    <CdtTrfTxInf>
      <PmtId><EndToEndId>E2E-778812</EndToEndId></PmtId>
      <IntrBkSttlmAmt Ccy="EUR">1250.00</IntrBkSttlmAmt>
      <Dbtr><Nm>Sender Name</Nm></Dbtr>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>

ISO 20022 is a schema, not a transport: that XML usually travels inside a SOAP message, over a queue, or in a batch file. Which means the skills in this chapter — XSD, namespaces, validation, JAXB, XML signatures — are exactly the skills an ISO 20022 project needs.

Part 14 — Cheat sheet

Part 15 — The remaining interview questions