Configure Tomcat 6 for JAX-WS

As a servlet container, Tomcat is not a full J2EE container hence requires some additional configuration in order to support JAX-WS. This article describes this configuration step-by-step:

1. Download a copy of the JAX-WS library – Instructions here were tested this on version 2.1.5 (https://jax-ws.dev.java.net/2.1.5/)
2. Copy the file JAXWS2.1.5-20081030.jar to an appropriate folder on your computer – say, /root/tools/ JAXWS2.1.5-20081030.jar
3. Execute the jar: java –jar JAXWS2.1.5-20081030.jar
4. This in effect unpacks the files contained in this jar. You should get a folder /root/tools/jaxws-ri containing the supporting libraries, docs, tools and samples. Let’s call this path $JAX-WS-HOME$.
5. Copy the jar files in $JAX-WS-HOME$/lib/ to the Tomcat (let’s call the install path for this $CATALINA_HOME$) library$CATALINA_HOME$/lib and $CATALINA_HOME$/shared/lib path.
6. Create an folder in the Tomcat installation directory called “endorsed”. The full path should be$CATALINA_HOME$/endorsed.
7. Copy the files “jaxb-api.jar” and “jaxws-api.jar” from the “$JAX_WS_HOME$/lib” to the “$CATALINA_HOME$/endorsed/”folder.
8. Edit the Tomcat configuration file “$CATALINA_HOME$/conf/catalina.properties” (You might want to take a backup before you edit it). There should be a property with the key “shared.loader”. Make sure the path $CATALINA_HOME$/shared/lib/*.jar is included in the comma separated list of paths in the value for this property. For example it could look like :shared.loader=/etc/tomcat/shared/lib/*.jar. That’s the main set of configuration that needs to be done.
9. Before running tomcat, ensure the following property is to be set on the script used to start tomcat:
   -Djava.endorsed.dirs=$CATALINA_HOME$\endorsed
10. This ensures the two jars we copied into the endorsed folder are picked up.
11. Start tomcat.

UPDATE: This post makes assumptions about your source and web-archive being correctly set up. When I was doing this, I was working in a Contract-First approach and I wrote a quick guide to that here. This covers how your web.xml and sun-jaxws.xml file should be done. When I get sometime I'll upload a redacted version of my code as it has some work stuff. Good luck!

Contract-First Web Services in practice - part 5 of 5 (Java / J2EE)

This is the last article in the series of 5 and today we're looking at contract first development in Java/J2EE. I've left this for last after considering PHP and NET due to the various application servers and technologies in which this is possible. Java is also my forte hence I'm not shying away from this challenge. We'll look at JAX-WS on J2EE and Tomcat.

JAX-WS / EE5 Application Servers

If you prefer the blue pill and like the neat, java 5+, annotation heavy, jaxws-does-everything-for-you alternate reality, then you're in for a treat. The JAX-WS RI is available in most J2EE servers. I've picked JBOSS (the 4.2.2 GA) which is what I was using for work. JBOSS ships with wstools in the bin directory. Run the command "wsconsume -k SampleService.wsdl". This creates client stubs and a server interface "com.kimenye.SampleServicePortType". This is the class to be implemented. Once this is done, create a web.xml file and create a servlet with the servlet-class as the implementation created. Package this as a web-archive, and pop it into the deploy directory of the app server.

Tomcat 6

Tomcat 6 is a servlet container and not a full J2EE container hence it is not compulsory for it to provide JAX-WS. See my post on how to configure Tomcat 6 to use JAX-WS. Follow the steps below to implement the sample service:

1. Use "wsimport" tool to create the service stubs. This tool is available from the bin directory of an unpacked JAX-WS installation. The full command to run is : wsimport -keep SampleService.wsdl
2. Create a web application in your preffered IDE. Copy the artifacts generated from the wsimport into your source. Implement the port type interface. For our example this class will be com.kimenye.ProvisionServicePortType. Compile the implementations and the generated classes.
   
3. Copy the wsdl into a folder named wsdl under the WEB-INF directory.
4. Create a file named sun-jaxws.xml in the WEB-INF directory and fill in the content below:
   view plaincopy to clipboardprint?

   1. <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
   2. version="2.0">
   3. 
      
   4. <endpoint name="SampleService" interface="com.applicationsnet.service.soap.SampleServicePortType"
   5. implementation=com.kimenye.SampleServiceImpl" wsdl="WEB-INF/wsdl/SampleService.wsdl"
   6. service="{http://kimenye.com/}SampleService" port="{http://kimenye.com/}SampleServicePort"
   7. url-pattern="/SampleService" />
   8. 
      
   9. </endpoints>

   <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"<br /> version="2.0"><br /><br /> <endpoint name="SampleService" interface="com.applicationsnet.service.soap.SampleServicePortType"<br /> implementation=com.kimenye.SampleServiceImpl" wsdl="WEB-INF/wsdl/SampleService.wsdl"<br /> service="{http://kimenye.com/}SampleService" port="{http://kimenye.com/}SampleServicePort"<br /> url-pattern="/SampleService" /><br /><br /></endpoints>
5. Edit the web.xml file to include the content below:
   view plaincopy to clipboardprint?

   1. <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   2. xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
   3. version="2.4">
   5. <description>sample</description>
   6. <display-name>sample</display-name>
   8. <listener>
   9. <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
   10. </listener>
   12. <servlet>
   13. <description>Sample End-Point</description>
   14. <display-name>Sample End-Point</display-name>
   15. <servlet-name>SampleServicePortType</servlet-name>
   16. <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
   17. <load-on-startup>1</load-on-startup>
   18. </servlet>
   20. <servlet-mapping>
   21. <servlet-name>SampleServicePortType</servlet-name>
   22. <url-pattern>/SampleService</url-pattern>
   23. </servlet-mapping>
   24. </web-app>

   <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br /> xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"<br /> version="2.4"><br /><br /> <description>sample</description><br /> <display-name>sample</display-name><br /><br /> <listener><br /> <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class><br /> </listener><br /><br /> <servlet><br /> <description>Sample End-Point</description><br /> <display-name>Sample End-Point</display-name><br /> <servlet-name>SampleServicePortType</servlet-name><br /> <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class><br /> <load-on-startup>1</load-on-startup><br /> </servlet><br /> <br /> <servlet-mapping><br /> <servlet-name>SampleServicePortType</servlet-name><br /> <url-pattern>/SampleService</url-pattern><br /> </servlet-mapping><br /></web-app>
6. Create the web-archive file and copy it to your tomcat web applications directory.
7. Edit the startup script for tomcat to include the property : -Dcom.sun.xml.ws.fault.SOAPFaultBuilder.disableCaptureStackTrace=false – This is related to how the soap faults are formatted and is IMPORTANT!
8. Start tomcat and enjoy!

Contract-First Web Services in practice - part 4 of 5 (.NET)

Welcome to part 4 of 5 of this article series putting contract first SOA through its paces. In the last article, I looked at how to create a php implementation of a wsdl defined in part two. In this article we look at how to create a service implementation in the .NET framework. This will be done in Visual Basic but could work for C#.NET.

Contract-first web service development is generally aspired to but often ignored in favour of code-first approaches because it is often quicker to do so. This is more so prevalent in the .NET framework where the ease of developing ".asmx" web services in Visual Studio drives people down this path. One way of creating "contract-first" web services is create a "code-first" one that closely resembles the contract you want to implement. This is may or may not work depending on the complexity of the contract and is not advised. The approach I advise is to create a binding interface using the "wsdl.exe" program that ships as part of the .NET framework or visual studio. With the path to this executable added to the %PATH% environment variable run the following command in a directory containing the wsdl file.

wsdl /language:VB /serverInterface SampleService.wsdl

If C#.NET artifacts are required replace the language with CS. This creates a single file "SampleServiceInterfaces.vb" that contains the data structures defined in the schema of the wsdl. It is heavily annotated to ensure that when the objects are serialized they are in compliance with wsdl. To complete the web service creation follow the steps below:

1. Add the bindings interface to an existing or newly created ASP.NET web site.
2. Now add a new "asmx" web service.
3. Open the code behind class for the new web service. Make this class implement the binding interface instead of extending Service. Visual Studio should now create the stubs for the methods to be implemented.
4. Implement the wsdl methods.

For our example, this should work brilliantly for our wsdl defined except for the typed exceptions. In the "infinite wisdom" of the designers of the .NET framework including thrown exceptions in the method signature is not supported. In fact, the binding interface does not create any types for the exceptions. I've created a custom class that creates the required xml for the exceptions.

view plaincopy to clipboardprint?

1. Imports System.Web.Services.Protocols  
2. Imports System.Xml  
3.    
4.    
5.       Public Class CustomSoapException  
6.             Inherits SoapException  
7.    
8.             Public Enum ExceptionCode  
9.                   ServiceException  
10.             End Enum  
11.    
12.             Public Sub New(ByVal ExCode As ExceptionCode, ByVal Message As String)  
13.                   Me.New(ExCode, SoapException.ClientFaultCode, Message)  
14.             End Sub  
15.    
16.             Public Sub New(ByVal ExCode As ExceptionCode, ByVal SoapFaultCode As XmlQualifiedName, ByVal Message As String)  
17.                   MyBase.New(ExCode.ToString(), SoapFaultCode, Nothing, CreateXmlNode(ExCode, Message))  
18.             End Sub  
19.    
20.             ''' <summary>  
21.             '''  
22.             ''' <ServiceException>  
23.             '''    <message>The exception message goes here.</message>  
24.             ''' </ServiceException>  
25.             '''  
26.             ''' </summary>  
27.             ''' <returns></returns>  
28.             ''' <remarks></remarks>  
29.             Private Shared Function CreateXmlNode(ByVal ExCode As ExceptionCode, ByVal Message As String) As XmlNode  
30.                   Dim doc As New System.Xml.XmlDocument  
31.    
32.                   Dim detailNode As System.Xml.XmlNode = doc.CreateNode(XmlNodeType.Element, SoapException.DetailElementName.Name, _  
33.                               SoapException.DetailElementName.Namespace)  
34.    
35.                   Dim excType As System.Xml.XmlNode = _  
36.                               doc.CreateNode(XmlNodeType.Element, _  
37.                               ExCode.ToString(), _  
38.                               "http://kimenye.com/soap/")  
39.    
40.                   Dim messageNode As System.Xml.XmlNode = _  
41.                               doc.CreateNode(XmlNodeType.Element, _  
42.                               "message", _  
43.                               "http://kimenye.com/soap/")  
44.    
45.    
46.                   messageNode.InnerText = Message  
47.    
48.                   excType.AppendChild(messageNode)  
49.    
50.                   detailNode.AppendChild(excType)  
51.    
52.                   Return detailNode  
53.             End Function  
54.       End Class  

Imports System.Web.Services.Protocols<br />Imports System.Xml<br /> <br /> <br /> Public Class CustomSoapException<br /> Inherits SoapException<br /> <br /> Public Enum ExceptionCode<br /> ServiceException<br /> End Enum<br /> <br /> Public Sub New(ByVal ExCode As ExceptionCode, ByVal Message As String)<br /> Me.New(ExCode, SoapException.ClientFaultCode, Message)<br /> End Sub<br /> <br /> Public Sub New(ByVal ExCode As ExceptionCode, ByVal SoapFaultCode As XmlQualifiedName, ByVal Message As String)<br /> MyBase.New(ExCode.ToString(), SoapFaultCode, Nothing, CreateXmlNode(ExCode, Message))<br /> End Sub<br /> <br /> ''' <summary><br /> '''<br /> ''' <ServiceException><br /> ''' <message>The exception message goes here.</message><br /> ''' </ServiceException><br /> '''<br /> ''' </summary><br /> ''' <returns></returns><br /> ''' <remarks></remarks><br /> Private Shared Function CreateXmlNode(ByVal ExCode As ExceptionCode, ByVal Message As String) As XmlNode<br /> Dim doc As New System.Xml.XmlDocument<br /> <br /> Dim detailNode As System.Xml.XmlNode = doc.CreateNode(XmlNodeType.Element, SoapException.DetailElementName.Name, _<br /> SoapException.DetailElementName.Namespace)<br /> <br /> Dim excType As System.Xml.XmlNode = _<br /> doc.CreateNode(XmlNodeType.Element, _<br /> ExCode.ToString(), _<br /> "http://kimenye.com/soap/")<br /> <br /> Dim messageNode As System.Xml.XmlNode = _<br /> doc.CreateNode(XmlNodeType.Element, _<br /> "message", _<br /> "http://kimenye.com/soap/")<br /> <br /> <br /> messageNode.InnerText = Message<br /> <br /> excType.AppendChild(messageNode)<br /> <br /> detailNode.AppendChild(excType)<br /> <br /> Return detailNode<br /> End Function<br /> End Class

Throw an instance of this class to comply with the wsdl. That's it for the .NET implementation. In the next article I'll detail how to do the implementation in Java and wrap up my thoughts on the process.

Contract-First Web Services in practice - part 3 of 5 (PHP)

Welcome to the third article in this series of 5 where I'm putting contract-first service oriented architecture through its paces. For a recap, in article one I defined the rules of engagement, and article two I outlined the contract for the service to be developed. With this behind us, the next challenge is to begin the representation of this service in the 3 programming languages and PHP is first of the blocks.

There are several libraries for use in tackling SOAP in PHP (Pear, Nu Soap, PHP Soap). Not being my forte, I selected the inbuilt soap library PHP Soap that ships with PHP 5. I needed a simple approach that supported WSDL 1.1 and "document literal". I didn't think this would be too much to ask until I discovered that there was an affinity for "RPC encoded" style of web services which fits in well with positional parameters which are well supported in php.

The first step in implementing the service is to create the endpoint handler. This is the php file at the url which will respond to this service and is set in the soap:address element of the wsdl. In the example wsdl the endpoint is "http://localhost:8080/index.php", so the endpoint handler is the index.php. The content for this file is shown below:

view plaincopy to clipboardprint?

1. <?php
3. //cache the wsdl
4. ini_set("soap.wsdl_cache_enabled", "0");
6. //load the code for the service handler
7. require_once('./SampleServiceClass.php');
9. //create a new soap server. Refer to the wsdl file
10. $server = new SoapServer('SampleService.wsdl');
12. //set the class which will be handling the request
13. $server->setClass('SampleServiceClass');
15. //begin the server
16. $server->handle();
18. ?>

1. The first statement is a directive to cache the wsdl for better performance (suitable for production environments but reasonable in this case as it's contract first so we're taking the WSDL as given).
2. The next statement imports a file SampleServiceClass.php which we have not yet created. More on this soon.
3. The third statement creates a soap server instance. The constructor takes as one of its arguments, the wsdl file defined in article 2.
4. The fourth statement sets the class SampleServiceClass (yet to be defined in the file SampleServiceClass.php)
5. The final statement starts the server instance.

With those five statements, we're setting up the endpoint by tying in the wsdl to the service handler which we will create in the next step.

view plaincopy to clipboardprint?

1. <?php
3. //Exception Types
4. define('SERVICE_EXCEPTION', 'ServiceException'); //thow this error when the user does not exist
7. //Soap Exception Fault Codes
8. define('ERROR_CODE_CLIENT', "Client");
9. define('ERROR_CODE_SERVER', "Server");
11. /**
12. *
13. * This class handles the Sample Service Soap Requests
14. *
15. */
16. class SampleServiceClass
17. {
18. /**
19. * Create an exception
20. *
21. * <ns2:SampleException xmlns:ns2="http://kimenye.com/soap/">
22. * <message>Some weird error occurred</message>
23. * </ns2:SampleException>
24. *
25. * @param object $exception
26. * @return
27. */
28. function createException($exception,$message)
29. {
30. $typedException = new StdClass();
31. $typedException->message = $message;
32. $detail = null;
33. $error_code = ERROR_CODE_CLIENT;
35. if ($exception == SERVICE_EXCEPTION)
36. {
37. $detail->ServiceException = $typedException;
38. }
40. return new SoapFault($error_code,$exception,null,$detail,$exception);
41. }
43. /**
44. * This is the sample operation.
45. *
46. * @param object $SampleOperationRequest
47. *
48. * @return
49. */
50. function SampleOperation($SampleOperationRequest)
51. {
52. $num_of_args = func_num_args();
54. //In this example the custom fields are compulsory
55. if(func_num_args()<1)
56. {
57. return $this->createException(SERVICE_EXCEPTION, "SampleOperationRequest -Incorrect parameters passed in.");
58. }
60. $Demo = $SampleOperationRequest->DemoField;
61. $CustomFields = $SampleOperationRequest->SampleFields;
63. $num_custom_fields = count($CustomFields->SampleField);
65. /**
66. * This is to demonstate how to access the custom fields.
67. *
68. * If only one custom field is required, access is
69. *
70. * $fieldOne = $CustomFields->CustomField->FieldValue
71. */
72. if($num_custom_fields == 2)
73. {
74. if($CustomFields->SampleField[0]->FieldName == 'a field')
75. {
76. $fieldOne = $CustomFields->CustomField[0]->FieldValue;
77. $fieldTwo = $CustomFields->CustomField[1]->FieldValue;
78. }
80. if($CustomFields->SampleField[0]->FieldName == 'another field')
81. {
82. $fieldTwo = $CustomFields->CustomField[0]->FieldValue;
83. $fieldOne = $CustomFields->CustomField[1]->FieldValue;
84. }
85. }
88. $ro1 = new StdClass();
89. $ro1->DemoField = "Scott";
91. $custom_logo = new StdClass();
92. $custom_logo->FieldName = 'logo';
93. $custom_logo->FieldValue = 'A logo';
95. $nickname = new StdClass();
96. $nickname->FieldName = 'nickname';
97. $nickname->FieldValue = 'Scotty';
99. $custom_logo2 = new StdClass();
100. $custom_logo2->FieldName = 'logo';
101. $custom_logo2->FieldValue = 'A logo';
103. $nickname2 = new StdClass();
104. $nickname2->FieldName = 'nickname';
105. $nickname2->FieldValue = 'Scotty';
107. $custom_fields = array($custom_logo, $nickname);
108. $custom_fields2 = array($custom_logo2, $nickname2);
110. $ro2->SampleFields = $custom_fields;
112. $ro2 = new StdClass();
113. $ro2->DemoField = "Hello";
115. $ro2->SampleFields = $custom_fields2;
117. $objs = array($ro1, $ro2);
119. return $objs;
121. }
122. }
123. ?>

<?php //Exception Types define('SERVICE_EXCEPTION', 'ServiceException'); //thow this error when the user does not exist //Soap Exception Fault Codes define('ERROR_CODE_CLIENT', "Client"); define('ERROR_CODE_SERVER', "Server"); /** * * This class handles the Sample Service Soap Requests * */ class SampleServiceClass { /** * Create an exception * * <ns2:sampleexception ns2="http://kimenye.com/soap/"><br /> * <message>Some weird error occurred</message><br /> * </ns2:SampleException><br /> * <br /> * @param object $exception<br /> * @return <br /> */<br /> function createException($exception,$message)<br /> {<br /> $typedException = new StdClass();<br /> $typedException->message = $message;<br /> $detail = null;<br /> $error_code = ERROR_CODE_CLIENT;<br /> <br /> if ($exception == SERVICE_EXCEPTION)<br /> {<br /> $detail->ServiceException = $typedException;<br /> }<br /> <br /> return new SoapFault($error_code,$exception,null,$detail,$exception);<br /> }<br /> <br /> /**<br /> * This is the sample operation.<br /> * <br /> * @param object $SampleOperationRequest<br /> * <br /> * @return <br /> */<br /> function SampleOperation($SampleOperationRequest)<br /> {<br /> $num_of_args = func_num_args();<br /> <br /> //In this example the custom fields are compulsory<br /> if(func_num_args()<1)>createException(SERVICE_EXCEPTION, "SampleOperationRequest -Incorrect parameters passed in.");<br /> }<br /> <br /> $Demo = $SampleOperationRequest->DemoField;<br /> $CustomFields = $SampleOperationRequest->SampleFields;<br /> <br /> $num_custom_fields = count($CustomFields->SampleField);<br /> <br /> /**<br /> * This is to demonstate how to access the custom fields.<br /> * <br /> * If only one custom field is required, access is <br /> * <br /> * $fieldOne = $CustomFields->CustomField->FieldValue<br /> */<br /> if($num_custom_fields == 2)<br /> {<br /> if($CustomFields->SampleField[0]->FieldName == 'a field')<br /> {<br /> $fieldOne = $CustomFields->CustomField[0]->FieldValue;<br /> $fieldTwo = $CustomFields->CustomField[1]->FieldValue;<br /> }<br /> <br /> if($CustomFields->SampleField[0]->FieldName == 'another field')<br /> {<br /> $fieldTwo = $CustomFields->CustomField[0]->FieldValue;<br /> $fieldOne = $CustomFields->CustomField[1]->FieldValue;<br /> }<br /> }<br /><br /> <br /> $ro1 = new StdClass();<br /> $ro1->DemoField = "Scott";<br /> <br /> $custom_logo = new StdClass();<br /> $custom_logo->FieldName = 'logo';<br /> $custom_logo->FieldValue = 'A logo';<br /> <br /> $nickname = new StdClass();<br /> $nickname->FieldName = 'nickname';<br /> $nickname->FieldValue = 'Scotty';<br /> <br /> $custom_logo2 = new StdClass();<br /> $custom_logo2->FieldName = 'logo';<br /> $custom_logo2->FieldValue = 'A logo';<br /> <br /> $nickname2 = new StdClass();<br /> $nickname2->FieldName = 'nickname';<br /> $nickname2->FieldValue = 'Scotty';<br /> <br /> $custom_fields = array($custom_logo, $nickname);<br /> $custom_fields2 = array($custom_logo2, $nickname2);<br /> <br /> $ro2->SampleFields = $custom_fields;<br /> <br /> $ro2 = new StdClass();<br /> $ro2->DemoField = "Hello";<br /> <br /> $ro2->SampleFields = $custom_fields2;<br /> <br /> $objs = array($ro1, $ro2);<br /> <br /> return $objs;<br /> <br /> }<br />}<br />?><br />

This class is a lot more substantial than the previous as it handles the Soap requests.

1. First, is the definition of a couple of exception constants.
2. Second, the method "createException" throws the contract specified exception.
3. Finally, the SampleOperation method reads the input and returns the array output.

That's it!

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.