Notes on WSDL and SOAP

General Concepts

Both WSDL and SOAP are related to web service. But do not get confused. The WSDL file describes the web service as its name "Web Servcice Description Language" implies. The SOAP is a protocol. Loosely speaking, a WSDL file describes what services the web service can do and what protocol is used to impement the web service. The protocol is usually SOAP.

In a WSDL file, an wsdl:operation is like an API. It has the wsdl:input, wsdl:output, and the optional wsdl:fault child elements.

The operation is implemented in a protocol described in the binding element. The protocol is usually SOAP. Within the binding, you can see that for every wsdl:operation defined in the wsdl:portType, there is the corresponding soap element for the operation, input, output, and the optional fault elements. More formally, a wsdl:binding defines message format and protocol details for operations and messages defined by a particular portType.

The web service implementation needs to be hosted at some place. For this, WSDL uses the wsdl:port element, which is a combination of a binding and a network address. A port is also called an endpoint.

A set of soap:operation forms a wsdl:portType.

A wsdl:service is a collection of ports.

Notes on Spring Web Service

Spring Web service is an open source product aiming to facilitate contract-first SOAP service development. When you use Spring Web Services, you just need to create xml schmas to define the messages. The wsdl file will be generated automatically. The generated WSDL file may not contain the wsdl:fault element at all. But this does not mean the web service will not return any fault messages. Actually Spring Web Services has a feature to convert exceptions to fault messages. The following is the bean configuration for such conversion:

<bean
class="org.springframework.ws.soap.server.endpoint.SoapFaultAnnotationExceptionResolver">
  <description>
   This exception resolver maps exceptions with the @SoapFault annotation to SOAP Faults. 
  </description>
  <property name="order" value="1" />
 </bean>

 <bean
class="org.springframework.ws.soap.server.endpoint.SoapFaultMappingExceptionResolver">
  <description>
   This exception resolver maps other exceptions to SOAP Faults. Both
   UnmarshallingException and ValidationFailureException are mapped to a SOAP Fault with a "Client" fault code. All other exceptions are mapped to a "Server" error code, the default.
  </description>
  <property name="defaultFault" value="SERVER" />
  <property name="exceptionMappings">
   <props>
    <prop key="org.springframework.oxm.UnmarshallingFailureException">CLIENT,Invalid request</prop>
    <prop key="org.springframework.oxm.ValidationFailureException">CLIENT,Invalid request</prop>
   </props>
  </property>
  <property name="order" value="2" />
 </bean>

The following is an actual fault message from the log file of a Spring web service:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header />
 <env:Body>
  <env:Fault xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/">
   <faultcode>ns0:Server</faultcode>
   <faultstring xml:lang="en">
PreparedStatementCallback;uncategorized SQLException for ...
   </faultstring>
  </env:Fault>
 </env:Body>
</env:Envelope>

Reference

[1]http://www.w3.org/TR/wsdl
[2]http://www.w3.org/2001/03/14-annotated-WSDL-examples.html