The article walks you through the entire building and deploying process, including:

• Using WebSphere Studio to develop a simple Java class
• Using WebSphere Studio to wrap the Java code as a Web service
• Using WebSphere Studio to package the Web service and Java code as an enterprise application
• Deploying the Web service and Java code to a Application Server accessible from the public Internet
• Using WebSphere Studio to publish the service to the Speed-start Community Collection on the IBM UDDI Business Test Registry.
• Using WebSphere Studio to discover and import a service published to the Speed-start Community Collection on the IBM UDDI Business Test Registry.

This article assumes you are using version 5.0 of both WebSphere Studio and the Application Server. If you are running WebSphere Application Server V4.0, you will need to make sure that the enterprise application you package conforms to J2EE 1.2 (more on this in the section entitled Creating the Ear.) If you are running version 5.0 of WebSphere Studio (as opposed to version 5.0.1), you will need to upgrade to 5.0.1 or apply one additional manual step. Details are available in the section entitled Are you running WebSphere Studio 5.0.1?.

Implementing the service

You will first create a new project and a class that will implement a simple service that returns the system date and time of the server on which the service is running. This allows a remote caller to get the date/time of the server.

Creating a new Web project

To create a new Web project, select File > New > Project from the menu bar. This opens the New Project wizard. Select Web in the left pane and Web Project in the right pane and click the Next button. This will bring up the next dialog in the wizard (shown in Figure 1) in which you define the Web project. Set the project name to ServerClock (or use your own name) and click the Finish button. You can specify that this project will be used within a new enterprise application project by clicking the Next button, or you can manually add this to an enterprise project later.

Creating the RemoteServerClock Class

You now need to build the RemoteServerClock class. This class implements a service returning the server date/time.

Within the Package Explorer, right click on the ServerClock folder and select New > Class. This brings up the Java Class dialog allowing you to create a new Java class. Enter the package name and the class name as shown in Figure 2.

Now you need to write the code for the class, which is a very simple method returning a single string:

package edu.wsspeedstart;

public class RemoteServerClock {
  public String getServerClock() {
    return java.util.Calendar.getInstance().getTime().toString();
  }
}

Back to top

Creating the Web service

Now that you have the method returning the date/time as a string, you can wrap it as a Web service.

Selecting the project and the class

From the menu bar select File > New > Other. This brings up a dialog in which you select Web Services from the left pane and then Web Service from the right pane. Click the Next button to move to the next page in the wizard. Select Java Bean Web Service as the Web service type and check the checkbox to generate a Java proxy so that you can test your Web service within the WebSphere Studio test environment. Click the Next button to move to the next wizard step. Keep the Use Defaults option in the Web service deployment environment selection and make sure your ServerClock Web project is selected. Click the Next button to move to the next wizard step. In the next screen of the wizard you are asked for the class that you want to expose as a Web service. Select RemoteServerClock and click the Next button (see also Figure 3).

At this stage you have finished specifying which functionality you want to wrap as a Web service; click the Next button to set the URN.

Setting the service URN

The service URN uniquely identifies the service. Because you are building a Web service wrapper for an existing piece of code (the RemoteServerClock class), you need to tell the server how to map the unique service identifier to the implementation class; the runtime will use this to identify the class performing the service when a request comes in.

Set the Web service URI field to urn:RemoteServerClock and set the scope to Session as shown in Figure 4. Click the Finish button.

Back to top

Building a proxy and a test client

Before you deploy your Web service to the Application Server you should test your code within WebSphere Studio. This is very easy to do because WebSphere Studio automatically generates a proxy and a simple client application. The proxy is a Java class that packages up a code object, places the URN within this object and invokes the request. On the server side the URN is extracted and used to look up the class that should receive the request. This is all done on the server side through a special servlet called the RPC router, which is part of the Application Server runtime. The communication path is shown in Figure 5.

The client is a simple JavaServer Page (JSP) page that uses the proxy to make the call to the server (in this case both residing within WebSphere Studio). The test application has three panes. In the left pane you select which Web service method you wish to invoke. Click on getServerClock(). The top right pane will then contain a form matching the input arguments to the service (none in this case). Click the Invoke button. The lower-right pane displays the output of the service -- the date/time of the machine on which the application is running. If you have the console pane open, you will see various logging messages emitted by Application Server as shown in Figure 6.

Back to top

Packaging your application for deployment

Now that your service is working you can go ahead and package it for deployment as an enterprise application within Application Server.

Modifying the WSDL

The first thing you need to do is modify the WSDL so that clients who discover your service will find it within the Application Server instance as opposed to the default setting of localhost, which will only work when you are running within the WebSphere test environment in WebSphere Studio. The service interface file (RemoteServerClockService.wsdl) includes address information about where the service resides and where the WSDL files reside. When WebSphere Studio generated these files, it pointed these locations at the test environment. For example, the SOAP address element will look as follows (assuming the test environment is listening on port 9080):

                <soap:addresslocation="http://localhost:9080/ServerClock/servlet/rpcrouter"/>

This is good for testing your code, but once you are ready to deploy your application, you should modify the address information. If you are deploying on an Internet-accessible node called xxx.yyy.zzz on port ppp then modify every instance of localhost:9080 to xxx.yyy.zzz:ppp, or xxx.yyy.zzz if deploying on port 80.

Creating the EAR

In order to deploy your Web service as an EAR, you need to include it within an enterprise application. Using the File menu select New > Project... and select J2EE in the left pane and Enterprise Application Project in the right pane. Click the Next button. Then select whether you want to create a J2EE 1.2 application or a J2EE 1.3 application. If you will be deploying on version 4.0 of WebSphere Application Server you should use J2EE 1.2. If you are using WebSphere Application Server V5.0, you can choose either but it is preferable to choose J2EE 1.3. Click the Next button to go to the next wizard step in which you set the enterprise application name. Deselect any additional module because you will be adding the Web project manually -- your screen should look as follows in Figure 7, and you can click the Finish button to create the enterprise application.

Adding the WAR

Open the enterprise application project in the navigation pane. The first entry is the Application Deployment Descriptor. Double click the deployment descriptor to open it with the top right editing pane. At the top right is a list of all modules within this enterprise application; this list is empty because the enterprise application is still only an empty shell. Click on the Details button and, in the modules editor, click the Add... button just under the module list. Select the ServerClock module from the list and click the Finish button. The module list should now look as follows in Figure 8.

Save the application deployment descriptor so that you can export the enterprise application.

Exporting the EAR

The last step is to package your application as an EAR. Rebuild your project one last time by selecting Project > Rebuild All from the menu bar.

In the Navigator pane, right-click on the enterprise application project and select Export. Then select EAR File from the list in the wizard. Select a directory to export the file to and click the Finish button. WebSphere Studio will create the EAR file with an embedded WAR file, which includes all the Web service specifics as well as the implementation code.

Back to top

Deploying on the WebSphere Application Server

Now that you have created the EAR file you can go ahead and install the enterprise application on Application Server.

Starting the administrator's console

To deploy your application and Web service you use the WebSphere administrator console. Make sure the Application Server is running and, if not, start up both the HTTP server and the WebSphere Application Server.

Open the administrator's console by navigating your browser to http://localhost:9090/admin. Enter your user ID and click the OK button.

Installing the enterprise application -- specifying the EAR

Using the navigator pane on the left, go to Applications > Install New Application. Enter the path to the EAR file or use the Browse button to find it. Because you are deploying an EAR file, you do not need to specify anything else -- all of the application properties are embedded within the EAR. The wizard should be similar to Figure 9. Click the Next button.

Deploying the Web module

Because the EAR includes a Web module, you need to specify onto which virtual host it should be deployed. The next window in the Application Installation Wizard lets you specify the virtual host. Keep the default_host value and click the Next button. Click Next again unless you want to modify some of the default deployment parameters. Map all Web modules to the default host as shown in Figure 10 and click the Next button.

Completing the installation of the enterprise application

In the next wizard step (see Figure 11), select the cell and server on which the Web modules are to be deployed and click Next.

Finally, confirm that all the application details are correct and click the Finish button. The application will be installed -- this might take some time, so be patient. If all goes well you will see a set of printouts on the screen of the form:

ADMA5005I: Application ServerClockEA configured in WebSphere repository 
ADMA5001I: Application binaries saved in f:\Program
   Files\WebSphere\AppServer\wstemp\admin\workspace\cells\rbn\applications\
   ServerClockEA.ear\ServerClockEA.ear 
ADMA5011I: Cleanup of temp dir for app ServerClockEA done. 
ADMA5013I: Application ServerClockEA installed successfully. 
Application ServerClockEA installed successfully.
            

Save the changes to the master configuration by clicking on the Save to Master Configuration link and clicking on the Save button. When you now click on the Enterprise Applications link in the navigator pane, you should see your new enterprise application.

Re-generating the Web server plug in

Before starting your Web service, you need to regenerate the Web server plug-in. The plug-in controls the communication between the Web server and Application Server. The Web server plug-in needs to know that URLs having a prefix of ServerClock must be forwarded to the WebSphere Application Server. This plug-in accesses the service by using a URL of the form: http://<hostname>/ServerClock/servlet/rpcrouter.

Finally, restart both the Web server and the application server. Your service is now deployed on the Application Server and accessible to the Internet. Now make sure someone other than yourself knows about it by publishing the Web service to a UDDI registry.

Back to top

Publishing the Web service to a UDDI registry

Now that your Web service is deployed on the Application Server, the last stage left is to publish the Web service to the UDDI test registry; you will need to use a special category to publish your Web service under the Speed-start program. But the first thing you need is to have a registered user name in the test registry.

Registering as a user on the IBM UDDI Business Test Registry

The IBM UDDI Business Test Registry is a public UDDI registry that can be used to register businesses and services to the public. It is most commonly used to test the publishing and discovering of Web services.

Before you can publish your Web services to this registry, you will need to set up a user account. Open your browser and navigate to https://uddi.ibm.com/testregistry/registry.html. Then click the Get an IBM user ID and password link. Fill in the registration page; the most important values to remember are the ID and password. Make sure you have the spelling of your email account correct because you will need to receive an activation email.

After accepting the license terms for using the UDDI registries and completing the registration, you will receive an activation email with a subject of IBM UDDI Registration Notice. Click on the link in the email to activate your account.

Are you running WebSphere Studio V5.0.1?

Now that you have an account within the test registry, you can go ahead and publish the Web service you just installed on the Application Server within the UDDI registry. You should check whether you are running WebSphere Studio V5.0.1; if you are running version 5.0, you will need to do one manual step in order to publish your service (see Special Instructions if you have not upgraded to version 5.0.1). If you are running version 5.0 and follow the normal procedure, you will receive an exception within the UDDI explorer, as shown in Figure 12, and will not be able to publish the service.

It is much simpler to upgrade to version 5.0.1. This is a straightforward procedure as long as you are using a high speed Internet connection. The upgrade requires two PTFs with an aggregate size of around 240MB, which will only be a problem if you don't have a high speed connection. Upgrading to version 5.0.1 is easy -- just follow the instructions provided at http://www3.software.ibm.com/ibmdl/pub/software/websphere/studiotools/html/501/wsad/install.html showing how to install the 5.0.1 PTF.

Opening the Web Services Explorer

Assuming you are using version 5.0.1, to open the Web Services Explorer, select File > Export from the menu bar. In the Export Wizard select Web Service and click the Next button (see Figure 13).

Check the Launch the Web Services Explorer box to publish this Web service to a UDDI Registry and make sure that the IBM UDDI Test Registry is selected; click the Finish button to launch the Web Services Explorer.

Publishing the business

Before you can publish your Web service to the UDDI registry you need to publish your business. In the Navigator pane (left pane) click on the IBM Test Registry link. In the toolbar of the Actions pane (top right pane) click the Publish tool (see Figure 14).

Make sure the Business option is selected in the Publish pull down menu, enter the user ID and password you used in the registration, and the name/description of the business you want to publish. Click Go.

In the Status panel at the bottom right you will see that your business was successfully published. You should now add identifiers such as phone numbers, fax numbers, contact names, etc. Click the Add button to add an identifier and fill in the fields. You should also add the categories to which this business belongs (similar to the Yellow Pages categorization scheme). You can add multiple categories if your business belongs to more than one business category. When you are done, submit the form using the Go button.

Publishing the service

Once you have published your business, you can go ahead and publish the service itself. You should still be browsing the business, but if not, use the left Navigator pane to select the business entity. On the Actions toolbar in the top right pane, click the Publish Business Service tool (see Figure 15).

Enter the URL pointing to your WSDL file. This is the most important part in the publishing process since the WSDL file service implementation file defines the service endpoint.

Using the right categorization

Before you can publish the service, you need to specify one or more names, descriptions, and categorizations for the service. Add the names and descriptions so that people can easily search for your service.

Note: Besides any categorizations that you want to tag your service with, you need to add a special category for your service to be registered within the Speed-start Community Collection. This is the last step you must complete to list your service with the Speed-start program.

If you upgraded to 5.0.1 this is very simple. In the categories section add a category and select a type of dWCommunity. Then click the Browse... link (see Figure 16).

In the popup shown in Figure 17 pick the Speed Start option. This special category distinguishes services published in the UDDI test registry as Speed Start services.

Special instructions if you have not upgraded to 5.0.1

If you have chosen not to upgrade to version 5.0.1 do not click the Browse button! Instead, manually type in a key value of Speed Start and publish the service. This will have the same affect.

Back to top

Verifying the Speed-start publishing

In order to verify that your service is indeed in the test repository and viewable under the Speed Start program, go to the Speed-start Community Collection (see the Resources section). Your service should appear as shown in Figure 18.

Back to top

Discovering and testing the service

Now that you know the service is published on the registry, let's look at how a consumer would discover and use the service.

Select File>Import from the menu bar to bring up the Import Wizard. Select Web Service and click the Next button. Check Launch the Web Services Explorer to find a Web service from a UDDI Registry and make sure that the IBM UDDI Test Registry is selected. Click the Finish button to bring up the Web Services Explorer in import mode.

Click on the Find tool in the top-right pane:

Select Businesses from the drop down and SpeedStartExample as the name of the business you wish to find and press Go:

Importing the WSDL

Click on the business that is retrieved by the search. Expand the query results entry in the UDDI Navigator pane and click on SpeedStartExample. Click on the Get Services tool:

Since you have only published one service, the RemoteServerClock service will be shown:

Click on the Get Service Interface tool and the click on the Import WSDL to Workbench tool:

You now have to specify which project to import the Web service to and click the Go button. This imports the WSDL file to your project. You are now ready to create the proxy and the sample test application.

Creating the proxy and test application

To create the proxy and sample test application, use WebSphere Studio's Web Services Wizard.

Select File>New>Other from the menu bar. Select Web Services in the left pane and Web Service Client from the right pane. Select Java proxy from the drop down and check Test the generated proxy. Click Next. Enter the WSDL binding document and click Finish.

This will generate the proxy and the test application and launch the application within WebSphere Studio for you to use as shown below. Note that the test application (with the set of sample JSPs) is running within WebSphere Studio, but the actual transactions are being performed on an instance of the Application Server deployed on the Internet by IBM.

Back to top

Summary

This article walked you through the entire process of developing, deploying, and publishing a Web service that is accessible on the Community Collection managed as part of the Web services Speed-start program. You saw how to develop a simple Java service, wrap it as a Web service, deploy it on a WebSphere Application Server instance, publish it to the IBM Business Test Registry with the appropriate categorization, and then discover and import this service -- all using WebSphere Studio and WebSphere Application Server.

Resources

• Find more information on the Speed-start program, with tools, training, and support and the test registry on the Speed-start Web services pages.
  
  
• Access the Speed-start Community Collection, hosted by the IBM UDDI Business Test Registry
  
  
• Access the UDDI Business Test Registry at: https://uddi.ibm.com/testregistry/registry.html.
  
  
• Read more about UDDI registries in "Understanding WSDL in a UDDI registry" (developerWorks, September 2002).
  
  

Get resources for the technologies utilized or referenced in this article below:

• Download a trial version of WebSphere Application Server Version 5.
  
  
  
• Download a trial version of WebSphere Studio.
  
  
  
• Get a user ID for the UDDI Business Test Registry.
  
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Implementing the service
• Creating the Web service
• Building a proxy and a test client
• Packaging your application for deployment
• Deploying on the WebSphere Application Server
• Publishing the Web service to a UDDI registry
• Verifying the Speed-start publishing
• Discovering and testing the service
• Summary
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers