Introduction

This paper discusses the test facilities related to Web services included in the IBM® Rational® Application Developer V6.0 Web services wizard. For the most part these concepts can be applied to development using WebSphere® Studio Application Developer. In order to get a clear picture of how you can use these test facilities effectively I have included explanations about the Web services technology and standards as well as how these are incorporated into the Web services wizard.

The first section of the paper deals with Web services development using the Web services wizard. The wizard follows a number of industry standards with regards to the deployment of Web services. There is a general discussion on the server and run-time extensions as well as the servers and run-times shipped with Rational Application Developer V6.0.

The Web services wizard has two key roles: 1) Web services deployment, and 2) client generation. Depending upon the server and the chosen run-time, the artifacts that the Web services wizard generates may vary. The end result is a deployed Web service on a server. There are a number of key scenarios within the Web services wizard. One of these is the ability to create a Web service from a Java bean. This is called the Bottom Up scenario. The other is the ability to create a Web service from a Web Service Description Language (WSDL -- see Resources) file. This is known as the Top Down or Skeleton scenario. If a vendor deploys a Web service and you would like to create a client to use it, the Web service client wizard does this by starting with the WSDL file.

The Web services wizard has a number of test facilities available at different points. After the developer has deployed the Web service there is a test page that has test facilities that test the service directly using the WSDL file. The Web services wizard provides a fully integrated WSDL test client known as the Web service Explorer.

As discussed earlier, the wizard can also produce a client for a deployed Web service. The client contains a number of files that help send an XML message over the developer's chosen run-time to the deployed Web service. To make it easy for client developers, the operations on the Web service are mapped to Java methods on the Service Endpoint Interface (SEI). The Java Proxy is a file that invokes methods in the SEI. The Web services wizard contains a number of clients that build on top of this Java Proxy. The Generated Sample Test Client (GSTC) and the Universal Test Client (UTC) are two test clients that use the generated Java Proxy. The GSTC is designed to give the user an example of a Web-based test client. The UTC is a Web-based dynamic engine that handles many types including collections, maps, and arrays. The GSTC may not handle more complex Java methods involving arrays, collections, and exceptions that the developer wants. It can be modified to handle types in the developer's Web service that the wixard hasn't originally generated.

This paper gives a tutorial using a Mortgage calculator example on how to modify a generated GSTC to better suit the Web service.

Back to top

Web services development overview

As Figure 1 shows, Web services are generally set up in a typical client/server architecture. The two parts of the run-time are known as the Requestor and the Provider.

The Web services wizard generates files for the Requestor and the Provider. The Web services wizard supports a number of servers and run-times. Figure 2 shows a list of run-times being shipped with Rational Application Developer.

You must decide on the type of server on which to run your service. This is the engine that would host the run-time. IBM has been very successful in this area with its own production server, the WebSphere Application Server. Rational Application Developer is now shipped with a fully integrated copy of WebSphere Application Server V6.0. Also shipped are the two previous versions: WebSphere Application Server versions 5.0 and 5.1. Rational Application Developer Web services have been tested extensively using the Apache Tomcat server. This is an open source server that doesn’t have all the bells and whistles afforded in a WebSphere Application Server production server. It is recommended you use Websphere becasue of its powerful capabilities.

The wizard generates three sets of artifacts (see Figure 3): 1) The Web service Requestor-side artifacts including the Proxy Bean, 2) the WSDL file, and 3) the Web service Provider-side files. A Web service can be based on a number of different types including a Java bean, Enterprise Java Bean (EJB) component, DADX document, and so on.

You can start at different points in the wizard and create a Web service using different file types. One start point is with a Java Bean. The Web services wizard would then generate the Requestor-side files including the proxy bean, the WSDL file, and Provider-side files. This is known as the Bottom Up scenario and is shown in Figure 4.

You can also start with a WSDL file and generate the Requestor-side artifacts and the Provider artifacts including a skeleton bean with the WSDL operations. The implementation is left to you to fill in. This is known as the Skeleton or Top Down Scenario. You can see this in Figure 5.

Developing Web services in the Rational Application Developer environment, as you will see, can be a trivial thing. Although you have a lot of choices, options, and integration points, a Web service can be developed by clicking finish on the first page of the Web services wizard. In this case, the wizard assumes a lot of defaults and uses preferences which you have already established.

Back to top

Web Service Deployment

When deploying a Web service, your choice of run-time and server affects both the chosen J2EE specification level, as well as the files generated. WebSphere Application Server V6.0 supports the J2EE 1.4 specification (see Resources). The concept of Web projects being deployed to an EAR file exists for WebSphere Application Server. Web services information for J2EE is stored in a file called webservices.xml. To see how Web services are made more interoperable using the JSR-109 specification, I recommend the article "Understanding the foundation of JSR-109" (see Resources).

In Figure 6 you see a Web project named webproject contained in an EAR named webprojectEAR. There are five files in the package mortgage.calc:

Figure 7 shows the same folder after the Web services wizard Bottom Up scenario has been run on the MortgageCalculator.java file. In this case I chose WebSphere Application Server V6.0 a WebSphere run-time. As you can see, several file types have been generated including deserializer, serializer, and helper files. These files are used to convert the incoming XML message to Java language and outgoing Java language to XML. There is also a SEI file which holds all the operations in the Web service. The client proxy is generated using this file. A WSDL file is generated into the Web Content directory. This contains information about the Web service that has just been deployed to the server. The WSDL Test Clients use the WSDL file to test the service directly. Rational Application Developer provides the Web service Explorer which you can use to test the service.

Looking at Figure 8 you see what happens during the Web services deployment in the Web services wizard. A number of files are generated to facilitate the serialization and deserialization of the messages to and from the service. Information is also added to the webservices.xml, web.xml, and x_mapping.xml. This information describes the deployment of the service. This follows the J2EE 1.4 standard. At this point all the information about the Web service has been deployed to the EAR. The EAR has then been added to WebSphere Application Server.

Back to top

Client generation

To generate a client, select the checkbox next to the corresponding label that says generate proxy on the first page of the Web services wizard. Another way to generate a client is to start with a WSDL from the service. This is known as the Client scenario (see Figure 9). In this case it is assumed the service has already been deployed. The Web services wizard creates a Web project called webprojectClient and a new EAR file that contains this project. In Figure 10 you see all the files that are generated for the client. Again there are serializer, deserializer, and helper classes. The key file that the test facilities focus on is the proxy file, in this case AddressBookProxy.

The SEI contains methods equivalent to those in the WSDL file, and the proxy class implements the SEI. In order for you to test your Web service, all you need to do is call the methods in the proxy. Of course you have to enter the specific input parameters for each method and handle any results. You can design your own client or rely on one of the two test clients that Rational Application Developer provides. The two test clients are the Generated Sample Test Client (GSTC) and the Universal Test Client (UTC).

Back to top

Web services testing

Included in the Rational Application Developer Web services wizard are extensive Web services capabilities. During the creation of Web services using the Web services wizard there are two stages during which you can test:

• After the service has been initially created and deployed on the Service Test Page
• If the user has selected to generate a client after the client has been created on the Client Test Page.

If you look at Figure 11 you can see the two different ways of testing a Web service. These correspond to the different test pages in the Web services wizard. For the first test method, you can use the information directly from the WSDL. The client is expected to get the location of the service and form the correct XML message to send to the Web service. The Web service Explorer uses this methodology to test Web services. This option occurs immediately after you create the Web service in the wizard. You generally use this method to ensure that the Web service is working as designed before carrying on with client generation.

The other way of testing a Web service is to generate the Requestor files including the Java proxy and use a Java client to call the methods in the Java proxy. Remember the Requestor files that the wizard generates are based on the WSDL. As with the Service Test Page, the Client Test Page has extension points which give you the ability to include your test client in this area of the wizard. This example presently provides two Java test applications: the GSTC the UTC. Both test clients handle complex beans as input parameters. A complex bean has properties of types other than primitives or strings.

The GSTC is made up of four generated Java Server Page (JSP) components based on the methods contained in the proxy. The GTSC is to be used as a guide to the user on how a Web-based client might be designed. It lets you enter input parameter information and invoke the operation. Because it is easy to use, it is often a very popular choice when simple tests are needed.

The UTC is also a Web-based test solution. It loads the Java operations in the proxy dynamically and gives you the ability to invoke the operations. The UTC is able to handle most complex types and makes it the best choice for more complicated tests.

Back to top

The Java test client

There are a number of files automatically created for you during Requestor generation in the Web services wizard. These files are generated to make it easy for you to access a Web service. Now you can build your client application directly on a Java file. The top level file is called a proxy file. This file is generated into the client Web project in the Rational Application Developer environment. The proxy is named after the service and is placed in a client-side folder with a package name based on the WSDL namespace.

Rational Java test clients

After client generation you might want to build your own extensive Java client based on the proxy provided that is specific to your needs. This would be time consuming and you would probably want to test your generated client to ensure it is working as designed. Rational provides the GSTC and the UTC for this purpose. Both have advantages and disadvantages that will be discussed at length in this document. Depending on what you are doing you may choose one over the other.

So how does a Java test client work? The answer is quite simple. The main goal of a Java test client is to invoke a method on the Java proxy at run-time. Looking at Figure 12 you can see that two methods were generated in the proxy. It is no coincidence that you can find these methods in the SEI files and in the WSDL file under the Port element. These two methods existed in the original Java class in the Bottom Up scenario.

If you were building your own client you might have a user interface, or you might decide to have an automated system that calls these methods directly. For testing purposes, assume you want to type in the information and invoke the methods manually.

Using Java test clients effectively

The following are rules of thumb that can help you create a Web service that is Java test client-friendly. For the most part the top-level service bean can have methods that are not in bean specification format (see Resources). It is recommended that all type structures within follow the bean specification.

The Generated Sample Test Client (GSTC)

The GSTC is a Web-based sample of how to create a client using JSP pages to invoke a service. It is actually used quite a bit just to test a Web service because of its simple interface, but its intention is to give you a starting point for a Web-based client using the client-side files.

The GSTC consists of four JSP pages (see Resources). JSP technology allows the mixing of HTML and Java code. They need to be hosted on a Web server. Figure 15 shows an overview of how the GSTC JSP pages works. The server reads through the JSP pages and produces an HTML page that the user sees in the browser. The user then selects a method and enters data relevant to the service and submits this to the Web server. The server forwards this data on to the JSP pages which process it and make a call to the Java Proxy. The Java Proxy sends this message on to the actual Web service across a webservice run-time.

Back to top

Customizing the GSTC

The sample client found in the Web services wizard handles a lot of types that are often used in a Web service, but there are types for which it does not generate code, particularly when dealing with certain types as inputs. Some common examples are arrays, collections, and maps. You might also want to specify certain exceptions that are not handled.

Mortgage calculator example

The mortgage calculator is an example anyone who has ever considered buying a home is probably familiar with. The user inputs all his financial information and is given an amount he can afford. The mortgage calculator in this example takes in monthly income, bills, rent, percentage rate, and mortgage term. As you can see in Figure 16, arrays represent the income and bills. This is to accommodate the fact that there might be more than one income and there is definitely more then one bill.

If you look at the code in Figure 16 you can see that this bean does fit the bean specification. Each of the properties are in lowercase and they all have getters and setters according to the bean specification. For the most part this class follows the Java test client best practices. However, the arrays cause problems with the GSTC. You can customize the GSTC to accommodate this, as I will show you later.

Below in Figure 17 is the class that does all the work and is the actual Web service class. The MortgageCalculator has two methods called calculateMortage and MortageInfo, which you saw in Figure 15. calculateMortgage has one input parameter. Calculate has two input parameters with type double. Only the parameters on the methods need to follow the bean specification. So the calculateMortgage method takes information gathered from the MortgageInfo class and calculates how much every month the user can afford. It also throws a TermException if the mortgage term is greater than twenty-five years.

Because I designed this Web service in a Java class, I show you how to create this Web service using the Bottom Up scenario. This means you create the Web service server-side artifacts, the WSDL file, and the Web service client-side artifacts. The proxy class is part of the client and the GSTC will call this class to access the service.

Now create the MortgageCalculator Web service and you will get a detailed look at the Web services wizard in action. First, create the Mortgage classes in a Web project by selecting File > New > Other > Web > Dynamic web project.

In the Java Source directory you can create new Java classes by selecting File > New > Other > Java > Class, or you can import the classes if you already have them by selecting File > Import.

Once you have completed this step, the classes should be in your Web project in the Java Source folder, as shown in Figure 18. The next step is to select the MortgageCalculator Java file, as this is the Service class. Select File > New > Other > Web services.

Looking at Figure 19 you see seven Web services options available to you. Unit Test UDDI has to do with discovering new Web services. Web Service Client would allow you to create the client-side artifacts, assuming the Web service has been deployed. The one used in this example, Web Service, creates and deploys the service as well as gives you the option to create the client and deploy the GSTC.

Click Next and you will see the Web services page shown in Figure 20. Make sure Generate a proxy and Test the Web service are selected. Also select Overwrite files without warning. If you know that the GSTC is your default Web services test client in the Web services preferences, click Finish now. If not, click Next until you get to the client test page and select the Web Service JSP page from the test facility drop down, as shown in Figure 21.

After you click Finish, you should get a warning that notifies you that the Sample doesn’t support the array type. You see this error in Figure 22. Specifically, the GSTC doesn’t support array types on input.

This message tells you that the array properties will be excluded from the GSTC generation. If you look at the code in MortgageInfo in Figure 16 you see two properties: income and bills. These are both arrays of doubles which cause a problem with the GSTC. This is not good news, as the income and bills are the most essential part of the calculation. Luckily there is a work-around; you can customize the generated JSP pages to suit your needs. Click OK on this warning and the MortgageCalculator GSTC will be generated.

Looking at Figure 23 you get your first glimpse of the MortgageCalculator in action. The GSTC has three panes; the methods are on the left, the inputs on the right and the result below. Four JSP pages that the Web services wizard generates control these areas. These files are generated and placed into the WebContent folder located in the client project that the Web services wizard created. The files are placed in a folder named sampleMortgageCalculatorProxy.

MortgageCalculatorProxy is a client-side Java file that the Web services wizard generated, and which the GSTC used to do its own generation. You can see the new client project in Figure 24 and the four new JSP files generated in the WebContent/sampleMortgageCalculatorProxy directory. The calculateMortgage method in the GSTC is not working yet because the GSTC could not handle the arrays in the MortgageInfo. The second method calculate takes two doubles, adds them, and returns the resultant double. Figure 25 below shows the input pane after the calculate method has been selected. I then entered two values, 10.2 and 15.5, in the input form and clicked Invoke. The result pane shows the return value from the service after the invoke at 15.7.

Below in Figure 26 you can see what happens when you select the calculateMortgage method. Remember the MortgageInfo bean in Figure 16 had 5 properties. However the Input pane only shows three inputs. The GSTC has excluded these inputs because it is unable to handle arrays. The two properties that were excluded were bills and income. You can change the generated JSP pages to take inputs for these two array properties.

Figure 27 is the Input.jsp. Open your own Input.jsp with the JSP page source editor and you should see something similar. Line number 97 shows this method is case number 25. This is part of a large switch statement that enumerates each method; this will become important later. As you can see there is a main title called mortgageInfo on line 104 and three other titles which take text inputs. This is standard HTML which is pretty easy to work with. You will add in the other two inputs, income and bills. You need to give the user the ability to add more than one of each, so you add a bunch of text boxes for each one.

You can add in as many bills and incomes as you like. I’m going to add two incomes and three bills. You can see the addition below in Figure 28; the new code starts on line 106.

I have also added in an extra label for the original three inputs to improve the appearance of the GSTC, as shown in Figure 29 on line 137.

Now that all the information has been added to the input.jsp you want to see the new input pane. You need to restart the project in the server. In order to do this you need to ensure the server view is activated. To activate the server view, select Window > Show view > Other > Server > Servers. Now select the application server, right click, and select Restart project > webprojectClientEAR.

In order to see the changes in the server, refresh the browser and select the calculateMortgage method in the methods pane. The inputs pane will look like that in Figure 31.

The final step is to change the Result.jsp file adding in new code to accommodate the new inputs we added. Below in Figure 32 is a screen shot of the Result.jsp before any code has been added.

In Figure 27 you saw that Input.jsp is divided by a switch statement, and the case for the calculateMortgage method was case 25. In order to make sure your code is in the right place in the result.jsp, it must be added to the same case as the input.jsp -- in this example case 25. As you can see in Figure 32 in the Result.jsp there are familiar terms you have seen in the Input.jsp. In the result.jsp, you use the getParameter method call to retreive the values for mortgage term, percentage, and rent that the user enters. This is seen on lines 79,81,83. On line 86 the useBean command creates a new instance of MortgageInfo. The MortgageInfo bean is set with the info collected from the Inputs page through the setters on lines 88,89 and 90. Next the method is invoked on line 91 using the MortgageInfo bean. A double is returned from the methods and is displayed in the browser.

To connect your new input parameters you need to add code to get them from the inputs page. Then you add code to create an array and add the values to it. Lastly, you set the new arrays on the MortageInfo bean represented by the id called mortgage1calc1MortgageInfo_1id.

In Figure 33 you can see the new code that has been entered into the result.jsp. New arrays, bills, and income are placed in Result.jsp between lines 79 and 90. These new arrays are then set on the MortgageInfo bean on lines 101 and 102. Now the MortgageCalculator is ready to be tested. So you will need to restart your server and refresh your browser.

Figure 34 shows the completed input form for the Mortgage Calculator. Click Invoke and check the results pane for results. Remember that you can modify all of these titles, so if you believe there should be more explanation for the user then, by all means, put it in. You expect an int to be displayed in the results pane, which gives you the monthly payment they can get. A more practical example might have returned a bean which supplied this monthly payment and the amount of the total loan. Looking at Figure 35 you can see that the total amount this family can afford every month is 1400 US dollars. These are great rates; the above calculation would be altered depending on the institution.

Exception handling

To make the Mortgage Calculator user-friendly, I put an exception in the original MortgageCalculator class. TermException is thrown when the term of the loan is over 25 years. There is one restriction placed on the process. There could be a lot more, for instance no negative numbers or no percentages over 15. But the designer figures this out. Another exception that occurs is a JavaFormatException. This happens when an input is not filled in. The messages provided to the user are simply the names of the exceptions; you can catch the exceptions and give a more understandable message.

In Figure 36 you see that the mortgage term is 27, so this should trigger the exception I placed in the MortgageCalculator.

Figure 37 is a picture of the TermException thrown because the mortgage term is greater than 25. Figure 38 shows the code near the bottom of the result.jsp file before we alter it. This is where the exception is caught and its primary message is displayed.

Figure 39 is a picture of the TermException code placed in the result.jsp. The code starts at 113 and ends on 118. It catches the TermException and then diplays the message "Enter a value less than 25 for the mortgage value."

In order to see the results of the new code in the result.jsp, you need to restart the project on the server. Then you need to enter a value greater than 25 in the mortgageTerm textbox on the input.jsp page.

Back to top

Conclusion

Rational Application Developer V6.0 comes well-equipped to handle all J2EE-compliant Web services deployment and client generation. It provides servers and run-times to help you quickly create and deploy a Web service.

When using Rational Application Developer, you will soon find that developing a Web service has an excellent balance of simplicity and choice. You can create a Web service by starting from different points. These include starting from a WSDL file (Top Down or Client scenario) or from a Java file (Bottom Up scenario).

Once you deploy a Web service you can immediately test it using the Web service Explorer. This is a test facility that reads information from the WSDL and connects to the service directly.

If a Web service has been deployed already and you are interested in creating a client for the service, you can do so starting from a WSDL file in the Rational Application Developer Web services wizard. To make client development easy, the wizard generates a number of client-side files which help process the client message into the appropriate XML message. The top-level file that holds the operation calls for the Web service is a Java file called the Java Proxy. Clients are expected to use the methods in the Proxy to invoke methods on the Web service. The two Java test clients available are the Generated Sample Test Client (GSTC) and the Universal Test Client (UTC). The GSTC is a static Web-based test client that the Web services wizard generates to give you an example of a working test client specific to a particular Web service. The UTC is a dynamic engine designed to cover many types.

You can customize the GSTC to fit the Web services you are developing. This paper used a Mortgage Calculator example to explain the versatility available in the IBM Rational Application Developer V6.0 Web services wizard. You learned that, although the generator does not handle every possible type including arrays, you can modify the GSTC to account for this. You can also modify the GSTC to improve usability by displaying better messages from exceptions, which you learned when modifying the TermException.

Resources

• Learn more about JSR-109 in the article "Understanding the foundation of JSR-109" (developerWorks, August 2003).
  
  
• Access the Bean Specification.
  
  
• Find the WSDL Specification on w3.org.
  
  
• Learn more about JSP Technology.
  
  
• Get the J2EE 1.4 Specification.
  
  
• Browse for books on these and other technical topics.
  
  
• Want more? The developerWorks SOA and Web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  
• The IBM developerWorks team hosts hundreds of technical briefings around the world which you can attend at no charge.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Web services development overview
• Web Service Deployment
• Client generation
• Web services testing
• The Java test client
• Customizing the GSTC
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Application Developer for WebSphere Software
• Buy: Rational Application Developer for WebSphere Software

Dig deeper into SOA and Web services on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers