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.

Contract-First Web Services in practice - part 1 of 5.

I've recently been working on a SaaS project where I'm integrating different ISVs (Independent Software Vendors) into a SaaS aggregation platform with a market place environment. Users come to the marketplace, purchase subscriptions to the ISVs' applications and realtime provisioning is expected. An exciting opportunity to test a SOA paradigm as SOAP web-services are a crucial medium of the SOA model and was the first solution to jump to my mind.

Once my approach was selected, my next task was to define a service specification that I would expect the ISVs to implement. This started out as a document with a list of methods and attributes encompassing the functionality I would expect the ISVs to expose. Once this was done, I needed to create a reference implementation in .NET, Java and PHP, and that's where the problems began.

My aim was to create a single WSDL which could easily be implemented in the 3 main programming languages so that only a single client is written. The main issues I had to address are summarized below:

• Creating a consistent doc/literal format style WSDL
• Working effectively with arrays in XSD schema
• Working effectively with typed exceptions - what is the best way of creating Soap Faults?
• JAX-WS, JAX-RPC, Axis, .NET ASMX, WCF, PHP-SOAP, NU-SOAP - just a snapshot of the different SOAP stacks in common use.
• Contract-First SOA

I'll be detailing the challenges I faced in a series of 5 tutorials on how to create a non-trivial WSDL and implement it in the 3 programming languages.