Introduction

Part 1 of this series focused on creating the web service provider from the command line. In this article, the second in our series, you'll learn how to develop a web service client without an Integrated Development Environment (IDE) like WebSphere® Studio Application Developer (WSAD) or Rational® Application Developer (RAD). You'll see just how simple it is to create a web service client. In the process you will learn how to use the Java™ compiler and WSDL2Java. TCPMonitor is demonstrated to show how to trace HTTP messages.

This article has the following prerequisites:

1. A Windows-based operating system
2. WebSphere Application Server 5.x or 6.x. Download the trial version to follow the steps in this article.

Back to top

Preparation

If you're not continuing from Part 1, install the WAR file linked in the Downloads section, using the WebSphere Application Server Administration Console. If you're continuing from Part 1 and have already installed the WAR file, skip this step. To install the WAR file, follow these steps:

Go to Applications -> Enterprise Applications -> Install. For the Local Path specify the location of HelloWorld.war, and for the Context Root specify HelloWorldWAR.

When the WSDL file was first created, the location parameter was set to "http://localhost:9080/HelloWorldWAR/services/HelloWorld." Therefore, the Context Root must be "HelloWorldWAR" so that the WSDL file can be used to generate clients, without manual alteration.

Click Next through all the defaults. Finish installing the WAR. Remember to save all the changes. Now the most important step is to start the WAR file - this is a step easily forgotten!

Back to top

Creating the client

Assuming that the web service provider starts up correctly, we can now create a client. There are three basic steps:

1. Create the client stubs from the WSDL
2. Develop a Java class that uses the stubs
3. Compile the Java files and run the client

Back to top

Create the client stubs from the WSDL

The beauty of the Web Services programming model is that it is very easy to invoke remote methods. The WSDL is used to create a stub, which can then be used to represent the remote object on the client side:

A) Create a directory (c:\temp\Client). Copy HelloWorld.wsdl created from Part 1, or download from the Downloads section.

B) Open a command-line prompt, and navigate to c:\temp\Client. Type in the following commands:

			
SET WAS_HOME=C:\Program Files\WebSphere\AppServer5.1

call "%WAS_HOME%\bin\setupcmdline.bat"	

The first line sets the "WAS_HOME" environment variable to where you have WebSphere Application Server installed. Ensure that this points to the correct directory! The second line calls a script that will set up additional environment variables, like JAVA_HOME.

C) Use the WSDL2Java command to create the client stubs:

call "%WAS_HOME%\bin\WSDL2Java" -role client -verbose -output . HelloWorld.wsdl

Here is an explanation of the options that we use:

• Role - this can be used to specify either server or client. We choose the latter because we are building a client.
• Verbose - this prints out messages to the console for every step taken
• Output - we place a period to specify the current directory
• WSDL file - this is always the last argument

After running this command, the following will appear in the console:

WSWS3185I: Info: Parsing XML file:  HelloWorld.wsdl
WSWS3282I: Info: Generating .\mypackage\HelloWorld.java.
WSWS3282I: Info: Generating .\mypackage\HelloWorldSoapBindingStub.java.
WSWS3282I: Info: Generating .\mypackage\HelloWorldService.java.
WSWS3282I: Info: Generating .\mypackage\HelloWorldServiceLocator.java.
WSWS3282I: Info: Generating .\mypackage\HelloWorldServiceInformation.java.

You will notice that a directory named mypackage will be created with the above files. Here are more details on the files:

• HelloWorld.java - this is the Service Endpoint Interface
• HelloWorldSoapBindingStub.java - this is an implementation of the Service Endpoint Interface
• HelloWorldService.java - this is the Service Interface
• HelloWorldServiceLocator.java - this is the implementation of the Service Interface

The concept to remember is:

• Service Endpoint Interface: HelloWorldSoapBindingStub implements HelloWorld
• Service Interface: HelloWorldServiceLocator implements HelloWorldService

You will learn more about these in the next section, when you build the client.

Back to top

Develop a Java class that uses the stubs

The next step is to create a class file that can utilize the generated stubs. In the "mypackage" directory, create a file called HelloWorldClient.java. Paste the following code:

package mypackage;

public class HelloWorldClient {
    public static void main(String[] args) throws Exception
    	{
	HelloWorldServiceLocator hwlocator = new HelloWorldServiceLocator();
	HelloWorld hw = hwlocator.getHelloWorld();
	String str = hw.sayHello();
	System.out.println(str);
	}
}

Notice that only three lines are used to invoke the web service. Here is an explanation:

A) The HelloWorldServiceLocator is a Service object. In short, the Service object is used to obtain the generated stub. The Service object is created by this line:

HelloWorldServiceLocator hwlocator = new HelloWorldServiceLocator();

The name of the service object will always be *service name*Locator where *service name* is the name of the service in the WSDL file.

NOTE: In a J2EE context (inside a servlet or EJB), the Service object should be retrieved through JNDI. Since we are using a J2SE client, this is the only way to retrieve the Service object.

B) Next, the client stub needs to be created. The stub represents the remote object. The stub is obtained by the following:

HelloWorld hw = hwlocator.getHelloWorld();

Notice that the method to get the port will always be called get*port name* where *port name* is the name of the port in the WSDL file.

C) Finally, the remote method can be called on the stub. Here, we use the sayHello method on the stub, and put the return value into a String:

String str = hw.sayHello();

Back to top

Compile and run the client

The next step is to actually compile the client. Issue the following command to compile:

"%JAVA_HOME%\bin\javac" -extdirs "%WAS_CLASSPATH%;%WAS_EXT_DIRS%;." mypackage\*.java

Class files should appear in the mypackage directory. Finally, run the Java application:

"%JAVA_HOME%\bin\java" 
	-Djava.ext.dirs="%WAS_CLASSPATH%;%WAS_EXT_DIRS%;." mypackage.HelloWorldClient

The message "Hello World!" should appear on your console. Congratulations! You invoked the Web Service through your client.

Back to top

Setting up a TCPMonitor Trace

An extra step that we can take is to examine the data that is going over the wire. WebSphere Application Server comes with a tool called TCPMonitor that allows users to trace HTTP messages. In order to use TCPMonitor, we place it between the client and the server. Currently, the client is interacting directly with the server. We will point the client to interact with TCPMonitor, and TCPMonitor will forward the traffic to the server.

A) In order to take advantage of TCPMonitor, we first have to modify the client. Edit HelloWorldClient.java so that it looks like the following:

package mypackage;
import javax.xml.rpc.Stub;
public class HelloWorldClient {
    public static void main(String[] args) throws Exception
    	{
	HelloWorldServiceLocator hwlocator = new HelloWorldServiceLocator();
	HelloWorld hw = hwlocator.getHelloWorld();
	((Stub) hw)._setProperty("javax.xml.rpc.service.endpoint.address",
		"http://localhost:1234/HelloWorldWAR/services/HelloWorld");
	System.out.println(hw.sayHello());
	}
}
		

The line ((Stub) hw)._setProperty("javax.xml.rpc.service.endpoint.address", "http://localhost:1234/HelloWorldWAR/services/HelloWorld"); is added to change the endpoint to which the client will send traffic. The default endpoint address is specified in the HelloWorldServiceLocator.java file, with the following line: private final java.lang.String helloWorld_address = "http://localhost:9080/HelloWorldWAR/services/HelloWorld";
Note that we changed the port from 9080 to 1234. Additionally, we must import the java.xml.rpc.Stub class in order to cast the HelloWorld instance into a Stub object in order to cast the HelloWorld instance into a Stub object.

B) When running TCPMonitor, it is important to use the Java version that came with WebSphere Application Server. Otherwise, you may receive a NullPointerException. Issue the following command:

"%JAVA_HOME%" -Djava.ext.dirs="%WAS_EXT_DIRS%" com.ibm.ws.webservices.engine.utils.tcpmon	

C) Specify the following values:

Listen Port - 1234
Target Hostname - localhost
Target Port # - 9080
		

The window should look like this:

Next, click the Add button. This will configure TCPMonitor to accept traffic on port 1234 and redirect it to 9080. The listener runs automatically after you click the add button. A tab at the top of the TCPMonitor will appear representing the listener.

D) Recompile and invoke the web service client through the following commands:

"%JAVA_HOME%\bin\javac" 
	-extdirs "%WAS_CLASSPATH%;%WAS_EXT_DIRS%;." mypackage\*.java
"%JAVA_HOME%\bin\java" 
	-Djava.ext.dirs="%WAS_CLASSPATH%;%WAS_EXT_DIRS%;." mypackage.HelloWorldClient	

E) Examine the traffic in the TCPMonitor window. The SOAP envelope appears all on one line. The web services engine avoids sending new-line characters in order to save space.

F) In order to make the XML easier to read, you can create a new file called tcptrace.xml and paste the XML into it. Mozilla Firefox or Microsoft Internet Explorer can then be used to open the XML file and view it formatted.

Back to top

Conclusion

The web service programming model makes it very easy to generate stubs which can then be used by the client application to invoke the web service. There are currently many web services out there for which you can use the technique described here to build a client. Major sites like Google, Amazon, Ebay, and Fedex currently have web services that you can use. Enjoy!

Back to top

Appendix A: Building the client automatically

The above steps can be automated by using the WebServiceTutorial.bat in the Downloads section. First, modify WebServiceTutorial.bat so that the WAS_HOME directory points to a current WAS installation directory. Next, run the batch file. The output should look similar to the following:

1. Creating Binding Classes...
WSWS3185I: Info: Parsing XML file:  HelloWorld.wsdl
WSWS3282I: Info: Generating .\mypackage\HelloWorld.java.
WSWS3282I: Info: Generating .\mypackage\HelloWorldSoapBindingStub.java.
WSWS3282I: Info: Generating .\mypackage\HelloWorldService.java.
WSWS3282I: Info: Generating .\mypackage\HelloWorldServiceLocator.java.
WSWS3282I: Info: Generating .\mypackage\HelloWorldServiceInformation.java.
2. Compiling Java Client...
3. Running Java Client...
Hello World!

Back to top

Downloads

Information about download methods

Resources

Learn

• Develop a web service without an IDE, Part 1: Focus on the Server, the first part in this series, shows to create a web service provider, including the deployment descriptors and the Java classes; and demonstrates the Java compiler, Java2WSDL, and WSDL2Java command-line tools.
  
  
• Develop, test, and deploy web services using Rational Application Developer V6.0 (developerWorks, January 2005) offers a tutorial on using Rational Application Developer to create a web service provider and client.
  
  
• The book J2EE Web Services is a comprehensive guide to developing and deploying web services using J2EE technology.
  
  
• W3Schools offers Web-building tutorials from basic HTML and XHTML to advanced XML, Multimedia and WAP.
  
  
• WebSphere Version 6 Web Services Handbook Development and Deployment is an IBM Redbook that discusses Web Services.
  
  
• Documentation on WSDL2Java documentation can be found on the InfoCenter.
  
  
• Java2WSDL documentation documentation is also available on the InfoCenter.
  
  
• The web services and SOA technical libraryfeatures developerWorks articles on Web Services.
  
  
• SOA and web services -- hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop web services applications.
  
  

Get products and technologies

• Download the trial version WebSphere Application Server V6.0 Trial Version to follow the steps in this article.
  
  

Discuss

• Participate in the discussion forum.
  
  
• developerWorks blogs -- get involved in the developerWorks community.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Preparation
• Creating the client
• Create the client stubs from the WSDL
• Develop a Java class that uses the stubs
• Compile and run the client
• Setting up a TCPMonitor Trace
• Conclusion
• Appendix A: Building the client automatically
• Downloads
• 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

Discover knowledge paths

Skill-building guides for Linux, open source, cloud, Java, business analytics, and more.

Special offers