Introduction

Many developers intrigued by Web Services have started writing simple services for inter-organizational or personal use. These developers, unfamiliar with the intricacies of Web services technology and development, rely on tools for most of the service code implementation. In these situations, the development and use of the Web Service is all carried out by one developer or one team. The service functions properly but, because of problems with the code generation tools, fails to achieve the primary goal of Web services; interoperability. This article will discuss the advantages of top-down Web services development. It will show you how to use IBM ® WebSphere® Studio V5.1 tools to author WSDL documents, generate interoperable Web services from these documents, and unit test your Web services.

Back to top

What is WSDL and how is it used?

WSDL (sometimes pronounced wiz-dul), or Web Services Description Language, is an XML meta-language for describing everything about a Web service, from the way to connect to the service to what type of information the service will return. A WSDL document gets as detailed as to specify the operations a client can use to interact with a service and the access point of the service. The allowable content of a WSDL document is controlled by the WSDL specification. This description document provides a standard way for clients wanting to consume a given service to obtain all the relevant information about the service. Instead of contacting the organization that has published a Web service to find out how to use it, all of the information can be obtained from the WSDL document associated with the service. The WSDL document can even be used to generate skeleton code for the client that will consume the service.

The Web services Description Working Group, a consortium of people from many different organizations and companies including Sun, Microsoft, Oracle and IBM, manages the WSDL specification. The goal of this group is to maintain and evolve the WSDL open standard to provide a platform independent way to describe a Web service.

The Web Services Interoperability (WS-I) organization, provides best practices for creating interoperable Web services in their basic profile document. The basic profile contains guidelines for authoring WSDL documents that describe interoperable Web services. The best way to ensure that your Web service will be interoperable is to first create a description document that complies with the basic profile and then to generate your service from the compliant WSDL document.

Back to top

Benefit of top-down Web services development

The quickest and easiest way to start developing Web services is the bottom-up approach. Using the bottom-up approach the developer writes the service implementation in any high-level programming language, such as Java^TM and C#, has some tool generate the WSDL document describing the service and deploys the service to a server. This approach is commonly used by companies that have legacy systems and applications within their organization which they want to have communicate with one another. A Web service is built on top of the existing infrastructure and then exposed within the organization. In this situation the quick, bottom-up approach works fine. One company is both creating and consuming the services and the environment can be controlled as all of the clients of the service are known. Since both the services and the clients can be created using the same set of tools and run on the same platform, there does not need to be a lot of concern with respect to interoperability.

Interoperability problems begin to surface when Web services developed using the bottom-up approach are exposed for external use by other companies and consumers running on different platforms, or when one company acquires another and now has to merge the second companies' systems with their own. In these situations all the possible clients to a service are not known when the service is created and this variable allows for interoperability problems. The interoperability problems originate from the tools that generated the WSDL documents. The generated WSDL documents may contain platform specific information that is allowed in the document because of ambiguities in the WSDL specification. Platform specific WSDL documents are by definition not interoperable and defeat the real goal of Web services.

For Web services to achieve their primary goal, live up to the hype and enter the mainstream of computing, they must be interoperable. In order for that to happen, developers must sacrifice the convenience of having tools generate their WSDL documents. Using the top-down approach, a developer starts by authoring a WSDL document. Once the description of the service is written, stub code for the service can be generated by development tools. The developer then fills in the implementation for the Web service and creates connections to any existing architecture. By authoring the WSDL document yourself instead of relying on platform biased tools, you have complete control of the WSDL document and the document can be written in a standard way such that it can be understood by any Web services platform. As the WSDL document is platform independent, stub code for any language can then be generated, provided there is a tool to do so. WSDL2Java is one example of a tool available in Apache Axis that will create Java stub code from a WSDL document.

The top-down approach eliminates the ability for the developer to have tools generate WSDL documents with interoperability problems as the first step in this approach is to author the description document. The top-down approach is favorable because it eliminates a major source of interoperability problems from Web services. Developing Web services in this way promotes the effort to achieve true interoperability between Web service implementations. The following section will illustrate a scenario where a service created using the bottom-up approach has an interoperability problem while the same service created using the top-down approach does not.

Back to top

Use case scenario comparing top-down and bottom-up Web services development

The problem with WSDL documents generated by development tools is that errors originating in the tools get propagated to the consumers of a Web service. A service's WSDL document is its contract with its clients. It defines the terms and uses of a Web service. Errors in the WSDL document mislead the consumers of a Web service as to what the expected behavior is. This use case scenario compares the interoperability of an address book Web service developed using the bottom-up approach to that of the same Web service developed using the top-down approach.

Back to top

Developing the echo message Web service using the bottom-up approach

The echo message Web service consists of four Java classes, EchoMessage.java, Message.java, RequestMessage.java and PhoneNumber.java. They are shown in Figures 1, 2, 3 and 4 respectively:

EchoMessage.java has one method, getClassName. This method takes in a Message instance as input and returns that instance's fully qualified Java class name as output. Message.java itself is an abstract class, it has two concrete implementations. They are RequestMessage.java and ResponseMessage.java. Therefore, the expected result for the getClassName method is either com.example.RequestMessage or com.example.ResponseMessage. Figure 5 shows the corresponding WSDL document describing the echo message Web service generated and deployed using Apache Axis 1.0.

In the XML schema type definition section of the WSDL document, there is an abstract complex type defined for com.example.Message. The definition for the two derived types, com.example.RequestMessage and com.example.ResponseMessage, are not present. The lack of the two derived types is an interoperability problem because abstract types cannot appear in an XML instance document. Abstract types must be substituted by their derived types. Without knowing what the derived types are, Web service clients created using tools such as Microsoft Visual Studio .NET, or even Apache Axis itself will have problems invoking this Web service. The echo message Web service created using the bottom-up approach is not interoperable as it has an incomplete WSDL document.

Back to top

Developing the echo message Web service using the top-down approach

The echo message Web service created using the top-down approach does not suffer from the interoperability problem illustrated in the previous section. By authoring the WSDL document, all the required XML schema type definitions can be specified. Using the WSDL document shown in Figure 6, the same echo message Web service is created. Using this description document, the echo message Web service interoperates well with other Web service clients. Figure 7 shows a sample request and response message.

The next section demonstrates how to use WebSphere Studio 5.1 Tools to author a WSDL document, create a Web service from a WSDL document, and test the Web service.

Back to top

Authoring the WSDL document

Whenever you develop in WebSphere Studio, your first step is to create a project:

• Select File => New => Project.
• Select Web on the left and Dynamic Web Project on the right, and then click Next.
• Enter a project name of AddressBookWeb and click Finish. If you are prompted to switch to a Web Perspective. Click OK.

1. The first step in the top-down approach to Web service creation is to create our WSDL document.
   Select the AddressBookWeb project, right click on it to bring up the context menu, and select New => Other
   Select Web Services on the left and WSDL on the right. Click Next.
   Change the name to AddressBook.wsdl and click Next.
   Change the namespace to http://example.com/AddressBook and the Definition name to AddressBook.
   Ensure the WSDL and XSD prefixes are selected and select the soap Prefix and click Finish.
   
   
2. The WSDL editor is now opened with the newly created WSDL document. Select the Graph tab
   
   
3. We will start by defining the service. Right-click under Services and select Add child => service. Name the service GetInfoByNameService and click OK.
   We have to create a port where the service will be located. Right-click on the GetInfoByNameService and select Add Child => Port. Name the port SOAPPort and click OK.
   Figure 8. Create a service
   
   
4. We need to set the concrete binding information for the service. We will start by just setting the binding and will fill in the details later. Figure 9 shows the Specify Binding wizard.
   Right click on Port and click Set Binding. Change the binding name to GetInfoByNameBinding and click Finish.
   
   
   Figure 9. Create a new binding wizard
   
   
   
5. The binding has to refer to an abstract definition of the operations. The operations are contained in a portType so we need to set a portType for the binding.
   Select the Show Bindings button at the top, right hand corner of the WSDL editor. The bindings will now be visible in the graph view.
   Right click on GetInfoByNameBinding and select Set PortType. Ensure Create a new Port Type is selected and name the port type AddressBookPortType.
   Click Finish.
   
   
6. We can now specify the operation to get address book information given a name. Right click on AddressBookPortType and select Add Child=> Operation.
   Name the operation GetInfoByName and click OK.
   
   
7. We will specify the input for this operation. This is where the request will pass in the name for which the address information is requested.
   Right click on GetInfoByName and select Add Child=>Input.
   
   
8. Now we can specify the information that is required for the input to the operation. Right click on Input and select Set Message. Ensure that Create a new message is selected, set the message name to GetInfoByNameRequest and click Finish.
   Right click on GetInfoByNameRequest and select Add Child => part. Name the part Name and click OK.
   
   
9. Now we will add the output or return information for the operation. Right click the portType operation GetInfoByName and select Add Child => Output.
   
   
10. We need to set what the output will return. Right click on the Output and select Set Message. Ensure that Create a new message is selected, set the message name to GetInfoByNameResponse and click Finish.
    Right click on GetInfoByNameResponse and select Add Child => part. Name the part AddressBookInfo and click OK.
    
    
11. Now we are going to create a one-way operation for adding information to our address book. This is an operation that requires an input but does not output anything. Right click on the AddressBookPortType and select Add Child => operation. Name the operation SaveInfo and click OK.
    
    
12. We need to add an input. Right click on SaveInfo and select Add Child => input.
    
    
13. Right click on the input for SaveInfo and select Set Message. Ensure that Create a new message is selected, set the message name to SaveInfoRequest and click Finish.
    Right click on SaveInfoRequest and select Add Child => part. Name the part AddressBookInfo and click OK.
    Your WSDL document, with the bindings hidden, should now look like figure 10.
    
    
    Figure 10. Current WSDL document with bindings hidden
    
    
    
14. We will now create the custom elements that will be used as input and output parameters from our operations. Right click under Types and select Add Child => Add Schema.
    Figure 11. Adding a schema to the document
    
    
15. Double-click on the arrow next to the Types section schema. This will open the schema editor.
    Figure 12. To edit the schema, select the arrow next to it
    
    
16. First we will create a complex type to hold the address information. Right click on the schema element and select Add Complex Type. Change the name of the element to Address. Right click on Address and select Add Complex Content.
    Right click on the complex content and select Add Element. Change the name of the element to Street.
    Add elements for City, Province, PostalCode and PhoneNumber in that order.
    Figure 13. Adding a global complex type
    
    
17. Next we will create a complex type to hold the name information. Right click on Complex Types and select Add Complex Type. Change the name of the complex type to Name.
    Right click on Name and select Add Complex Content.
    Right click on the complex content and select Add Element. Change the name to FirstName.
    Add a second element and change the name to LastName.
    
    
18. We now need a concrete way to refer to our complex types. We will create global elements in our schema. The first element we need is for our name.
    Right click on Schema and select Add Global Element.
    Change the name of the element to Name.
    Using the drop down menu, change the type of the element to tns:Name.
    Figure 14. Adding a global element
    
    
19. The second global element we need is for our address book information which will contain a name and an address.
    Right click on Global Elements and select Add Global Element.
    Change the name of the new element to AddressBookInfo.
    Right click on AddressBookInfo and select Add Local Complex Type.
    Right click on the complex type and select Add Element.
    Name the element Name and select a type of tns:Name.
    Create a second element for the complex type. Name the element Address and select a type of tns:Address.
20. We now have all the elements we need. Click on the arrow in the top left-hand corner of the editor to return to the WSDL editor.
    
    
21. Now we have to set the parts of our messages to use the elements we just defined in our schema. Figure 15 shows the Specify Element wizard.
    Right click on the tns:Name part for GetInfoByNameRequest. Select Set Element. Select an existing element. Select tns:Name and click Finish.
    Set the elements for the other two parts to tns:AddressBookInfo.
    Figure 15. Specifying an element for a message
    
    
    
22. Now all we have to do is fill in the binding information. The Generate Binding Wizard is shown in figure 16.
    Select the Generate Binding Wizard from the WSDLEditor menu. Ensure Generate content for an existing binding is selected. Select GetInfoByNameBinding. Selecttns:AddressBookPortType. Select Protocol: SOAP and set the SOAP Binding Options to document literal. Ensure that Overwrite existing binding information is selected and click Finish.
    Figure 16. Setting binding information in the binding wizard
    
    
    
    
23. We should check that the WSDL document is valid. Save the WSDL document and then right click on it in the Navigator view and select Validate WSDL File from the context menu. You should see a dialog like figure 17 that states that the WSDL file is valid.
    Figure 17. Message Window upon successful validation
    
    
    
    

Congratulations! Your service definition is complete.

You can view the completed WSDL document here.

Back to top

Building and testing a Web service

1. Bring up the wizard selection dialog. Click on menu File => New => Other.
   
   
2. Launch the Web services creation wizard. Select Web Services from the menu on the left and Web Service from the list on the right. Click Next.
   
   
3. Figure 18 shows the Web services creation wizard. Choose Skeleton Java bean Web Service as the Web service type, deselect the Start Web service in Web project checkbox and select the Overwrite files without warning checkbox. Click Next.
   Figure 18. Web services creation wizard
   
   
4. Accept the default settings in the service deployment configuration page. The address book Web service will be deployed to the IBM WebSphere V5.0.2 Web services engine on a WebSphere V5.0.2 unit test environment server. Click Next.
   
   
5. Figure 19 shows the Web service selection page. Click on the Browse button and navigate to the location of AddressBook.wsdl. Click Next.
   Figure 19. Web service selection page
   
   
6. Accept the default settings in the Web service skeleton Java bean configuration page. Click Finish. This will generate Java skeleton code based on AddressBook.wsdl.
   
   
7. Before invoking the address book Web service, we must fill in the implement for the Java skeleton. Open /AddressBookWeb/JavaSource/com/example/GetInfoByNameBindingImpl.java in an editor. Modify this Java skeleton as shown in Figure 20. Save and close the editor.
   Figure 20. GetInfoByNameBindingImpl.java
   
   
8. Open the server view if necessary. Click on menu Window => Show View => Other... In the show view dialog, expand the Server tab, select the Servers node and click OK.
   
   
9. In the Servers view, right-click on the server that the address book Web service is deployed to and select menu item Start.
   
   
10. We'll now use the Web Services Explorer to test the address book Web service. To launch the Web Services Explorer, right click on /AddressBookWeb/WebContent/wsdl/com/example/AddressBook.wsdl and select menu item Web Services => Test with Web Services Explorer.
    Figure 21. Web Services Explorer
    
    
11. To save an address, click on the SaveInfo operation. Enter the values shown in figure 22 and click Go.
    Figure 22. SaveInfo operation
    
    
12. To retrieve the address saved in the previous step, click on the GetInfoByName node in the Web Services Explorer's navigator pane. Enter John as the first name and Doe as the last name. Click Go to invoke the operation. Figure 23 shows the status pane containing the result of invoking the operation.
    Figure 23. Status pane containing result of invoking GetInfoByName operation
    
    

Back to top

Conclusion

Interoperability is the key that Web services require to open the door to mainstream computing. The interoperability of a Web service begins with its WSDL document, which describes everything about a service. The bottom-up approach to Web service development is fast and easy but may produce services with interoperability problems. The best way to maintain interoperability is by following the top-down approach to Web service development and starting your development by authoring your description document. WebSphere Studio 5.1 provides development tools to author WSDL documents, generate interoperable services from the documents and unit test your newly created services.

Resources

• Apache Axis
  
  
• Web Services Description Language (WSDL)
  
  
• Web Services Description Working Group
  
  
• Web Services Interoperability (WS-I) Organization
  
  
• Web Service Validation Tools (WSVT) eclipse open source project
  
  
• WebSphere Studio
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• What is WSDL and how is it used?
• Benefit of top-down Web services development
• Use case scenario comparing top-down and bottom-up Web services development
• Developing the echo message Web service using the bottom-up approach
• Developing the echo message Web service using the top-down approach
• Authoring the WSDL document
• Building and testing a Web service
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers