Introduction

Much of the development around Web services to date has been bottom-up; that is, starting with a Java™ class. IBM's WebSphere Studio family of tools offers almost automatic support for bottom-up development; a developer can identify a Java class and, with a few mouse clicks, can create a Web service, complete with a WSDL description. However, experience in some recent service-oriented customer engagements has shown that top-down development is more common than the bottom-up approach. In the top-down approach, the developer starts with an object model defined by an XML schema rather than by Java classes, and directly creates the WSDL document defining the Web service interface. The increasing frequency of top-down development is fueled by a growing trend to define interoperable industry standards using XML.

Another trend in interoperability is the use of wrapped document-literal Web services definition. The document-literal style of Web service description has been a part of the SOAP binding options in the WSDL specification from the beginning. Per the WSDL specification, document-oriented Web services use messages containing one or more documents as opposed to a set of parameters; literal-oriented Web services produce messages where each part in a message references a concrete schema definition, as opposed to having the encoding information in the message. Thus, document-literal Web services use messages with one or more documents as children of the soap:body element of the message, where the structure of the documents is defined by schema. The WSDL specification allows a bit too much freedom, and the Web Services Interoperability Organization has refined how to describe document-literal Web services to enhance interoperability. Listing 1 (copied from Which style of WSDL should I use? by Russell Butek) shows an example of a Web service with a single method called myMethod that has an input parameter with the data type xElement.

<types>
    <schema>
        <element name="xElement" type="xsd:int"/>
    </schema>
</types>

<message name="myMethodRequest">
    <part name="x" element="xElement"/>
</message>
<message name="empty"/>

<portType name="PT">
    <operation name="myMethod">
        <input message="myMethodRequest"/>
        <output message="empty"/>
    </operation>
</portType>

Wrapped document-literal derives from the Microsoft® .NET Web services environment. While no official specification exists, wrapped document-literal has become the de facto standard for defining interoperable Web services. See Which style of WSDL should I use? for more information about various forms of Web service description and why you might or might not want to use wrapped document-literal. Wrapped document-literal is compliant with the WS-I basic profile for document-literal, that adds additional characteristics: there is a single element in the request message body (the document), and it has the same name as the operation that is the target of the request. A simple way to think about this is that the parameters for the operation are wrapped in a document containing the parameters, and the document (actually an element in the message) is given the name of the operation. Listing 2 shows an another example from Russell Butek's article. The differences are highlighted.

<types>
    <schema>
        <element name="myMethod"/>
            <complexType>
                <sequence>
                    <element name="x" type="xsd:int"/>
                </sequence>
            </complexType>
        </element>
    </schema>
</types>
<message name="myMethodRequest">
    <part name="parameters" element="myMethod"/>
</message>
<message name="empty"/>

<portType name="PT">
    <operation name="myMethod">
        <input message="myMethodRequest"/>
        <output message="empty"/>
    </operation>
</portType>

Suppose you want to create a wrapped document-literal Web service to maximize interoperability, but want to leverage an object model defined by an existing XML schema. WebSphere Studio Application Developer V5.1.2 (hereafter called Application Developer) provides editors for creating and modifying schema files and WSDL files. The WSDL editor tells you when something is wrong, but doesn't offer a lot of explicit assistance in creating a compliant wrapped document-literal WSDL document. While the overall process is not that difficult once you understand it, it can be challenging to get it right the first time without some understanding of the syntax of wrapped document-literal WSDL documents. This article offers some tips and techniques for getting it right the first time.

Back to top

General principles

First, let's examine the general principles for creating a wrapped document-literal WSDL document. The principles are derived from examination of such WSDL documents as those produced automatically by Application Developer using bottom-up development. The wrapped aspect impacts the WSDL types and messages; the document-literal aspect impacts the WSDL portType and binding. The following principles apply:

• An operation in the portType contains an input message part and may contain an output message; this is standard for document-literal WSDL. Our pattern suggests the name of the input message is the name of the operation with Request appended. Likewise, the name of the output message is the name of the operation with Response appended.
• The request message has a single part that identifies an element as the content. The name of the element must be the same as the name of the operation; this is key to the wrapped document-literal definition. The response message has a single part that identifies an element as the content; our pattern suggests the name of the element is the same as the name of the operation with Response appended (the same as the name of the message).
• The request element identified in the request message must contain elements for all the input parameters for the operation. The response element must contain one element for the output parameter returned by the operation.
• The binding must adhere to the standard document-literal rules.

Let's look at a more detailed example. We want to define a Web service named Service, and we want the service to have an operation named op. Listing 3 shows the proper definition of the portType and operation within it. The Web service name derives from the WSDL portType. The names of the messages used by the operation are derived from the name of the operation. To add a new operation, you can simply copy the wsdl:operation element and change the op to the new operation name everywhere within the new wsdl:operation element.

   <wsdl:portType name="Service">
      <wsdl:operation name="op">
         <wsdl:input message="intf:opRequest" />
         <wsdl:output message="intf:opResponse" />
      </wsdl:operation>
   </wsdl:portType>

Next, we'll define the messages for the op operation, as shown in Listing 4. As mandated by the pattern, the request message includes a single part that identifies an element with the same name as the operation. Likewise, the response message has a single part that identifies an element with the name of the operation with Response appended. To add the new messages required for a new operation, you can simply copy both the request and response wsdl:message elements and change the op to the new operation name everywhere within the new wsdl:message elements. Notice that the parts are given the name parameters. This is really not necessary, but we'll see why below.

   <wsdl:message name="opRequest">
      <wsdl:part element="intf:op" name="parameters"/>
   </wsdl:message>
   <wsdl:message name="opResponse">
      <wsdl:part element="intf:opResponse" name="parameters"/>
   </wsdl:message>

Now we'll look at the schema definitions necessary to support the messages, as shown in Listing 5. A key aspect of Listing 5 is the importation of an independent schema file (info.xsd in this example). This allows existing schema to be used; for example, when the schema has been produced by a standards organization. This is also a good practice for keeping the types representing an object model independent of the types needed only for the service definition. Assume we have some types named A, B and C defined in info.xsd. Further, assume the op operation has two input parameters, of type A and B and that op returns C as the response.

Most important in the WSDL types definition is the op element that represents the request document. This element encapsulates or wraps the input parameters for the operation, in this case, the two input parameters of type A and B. This document element is the first place there is really any differentiation from the rote pattern for wrapped document-literal WSDL, as its structure must reflect the actual input signature of the operation. The request document element must include an element for each request parameter. The name attribute of the elements for the parameters is arbitrary, but will become the names of the parameters used in the methods on the Web service skeleton and stub generated by the tooling. The opResponse element represents the response document, and simply encapsulates the returned type. The name of the encapsulated response it not really critical, but the pattern is to append Return to the operation name. To add types for additional messages, you can copy the op request and response elements, change the operation name and then modify, as appropriate, the structure of the new request and response elements.

  
<wsdl:types>
  <schema elementFormDefault="qualified" targetNamespace="..." xmlns="..." 
     xmlns:impl="..." xmlns:intf="..." xmlns:wsdl="..." xmlns:xsd="..." 
     xmlns:info="http://www.test.com/info" >
   <import schemaLocation="info.xsd" 
	  namespace="http://www.test.com/info"></import>
   <element name="op">
     <complexType>
       <sequence>
         <element name="a" type="info:A"/>
         <element name="b" type="info:B"/>
       </sequence>
     </complexType>
   </element>
   <element name="opResponse">
     <complexType>
       <sequence>
         <element name="opReturn" type="info:C"/>
       </sequence>
     </complexType>
   </element>
  </schema>
 </wsdl:types>

Finally, let's look at the binding element of the wrapped document-literal WSDL document, shown in Listing 6. This binding is the standard document-literal binding. It shows that the SOAP binding style is document and the encoding style for each message in an operation is literal. To create additional operations, you can copy the wsdl:operation and simply change the name of each occurrence of op to the new operation name.

  
   <wsdl:binding name="ServiceSoapBinding" type="intf:Service">
      <wsdlsoap:binding style="document" 
          transport="http://schemas.xmlsoap.org/soap/http"/>
      <wsdl:operation name="op">
         <wsdlsoap:operation soapAction=""/>
         <wsdl:input name="opRequest">
            <wsdlsoap:body use="literal"/>
         </wsdl:input>
         <wsdl:output name="opResponse">
            <wsdlsoap:body use="literal"/>
         </wsdl:output>
      </wsdl:operation>
   </wsdl:binding>

The service element in the WSDL document is not impacted by the nature of the binding. Therefore, no special actions are necessary to create the service initially or when new operations are added.

Back to top

Create wrapped document-literal WSDL with Application Developer

Now let's step through the creation of a wrapped document-literal WSDL document using the Application Developer WSDL editor. For the purposes of this article, I assume you're familiar with Application Developer XML and WSDL editors. Refer to the WebSphere InfoCenter if you are not familiar with the editors. We'll start by defining an independent schema using the XML schema editor. Listing 7 shows a schema that defines some information about a person. The schema is contained in a file called info.xsd.

 
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" 
    targetNamespace="http://www.test.com/info" 
    xmlns:info="http://www.test.com/info">
	<complexType name="address">
		<sequence>
			<element name="street" type="string"></element>
			<element name="city" type="string"></element>
			<element name="state" type="string"></element>
		</sequence>
	</complexType>

	<complexType name="telephone">
		<sequence>
			<element name="type" type="string"></element>
			<element name="number" type="string"></element>
		</sequence>
	</complexType>

	<complexType name="name">
		<sequence>
			<element name="first" type="string"></element>
			<element name="last" type="string"></element>
		</sequence>
	</complexType>

	<complexType name="person">
		<sequence>
			<element name="name" type="info:name"></element>
			<element name="phone" type="info:telephone"
                  minOccurs="0" maxOccurs="unbounded"></element>
			<element name="address" type="info:address"
                        minOccurs="0" maxOccurs="1"></element>
		</sequence>
	</complexType>
</schema>

Next, we'll create a new WSDL file using the WSDL editor. Figure 1 shows the WSDL creation dialog, with the name of the WSDL file entered as person. We know we're going to create a SOAP binding, so we need to include the SOAP namespace. We didn't change the default target namespace, but generally you would want to do so. Click Finish to open the WSDL editor with a new empty WSDL file. The WSDL editor offers a Graph view and a Source view. Some things are easier in one and some are easier in the other. We'll use the Graph view to create a service with one operation and then use the Source view to add other operations.

First we'll add a WSDL types element, and then import the info.xsd schema into it. If you view the source at this point, you'll see a wsdl:types element similar to that in Listing 5, but containing only the import element. Due to a bug in Application Developer V5.1.2, you may see some warnings related to the import, but if the schema you are importing is validated by Application Developer, you can safely ignore the warnings.

Next, we'll create a portType (we'll use Person for the name to produce a Web service with that name), add an operation (we'll use add for the operation name), and add input and output children to the operation. Then we'll set the message for the input. You'll see the Specify message dialog, as shown in Figure 2, in which you can indicate the source of the message. The default is to create a new message, and the default name for the message is exactly what we want for the wrapped document-literal pattern; in this case, addRequest. The same behavior occurs when setting the output message.

Now we need to add a part to the messages. Remember that both messages must have a single part, and that the request message must identify an element with the same name as the operation. The editor first asks for the name of the part. The actual name doesn't really matter; to adhere to the pattern we use parameters. The editor then shows the details for the part, similar to Figure 3. The default for Reference Kind is type, but we need to change it to element for WS-I document-literal WSDL files.

Click the ... button to manually identify the element. The dialog shown in Figure 4 displays. Once again, the editor allows us several choices for identifying the element. We want to create a new element. In this case, the editor does not offer the correct element name by default, so we have to manually enter the operation name, which is add in this case, since that is the name of the operation. We follow a similar process for the response message, manually entering the element name addResponse.

Now we need to manually construct the request and response types. It's quite convenient to finish the definition of the add and addResponse types using the outline view of the WSDL file at this point, as shown in Figure 5, as it offers the same sort of features as the XML editor. To the add element, we need to add a Local Complex Type, which automatically adds a content model (sequence). Now we need to add elements into the sequence corresponding to the real input parameters of the add operation. In this case, we'll use parameters that allow the operation to add a telephone to the list of telephones for a person. To do so, we need to add an element named person with a type of info:person and an element named phone that has a type of info:telephone. We want the operation to return a person type, and so follow a similar process to insert an element named addReturn of type info:person into the addResponse element.

We've now completed the worst part and will continue with the more mundane binding and service definitions. When we create a binding, the editor shows the dialog in Figure 6. Enter the name PersonSoapBinding to be consistent with the pattern; then select the portType Person, the protocol as SOAP, and the SOAP binding options as document literal, as shown below.

If you now examine the source of the WSDL document, you'll find the editor created exactly the binding we want. It has the document style in the SOAP binding and a literal encoding for the input and output elements in the operation. Therefore, we don't need to do anything more to the binding.

Now we'll add a service to the WSDL document. The editor asks for a name. To be consistent with the pattern, we'll use the name PersonService. Then we must add a port to the service. The editor shows the dialog in Figure 7. In the dialog, we use Person for the port name. Choose the SOAP binding we created earlier, and choose SOAP as the protocol. You can also enter a specific service endpoint address if you have one. In this case we'll accept the default.

Listing 8 shows the final WSDL document. We've created a WSDL document that adheres to the wrapped document-literal pattern described above using the standard WSDL editor capabilities with only a few additional manual steps.

 
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="person" 
targetNamespace="http://tempuri.org/person/" 
xmlns:tns="http://tempuri.org/person/" 
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <wsdl:types>
	<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
     	elementFormDefault="qualified" 
	targetNamespace="http://tempuri.org/person/" 
	xmlns:info="http://www.test.com/info">
		<xsd:import schemaLocation="info.xsd" 
    		namespace="http://www.test.com/info"></xsd:import>
		    <xsd:element name="add">
			<xsd:complexType>
			  <xsd:sequence>
			    <xsd:element name="person" type="info:person"></xsd:element>
			    <xsd:element name="phone" type="info:telephone"></xsd:element>
			  </xsd:sequence>
			</xsd:complexType>
		    </xsd:element>
		    <xsd:element name="addResponse">
			<xsd:complexType>
			  <xsd:sequence>
			    <xsd:element name="addReturn" type="info:person"></xsd:element>
			  </xsd:sequence>
			</xsd:complexType>
		    </xsd:element>
		</xsd:schema>
	</wsdl:types>
	<wsdl:message name="addRequest">
		<wsdl:part name="parameters" element="tns:add"></wsdl:part>
	</wsdl:message>
	<wsdl:message name="addResponse">
		<wsdl:part name="parameters" element="tns:addResponse"></wsdl:part>
	</wsdl:message>
	<wsdl:portType name="Person">
		<wsdl:operation name="add">
			<wsdl:input message="tns:addRequest"></wsdl:input>
			<wsdl:output message="tns:addResponse"></wsdl:output>
		</wsdl:operation>
	</wsdl:portType>
	<wsdl:binding name="PersonSoapBinding" type="tns:Person">
		<soap:binding style="document" 
        	transport="http://schemas.xmlsoap.org/soap/http" />
		<wsdl:operation name="add">
			<soap:operation soapAction="http://tempuri.org/person/add" />
			<wsdl:input>
				<soap:body use="literal" />
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal" />
			</wsdl:output>
		</wsdl:operation>
	</wsdl:binding>
	<wsdl:service name="PersonService">
		<wsdl:port name="Person" binding="tns:PersonSoapBinding">
			<soap:address location="http://example.com/" />
		</wsdl:port>
	</wsdl:service>
</wsdl:definitions>

Back to top

Test the WSDL

We can now use the WSDL in Listing 8 to generate a service implementation skeleton and a client stub and proxy. A test client uses the proxy to request the service to add a telephone number to a person. Listing 9 shows the request message, and Listing 10 shows the response message. The Application Developer TCP/IP monitor can verify that both the request and response are WS-I compliant. See the WebSphere InfoCenter for details. A visual examination reveals that these messages also are compliant with the wrapped document-literal rules.

 
<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <soapenv:Body>
         <add xmlns="http://tempuri.org/person/">
            <person>
               <name xmlns="">
                  <first>Bill</first>
                  <last>Bopper</last>
               </name>
               <phone xmlns="">
                  <type>home</type>
                  <number>123-456-7890</number>
               </phone>
               <address xmlns="">
                  <street>456 Evergreen</street>
                  <city>Austin</city>
                  <state>TX</state>
               </address>
            </person>
            <phone>
               <type xmlns="">work</type>
               <number xmlns="">123-456-0987</number>
            </phone>
         </add>
      </soapenv:Body>
   </soapenv:Envelope>

 
<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <soapenv:Body>
         <addResponse xmlns="http://tempuri.org/person/">
            <addReturn>
               <name xmlns="">
                  <first>Bill</first>
                  <last>Bopper</last>
               </name>
               <phone xmlns="">
                  <type>home</type>
                  <number>123-456-7890</number>
               </phone>
               <phone xmlns="">
                  <type>work</type>
                  <number>123-456-0987</number>
               </phone>
               <address xmlns="">
                  <street>456 Evergreen</street>
                  <city>Austin</city>
                  <state>TX</state>
               </address>
            </addReturn>
         </addResponse>
      </soapenv:Body>
   </soapenv:Envelope>

Back to top

Add a new operation

Now we'll add a new operation to the Web service. The new operation sets the address for a person and returns the updated person. We'll use the name setAddress for the operation. We could go through the step-by-step process described above, starting with adding an operation to the existing portType and ending with adding an operation to the binding, but a faster way is to do a copy/paste in the Source view of the WSDL editor. Note that using the Application Developer Find/Replace function is a convenient way to replace the operation name when editing.

To add an operation, do the following:

1. Copy the elements used in the original messages, change the names to match the new operation, and modify the structure to match the new input and output parameters.
2. Copy the original messages and change the names to match the new operation.
3. Copy the original operation in the portType and change the names to match the new operation.
4. Copy the original operation in the binding and change the names to match the new operation.

The order of these steps doesn't really matter, but doing them in the order above will eliminate or at least minimize intermediate error notification. To start, we create elements used in the messages. Listing 11 shows the document elements copied and modified to reflect the new operation name and the new input parameters; in this case, person and address instead of person and phone. In this example, the response type (info:person) is the same, but that won't always be the case.

 
<xsd:element name="setAddress">
	<xsd:complexType>
		<xsd:sequence>
			<xsd:element name="person" 
    			type="info:person"></xsd:element>
			<xsd:element name="address" 
    			type="info:address"></xsd:element>
		</xsd:sequence>
	</xsd:complexType>
</xsd:element>
<xsd:element name="setAddressResponse">
	<xsd:complexType>
		<xsd:sequence>
			<xsd:element name="setAddressReturn" 
    			type="info:person"></xsd:element>
		</xsd:sequence>
	</xsd:complexType>
</xsd:element>

Next we'll create the messages needed for the new operation. Listing 12 shows the original messages copied, with add replaced with setAddress.

 
	<wsdl:message name="setAddressRequest">
		<wsdl:part name="parameters" 
    		element="tns:setAddress"></wsdl:part>
	</wsdl:message>
	<wsdl:message name="setAddressResponse"> 
		<wsdl:part name="parameters" 
    		element="tns:setAddressResponse"></wsdl:part>
	</wsdl:message>

Next we'll add the new operation in the portType. Listing 13 shows the original operation copied, with add replaced with setAddress.

 
	<wsdl:operation name="setAddress">
		<wsdl:input message="tns:setAddressRequest"></wsdl:input>
		<wsdl:output 
    		message="tns:setAddressResponse"></wsdl:output>
	</wsdl:operation>

Finally, we'll add the new operation in the binding. Listing 14 shows the original operation copied, with add replaced with setAddress.

 
	<wsdl:operation name="setAddress">
		<soap:operation 
    		soapAction="http://tempuri.org/person/setAddress" />
		<wsdl:input>
			<soap:body use="literal" />
		</wsdl:input>
		<wsdl:output>
			<soap:body use="literal" />
		</wsdl:output>
	</wsdl:operation>

Despite the changes in the type, message, portType and binding definitions, no changes are necessary in the service definition.

Back to top

Conclusion

This article identified a specific pattern that you can use to quickly produce wrapped document-literal WSDL documents from scratch. More specifically, we showed that Application Developer WSDL editor offers a fair amount of automated support for doing so, and we identified the additional manual steps necessary to produce wrapped document-literal WSDL documents. Hopefully, this article will help you, the Web services developer, produce wrapped document-literal services more quickly and efficiently.

Resources

• Which style of WSDL should I use?. An article by Russell Butek that describes various forms of Web service description and how to decide which one you want to use.
  
  
• Web Services Description Language (WSDL) 1.1. The current WSDL schema.
  
  
• Web Services Interoperability Organization.The home page of the WSI Organization.
  
  
• WebSphere InfoCenter. The InfoCenter provides complete information on WebSphere Application Server, Application Developer, and other WebSphere products.
  
  

About the author

Greg Flurry is a Senior Technical Staff Member in IBM's SOA Advanced Technology group. His responsibilities include working with customers on service-oriented solutions and advancing IBM's service-oriented products. If you have comments for the Greg about this article, send them to wsdd@us.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• General principles
• Create wrapped document-literal WSDL with Application Developer
• Test the WSDL
• Add a new operation
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers