Contract-First Web Services in practice - part 2 of 5

This is article is the second part of a five article series on a working example of SOA at work. In the last article I introduced the challenge, coming up with a fairly robust WSDL which could be implemented in multiple different programming languages consistently.

The service we are creating has one operation. The input for this sample operation takes an xml message with one element as well as an array of a nested object. The output returns an array of the same input objects (I had to redact the more meaningful input and output messages as they were work related). It initially seems complicated because I'm trying to capture all the complexities of xml structures and how the map to data structures that programmers in modern programming languages often take for granted. Ok, enough introduction, let's get onto the WSDL.

WSDL

+ expand sourceview plaincopy to clipboardprint?

1. <?xml version="1.0" encoding="utf-8"?>
2. <wsdl:definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://kimenye.com/soap/" xmlns:impl="http://kimenye.com/soap/" xmlns:xsd1="http://kimenye.com/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" name="SampleService" targetNamespace="http://kimenye.com/soap/">
3. <wsdl:types>
4. <xsd:schema elementFormDefault="qualified" targetNamespace="http://kimenye.com/soap/">
6. <!-- Exception message, contains a string with the field message -->
7. <xsd:complexType name="ServiceException">
8. <xsd:sequence>
9. <xsd:element name="message" nillable="true" type="xsd:string"/>
10. </xsd:sequence>
11. </xsd:complexType>
13. <!-- A sample field with two elements, FieldName and FieldValue -->
14. <xsd:complexType name="SampleField">
15. <xsd:sequence>
16. <xsd:element minOccurs="1" maxOccurs="1" name="FieldName" type="xsd:string"/>
17. <xsd:element minOccurs="1" maxOccurs="1" name="FieldValue" type="xsd:string"/>
18. </xsd:sequence>
19. </xsd:complexType>
21. <!-- An array of sample fields -->
22. <xsd:complexType name="ArrayOfSampleField">
23. <xsd:sequence>
24. <xsd:element minOccurs="0" maxOccurs="unbounded" name="SampleField" nillable="true" type="tns:SampleField"/>
25. </xsd:sequence>
26. </xsd:complexType>
28. <xsd:complexType name="AnObject">
29. <xsd:sequence>
30. <xsd:element minOccurs="0" maxOccurs="1" name="DemoField" type="xsd:string" nillable="true"/>
31. <xsd:element minOccurs="0" maxOccurs="1" name="SampleFields" type="tns:ArrayOfSampleField"/>
32. </xsd:sequence>
33. </xsd:complexType>
35. <xsd:complexType name="ArrayOfReturnObjects">
36. <xsd:sequence>
37. <xsd:element minOccurs="0" maxOccurs="unbounded" name="AnObject" nillable="true" type="tns:AnObject"/>
38. </xsd:sequence>
39. </xsd:complexType>
41. <xsd:element name="ServiceException" type="tns:ServiceException"/>
42. <xsd:element name="in" type="tns:AnObject" />
43. <xsd:element name="out" type="tns:ArrayOfReturnObjects" />
45. </xsd:schema>
46. </wsdl:types>
48. <message name="ServiceException">
49. <part name="ServiceException" element="tns:ServiceException"/>
50. </message>
52. <message name="InputRequest">
53. <part name="in" element="tns:in"/>
54. </message>
56. <message name="OutputResponse">
57. <part name="out" element="tns:out"/>
58. </message>
60. <portType name="SampleServicePortType">
61. <operation name="SampleOperation">
62. <input message="tns:InputRequest"/>
63. <output message="tns:OutputRequest"/>
64. <fault name="ServiceException" message="tns:ServiceException"/>
65. </operation>
66. </portType>
68. <binding name="SampleServiceBinding" type="tns:SampleServicePortType">
69. <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
70. <operation name="SampleOperation">
71. <soap:operation soapAction="urn://SampleService#SampleOperation"/>
72. <input>
73. <soap:body use="literal"/>
74. </input>
75. <output>
76. <soap:body use="literal"/>
77. </output>
78. <fault name="ServiceException">
79. <soap:fault name="ServiceException" use="literal"/>
80. </fault>
81. </operation>
82. </binding>
83. <service name="SampleService">
84. <port name="SampleServicePort" binding="tns:SampleServiceBinding">
85. <soap:address location="http://127.0.0.1:8000/index.php"/>
86. </port>
87. </service>
88. </wsdl:definitions>

<?xml version="1.0" encoding="utf-8"?><br /><wsdl:definitions xmlns="http://schemas.xmlsoap.org/wsdl/" tns="http://kimenye.com/soap/" impl="http://kimenye.com/soap/" xsd1="http://kimenye.com/soap/" xsd="http://www.w3.org/2001/XMLSchema" wsdl="http://schemas.xmlsoap.org/wsdl/" soap="http://schemas.xmlsoap.org/wsdl/soap/" soapenc="http://schemas.xmlsoap.org/soap/encoding/" name="SampleService" targetnamespace="http://kimenye.com/soap/"><br /> <wsdl:types><br /> <xsd:schema elementformdefault="qualified" targetnamespace="http://kimenye.com/soap/"><br /> <br /> <!-- Exception message, contains a string with the field message --><br /> <xsd:complextype name="ServiceException"><br /> <xsd:sequence><br /> <xsd:element name="message" nillable="true" type="xsd:string"><br /> </xsd:sequence><br /> </xsd:complexType><br /> <br /> <!-- A sample field with two elements, FieldName and FieldValue --><br /> <xsd:complextype name="SampleField"><br /> <xsd:sequence><br /> <xsd:element minoccurs="1" maxoccurs="1" name="FieldName" type="xsd:string"><br /> <xsd:element minoccurs="1" maxoccurs="1" name="FieldValue" type="xsd:string"><br /> </xsd:sequence><br /> </xsd:complexType><br /> <br /> <!-- An array of sample fields --><br /> <xsd:complextype name="ArrayOfSampleField"><br /> <xsd:sequence><br /> <xsd:element minoccurs="0" maxoccurs="unbounded" name="SampleField" nillable="true" type="tns:SampleField"><br /> </xsd:sequence><br /> </xsd:complexType><br /><br /> <xsd:complextype name="AnObject"><br /> <xsd:sequence><br /> <xsd:element minoccurs="0" maxoccurs="1" name="DemoField" type="xsd:string" nillable="true"><br /> <xsd:element minoccurs="0" maxoccurs="1" name="SampleFields" type="tns:ArrayOfSampleField"><br /> </xsd:sequence><br /> </xsd:complexType><br /><br /> <xsd:complextype name="ArrayOfReturnObjects"><br /> <xsd:sequence><br /> <xsd:element minoccurs="0" maxoccurs="unbounded" name="AnObject" nillable="true" type="tns:AnObject"><br /> </xsd:sequence><br /> </xsd:complexType><br /> <br /> <xsd:element name="ServiceException" type="tns:ServiceException"><br /> <xsd:element name="in" type="tns:AnObject"><br /> <xsd:element name="out" type="tns:ArrayOfReturnObjects"><br /> <br /> </xsd:schema><br /> </wsdl:types><br /> <br /> <message name="ServiceException"><br /> <part name="ServiceException" element="tns:ServiceException"><br /> </message><br /> <br /> <message name="InputRequest"><br /> <part name="in" element="tns:in"><br /> </message><br /> <br /> <message name="OutputResponse"><br /> <part name="out" element="tns:out"><br /> </message><br /> <br /> <porttype name="SampleServicePortType"><br /> <operation name="SampleOperation"><br /> <input message="tns:InputRequest"><br /> <output message="tns:OutputRequest"><br /> <fault name="ServiceException" message="tns:ServiceException"><br /> </operation><br /> </porttype><br /> <br /> <binding name="SampleServiceBinding" type="tns:SampleServicePortType"><br /> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"><br /> <operation name="SampleOperation"><br /> <soap:operation soapaction="urn://SampleService#SampleOperation"><br /> <input><br /> <soap:body use="literal"><br /> </input><br /> <output><br /> <soap:body use="literal"><br /> </output><br /> <fault name="ServiceException"><br /> <soap:fault name="ServiceException" use="literal"><br /> </fault><br /> </operation><br /> </binding><br /> <service name="SampleService"><br /> <port name="SampleServicePort" binding="tns:SampleServiceBinding"><br /> <soap:address location="http://127.0.0.1:8000/sso.php"><br /> </port><br /> </service><br /></wsdl:definitions>

Click the expand source link and voila! That's the WSDL. Now to run you through the xml elements that constitute this WSDL.

Exceptions

Exceptions in SOAP are xml messages that can be defined in the schema. For this example, the exception is aptly named ServiceException, and it has an element named "message" which happens to be a string.

view plaincopy to clipboardprint?

1. <!-- Exception message, contains a string with the field message -->
2. <xsd:complexType name="ServiceException">
3. <xsd:sequence>
4. <xsd:element name="message" nillable="true" type="xsd:string"/>
5. </xsd:sequence>
6. </xsd:complexType>

<!-- Exception message, contains a string with the field message --><br /> <xsd:complextype name="ServiceException"><br /> <xsd:sequence><br /> <xsd:element name="message" nillable="true" type="xsd:string"><br /> </xsd:sequence><br /></xsd:complexType>

Arrays & Collections

There are several ways to represent arrays in XML. I've chosen for this sample, the simplest way which is to use the xml attribute "maxOccurs" and set it to "unbounded".

view plaincopy to clipboardprint?

1. <!-- A sample field with two elements, FieldName and FieldValue -->
2. <xsd:complexType name="SampleField">
3. <xsd:sequence>
4. <xsd:element minOccurs="1" maxOccurs="1" name="FieldName" type="xsd:string"/>
5. <xsd:element minOccurs="1" maxOccurs="1" name="FieldValue" type="xsd:string"/>
6. </xsd:sequence>
7. </xsd:complexType>
9. <!-- An array of sample fields -->
10. <xsd:complexType name="ArrayOfSampleField">
11. <xsd:sequence>
12. <xsd:element minOccurs="0" maxOccurs="unbounded" name="SampleField" nillable="true" type="tns:SampleField"/>
13. </xsd:sequence>
14. </xsd:complexType>

<!-- A sample field with two elements, FieldName and FieldValue --><br /> <xsd:complextype name="SampleField"><br /> <xsd:sequence><br /> <xsd:element minoccurs="1" maxoccurs="1" name="FieldName" type="xsd:string"><br /> <xsd:element minoccurs="1" maxoccurs="1" name="FieldValue" type="xsd:string"><br /> </xsd:sequence><br /> </xsd:complexType><br /> <br /> <!-- An array of sample fields --><br /> <xsd:complextype name="ArrayOfSampleField"><br /> <xsd:sequence><br /> <xsd:element minoccurs="0" maxoccurs="unbounded" name="SampleField" nillable="true" type="tns:SampleField"><br /> </xsd:sequence><br /> </xsd:complexType>

Declarative SOAP Exceptions

For this sample, soap exceptions are declared in the WSDL, this is in order to detect multiple exceptions. In this sample, we only have ServiceException, but could have included others, to programmatically detect which exception was thrown. This declaration is achieved by using the "fault" element. Note that the exception needs to be declared in both the binding and port type.

view plaincopy to clipboardprint?

1. <binding name="SampleServiceBinding" type="tns:SampleServicePortType">
2. <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
3. <operation name="SampleOperation">
4. <soap:operation soapAction="urn://SampleService#SampleOperation"/>
5. <input>
6. <soap:body use="literal"/>
7. </input>
8. <output>
9. <soap:body use="literal"/>
10. </output>
11. <fault name="ServiceException">
12. <soap:fault name="ServiceException" use="literal"/>
13. </fault>
14. </operation>
15. </binding>

<binding name="SampleServiceBinding" type="tns:SampleServicePortType"><br /> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"><br /> <operation name="SampleOperation"><br /> <soap:operation soapaction="urn://SampleService#SampleOperation"><br /> <input><br /> <soap:body use="literal"><br /> </input><br /> <output><br /> <soap:body use="literal"><br /> </output><br /> <fault name="ServiceException"><br /> <soap:fault name="ServiceException" use="literal"><br /> </fault><br /> </operation><br /> </binding>

That's it for the most part. In the next article, I'll be looking at the PHP implementation of this WSDL.