Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท WSDL and Contracts

WSDL Bindings, Ports and Faults in Detail

Go deeper into WSDL: binding style and use, rpc vs document parts, faults in the contract, one-way operations, SOAP 1.1 and 1.2 ports, and how clients discover a WSDL at ?wsdl.

WSDL Structure gave you the overview. This lesson zooms in on the parts that cause the most trouble in practice: the binding (how messages are encoded), the port (where the service lives), the fault declarations, one-way operations and how clients get hold of the WSDL in the first place.

The binding in detail

A binding has three layers, each adding concrete information to the abstract portType:

XML
<binding name="OrderBinding" type="tns:OrderPortType">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>   <!-- 1: default for the whole binding -->
  <operation name="PlaceOrder">
    <soap:operation soapAction="urn:orders/PlaceOrder" style="document"/>              <!-- 2: per operation -->
    <input>  <soap:body use="literal"/>  </input>                                      <!-- 3: per message -->
    <output> <soap:body use="literal"/> </output>
    <fault name="OutOfStock"> <soap:fault name="OutOfStock" use="literal"/> </fault>
  </operation>
</binding>
  1. soap:binding: transport says HTTP (the URI is a fixed identifier, http://schemas.xmlsoap.org/soap/http), and style is the default for operations (document or rpc).
  2. soap:operation: carries the soapAction string and may override the style.
  3. soap:body (and soap:header, soap:fault): states how each message is serialized: use="literal" or use="encoded". For RPC style you also give the namespace used for the operation wrapper element, because there is no schema element for it.

Parts: element or type

The message parts decide the wire layout together with the style:

Style Part declared with Result in the Body
document element="tns:Add" The element itself is the Body child.
rpc type="xsd:int" (one part per parameter) A wrapper named after the operation, one child per part.
document, wrapped one part, element named like the operation Looks like rpc, validated by schema.

Mixing type= parts with document style is a WS-I violation. If a generator complains about "part must use element", this is why.

Faults in the contract

A WSDL can promise specific faults so that clients can generate typed exceptions. The abstract side declares them in the portType, the concrete side maps them in the binding.

XML
<message name="OutOfStockFault"><part name="detail" element="tns:OutOfStock"/></message>

<portType name="OrderPortType">
  <operation name="PlaceOrder">
    <input message="tns:PlaceOrderIn"/>
    <output message="tns:PlaceOrderOut"/>
    <fault name="OutOfStock" message="tns:OutOfStockFault"/>
  </operation>
</portType>

When the service raises that fault, the <detail> of the SOAP Fault contains an OutOfStock element, and a generated client throws an OutOfStockFault exception. Undeclared failures still arrive as generic SOAP faults.

One-way and other patterns

An operation in the portType can omit output; then it is one-way: the client sends a message and does not wait for a business response (over HTTP only an empty 202 or 200 comes back). Notification operations ("fire and forget") use this. WSDL 1.1 also defined solicit-response and notification from the service side, but tools almost never support them. Request-response and one-way cover nearly everything.

Ports and several bindings

The service element can offer the same portType through several ports. A common setup serves SOAP 1.1 and SOAP 1.2 at different addresses:

XML
<service name="OrderService">
  <port name="OrderPort"      binding="tns:OrderBinding">
    <soap:address location="https://shop.example/ws/orders"/>
  </port>
  <port name="OrderPort12"    binding="tns:OrderBinding12">
    <soap12:address location="https://shop.example/ws/orders12"/>
  </port>
</service>

SOAP 1.2 elements live in another namespace (http://schemas.xmlsoap.org/wsdl/soap12/, prefix soap12). A client library picks one port, usually the first or the one you name.

The location is a promise, not magic. Behind a proxy or load balancer the WSDL often advertises an internal host name such as http://app-server-3:8080/ws, which the outside client cannot reach. Fixes: configure the service to publish its public URL, or override the endpoint in the client. When a call fails with "connection refused" to a strange host, inspect the soap:address.

Generating a binding

The first program writes the binding, portType and service parts of a WSDL from a short operation list, so you can see how the three layers line up. A generator like this is how many frameworks produce a WSDL from code.

Node.js Generate portType, binding and service

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Spot the one-way operation Cancel: its portType and binding have no output.

Discovering the WSDL: ?wsdl

Many toolkits publish the contract at the service URL with ?wsdl appended (https://host/ws/orders?wsdl); others use ?singleWsdl (WCF) or a fixed file path. A client downloads the WSDL, reads the address and actions and builds its calls. The following program publishes the service, its WSDL, and a client that discovers everything from the ?wsdl response, hard-coding nothing except the URL.

Node.js Discovery through ?wsdl

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Common binding mistakes

  • Missing or wrong soapAction. The server rejects the call, or routes it to another operation.
  • style mismatch between WSDL and the code actually running (the WSDL says rpc, the server expects document).
  • use="encoded" left over in a legacy WSDL, producing xsi:type attributes that modern clients cannot validate.
  • Wrong address in soap:address behind proxies and containers.
  • Editing generated WSDLs by hand and drifting away from the running code. Treat the WSDL as generated, or treat the code as generated from it (next lesson).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where in the WSDL do you set style="document" and use="literal"?

    Style and use are concrete details, so they belong to the binding.
  2. 2. What makes an operation one-way?

    An operation with only an input is one-way: the client does not wait for a business response.
  3. 3. A client fails to connect to http://app-server-3:8080/ws, which it never configured. What is the likely cause?

    WSDL generators publish the host they see internally. Configure the public URL or override the endpoint in the client.
  4. 4. Why declare faults in the portType?

    Declared faults give clients typed exceptions; undeclared failures still arrive as generic faults.

Summary

  • The binding adds transport, style, use and soapAction to the abstract interface; the port adds the address.
  • RPC parts use type, document parts use element; wrapped document style is the usual choice.
  • Declare faults in the portType and binding to give clients typed exceptions.
  • Operations without output are one-way.
  • Clients usually fetch the WSDL from ?wsdl; check the advertised address when connections fail.

Next: Contract-First vs Code-First