Web Services Tools Evaluation Guide

1.0 Introduction

The Web Services Tools contribution provides an extensible framework of wizards, actions, preferences, code generators and Web applications to help Eclipse users create, publish, discover, consume and test Web Services chiefly for, but not limited to, the Java programming language and the J2EE platform. Included in the contribution are tools for building Apache Axis Web services and Web service clients on Apache Tomcat.

The design and capabilities of the tools, both internally and visually, are anchored to a small but significant set of public specifications and consortiums, including:

Included in the Web Services Tools contribution are: Note: The J2EE Tools and XML Tools contributions also contain tools for Web services, such as the WSDL Editor, the WSDL and WS-I validators, and the J2EE Project Explorer.

2.0 Getting Started

Of all the Web services tools included in this contribution, three of them stand out as the primary means to developing and working with Web services: If you have a connection to the internet, then the easiest way to get started with the tools and learn a bit about Web services is to run the Web Services Explorer and play with some Web services on the internet. You don't need anything in your workspace, and you don't need any installed servers. Follow the instructions in Chapter 3.1 to use the Web Services Explorer to invoke an operation on a Web service available via XMethods.

If you do not have a connection to the internet, then the next easiest way to get started is to create your own Web service. The Web Service wizard will help you do this, however, there are a couple of prerequisites. First, you will need to download a version of Apache Tomcat and install it into Eclipse WTP using the Installed Runtimes preference page. Second, you will need to create a Web project and create a basic Java class within it. Follow the instructions in Chapter 3.2 to create a Web service and Web service client bottom-up from a simple Java class.

3.0 Quick Tour

The following chapters will guide you through a few of the more prominent tools in this contribution:
  1. Using the Web Services Explorer to test a Web service
  2. Using the Web Service wizard to build a Web service bottom-up from Java
  3. Exploring the Preferences
  4. Exploring the Wizards
  5. Exploring the Popup Actions
  6. Behind the Scenes

3.1 Using the Web Services Explorer to test a Web service

This scenario is very simple. It demonstrates how to use the Web Services Explorer to invoke operations on a Web service named "Temperature - Weather" as available from XMethods on the internet. The only prerequisite is that you be connected to the internet. If you are connected via a firewall, you can use the Internet preferences page (choose Preferences -> Internet from the main menu). Other than that, you can begin with a completely fresh workspace and no installed servers.
  1. Launch the Eclipse WTP workbench.
  2. From the main menu bar, select Run -> Launch the Web Services Explorer. This will take a few moments the first time while Eclipse's internal Tomcat server starts up and loads the Web Services Explorer application. After the Web Browser view opens, maximize it. Result:

  3. In the Web Service Explorer's toolbar (top-right), click on the WSDL Page icon, . Result:

  4. Click on WSDL Main. Result:

  5. In the WSDL URL field, enter the URL http://www.xmethods.net/sd/2001/TemperatureService.wsdl, then click on Go. Result:

  6. Under Operations in the right hand pane, click on getTemp. Result:

  7. In the zipcode string entry field, enter 90210, then click on Go. In the Status pane, you should see an answer like this:

    8. return (float): 67.0
    You may need to move the horizontal bar separating the Actions and Status panes upwards a bit to get a better view. Result:
Explanation

The Web Services Explorer is a JSP Web application hosted on the Apache Tomcat servlet engine contained within Eclipse. It is integrated into Eclipse on two levels: visually by virtue of it running in the embedded browser, and logically by virtue of it running as a thread in the Eclipse JRE. Though not demonstrated in this scenario, this latter type of integration allows the Web Services Explorer to access resources in the workspace, write resources into the workspace, and launch various Web services wizards.

The Web Services Explorer provides three key services to the user:

  1. Comprehensive support for discovering Web services in WS-Inspection 1.0 documents, and in UDDI v2 or v3 registries using the UDDI v2 protocol.
  2. Comprehensive support for publishing Web services to UDDI v2 or v3 registries using the UDDI v2 protocol.
  3. Comprehensive support for browsing and invoking Web services natively* via their WSDL and XSD.
* A key point of the scenario above is that no code was generated and no servers were required in order to invoke operations on the WSDL.

3.2 Using the Web Service wizard to build a Web service bottom-up from Java

This scenario shows how to create a simple Web service and Web service client from a Java class. The Java class in this scenario converts between the Celsius and Farenheit temperature scales. Before creating the Web service, there are three prerequisites:
  1. Install Apache Tomcat
  2. Turn off WS-I compliance checking
  3. Create a Web project
If you have completed these prerequisites, carry on with the scenario at chapter 3.2.4.

3.2.1 Install Apache Tomcat

  1. Download and unzip Apache Tomcat (this scenario was written using Apache Tomcat version 4.1.30, but other versions can be substituted).
  2. Start the Eclipse WTP workbench.
  3. Open Window -> Preferences -> Server -> Installed Runtimes to create a Tomcat installed runtime.

  4. Click on Add... to open the New Server Runtime dialog, then select your runtime under Apache (Apache Tomcat v4.1 in this example):

  5. Click Next, and fill in your Tomcat installation directory:

  6. Ensure the selected JRE is a full JDK and is of a version that will satisfy Apache Tomcat (this scenario was written using SUN JDK 1.4.2_05). If necessary, you can click on Installed JREs... to add JDKs to Eclipse.
  7. Click Finish.
Note: Further details on installing and using servers can be found in the Server Tools contribution.

3.2.2 Turn off WS-I compliance checking

  1. Open Window -> Preferences -> Web Services -> WS-I Compliance.
  2. Change both compliance levels from Suggest compliance to Ignore compliance since Apache Axis 1.0 does not lend itself to WS-I compliant Web services in general. Note that this prerequisite is not critical. If you leave the compliance level set to Suggest compliance, then the Web service wizards and the WSDL validator will simply produce warning messages telling you that your Web service will not be, or is not, WS-I compliant.

  3. Click OK.

3.2.3 Create a Web project

  1. Open File -> New -> Other... -> Web -> Dynamic Web Project to create a new Web project named Converter.
  2. Enter Converter into the Name field.
  3. Choose a Web version of 2.3.
  4. Choose a Target server of Apache Tomcat v4.1.
  5. Deselect Add module to an EAR project. Result:

  6. Click Finish.

3.2.4 Create a Web service and Web service client

  1. Import the wtp/Converter.java class into Converter/JavaSource (be sure to preserve the package).
  2. Select the file.
  3. Open File -> New -> Other... -> Web Services -> Web Service.
  4. Select Generate a proxy.
  5. Select Test the Web service.
  6. Select Overwrite files without warning. Result:

  7. Click Finish.
  8. It will take about one minute for the wizard to assemble the Web service and Web service client Web projects, start Apache Tomcat, and deploy the projects to Tomcat. Once finished, the generated Sample JSP Web application will appear in the browser view, maximized here for clarity:

  9. Under Methods, click on celsiusToFarenheit(float).
  10. Under Inputs, enter 37 into the celsius entry field.
  11. Click on Invoke. In the Result view, you should get a response of 98.6.

Explanation

The Web Service wizard is orchestrating the end-to-end generation, assembly, deployment, installation and execution of the Web service, Web service client, and sample JSPs. In this scenario we clicked Finish on page one. In effect, this is allowing the wizard to pick reasonable defaults according to the basic high-level choices made on the first page. If you repeat this scenario, but use the Next button to work thru the wizard, you will learn more about the kinds of choices that are available and the kinds of defaults being assumed.

Note that this evaluation guide does not include a Web Service Client wizard scenario. This is mainly because the above Web service creation scenario includes all the logical features and most of the visual features of the Web Service Client wizard. Also, note that the process of using the Web service creation wizard to create a Web service top-down is largely the same as for bottom-up. The only major difference is that the top-down scenario generates a skeletal Java class which you must implement in order to get any kind of useful response from the service.

After completing this scenario, the WSDL for the Converter Web service can be found in Converter/WebContent/wsdl/Converter.wsdl. Now that your Web service is running, there are a few interesting things you can do with this WSDL file. Examples:

  1. You can double-click on the WSDL to open the WSDL graphical editor.
  2. You can right-click on the WSDL and choose Web Services -> Test with Web Services Explorer to test the service (as similar to scenario 3.1 above).
  3. You can right-click on the WSDL and choose Web Services -> Publish WSDL file to publish the service to a public UDDI registry.
  4. You can click on the WSDL and choose File -> New -> Other... -> Web Services -> Web Service Client to generate a Web service client. Note, however, that we have already witnessed the internal and visual features of the Web Service Client wizard since, in addition to being its own wizard, it is quite literally embedded within the larger Web Service wizard.

3.3 Exploring the Preferences

This contribution includes a number of preference pages to help govern the default behaviour of the Web services tools in the Web Services Tools and XML Tools contributions.

The Internet preferences page found under Window -> Preferences -> Internet lets you configure regular and basic-authenticating firewall proxies for any plugin in Eclipse that opens HTTP connections to the outside world. Because of the proliferation of WSDL documents, Schema, Web services, UDDI registries and similar resources on the internet, the Web services tools are frequently called upon to load resources from the internet. For users running on the protected side of a firewall, the Internet preferences page is essential. The settings made on this page apply to all plugins running in the Eclipse JRE, not just to the Web service plugins.

All the other preference pages reviewed below can be found under Window -> Preferences -> Web Services.

The Popup Dialog Selection page lets you enable or disable the wizards associated with specific Web service popup actions. Most of the Web services popup (or context menu) actions are equipped with wizards which are visually enabled by default. Each of these wizards has a checkbox entitled "Do not show me this dialog box again." If you select this, then Finish the wizard, the next time you run the same popup action the wizard will be disabled, meaning the action will simply run with whatever default values are in effect. You can use the Popup Dialog Selection preferences page to re-enable the wizards for the various popup actions.

The Project Topology page controls the default J2EE project layout built by the Web service wizards for your Web services and clients. Using this page, you can choose your favourite J2SE or J2EE project type for Web service clients, and you can control whether your service and client projects get assembled into the same EAR or into different EARs. Note: It is recommended that you choose different EARs for services and clients. Because of the symmetry of the package-to-namespace and namespace-to-package mappings when generating Web services and Web service clients, it is common for classes of identical qualified names to appear in the service and client projects. If both projects are assembled into the same EAR, J2EE classloaders can end up loading the wrong classes.
The Resource Management page specifies the file overwrite, folder creation, and file checkout policies for the wizards.
The Scenario Defaults page controls the default choices that appear on the first page of the Web Service and Web Service Client wizards.
The Server and Runtime page lets you choose your favourite server, Web service runtime and J2EE level.
The Test Facility Defaults page lets you customize the preferred order of the available Web service test facilities in the tools. In the WTP, there are two, and in this default order: 1. The Web service sample JSPs (seen in scenario 3.2 above) and the Web Services Explorer (seen in scenario 3.1 above). The wizards will choose the first test facility in the list that is compatible with the scenario. For example, if you run the Web Service wizard with Generate a Proxy deselected and Test the Web service selected on page one, then the wizard will launch the Web Services Explorer. Although the Sample JSP test facility appears first in the list, the wizard will not choose it since the Sample JSPs require a generated Java proxy.
The Web Services Explorer page includes a couple of preferences that control how the Explorer talks to UDDI registries and to Web services. In general you will not need to visit this page.
The WSDL Files page lets you pick a default namespace for WSDL editing.
The WS-I Compliance page was visited in the prerequisites of scenario 3.2 above. It controls the degree to which the tools expect adherence to various WS-I Profiles.

3.4 Exploring the Wizards

In addition to the Web Service and Web Service Client wizards discussed above, there are a couple of other wizards in this contribution.

The Import WSIL wizard (File -> Import... -> WSIL) is used to create WS-Inspection documents in the workspace containing a list of one or more WSDL document URLs. The Web Services Explorer and some of the other wizards can also create WS-Inspection documents in the workspace. In all these cases, the purpose is to keep references to WSDL documents (via WSIL) in the workspace instead of copies of WSDL documents (which can become stale).


The Unit Test UDDI Registry Configuration wizard (File -> New -> Other... -> Web Services -> Unit Test UDDI) is the extension point for plugging in providers of UDDI registries. There are no UDDI registries included in the current WTP contribution, so the wizard will come up with no registries to choose from.

The Web Service Import wizard (File -> Import... -> Web Service) launches a wizard that helps you choose a UDDI Registry and then launches the Web Services Explorer so that you can begin searching for the Web service you are interested in.
The Web Service Export wizard (File -> Export... -> Web Service) launches a wizard similar to the aforementioned Web Service Import wizard that helps you choose a UDDI Registry and then launches the Web Services Explorer so that you can publish your Web service to the registry.
The Configure Handlers wizard is available from the context menu for certain WSDL documents and J2EE descriptors. It simplifies the process of developing and configuring JAX-RPC handlers into a JSR-109 compliant Web service or Web service client. Since Apache Axis is not a JSR-109 Web service runtime, the Configure Handlers wizard is of limited use unless a third party extends the WTP platform with a JSR-109 compliant Web service runtime.

3.5 Exploring the Popup Actions

The Web Services Tools contribution includes a handful of popup actions available on key resources, including: Popup actions available:
 
Action Remarks
Test with Web Services Explorer Launches the Web Services Explorer to invoke operations on a given WSDL document.
Publish WSDL file Launches the Web Services Explorer to publish WSDL to a UDDI registry.
Generate WSIL Launches a wizard that generates a WS-Inspection document from a given WSDL document.
Generate Client Equivalent to File -> New -> Other... -> Web Services -> Web Service Client.
Create Web service Equivalent to File -> New -> Other... -> Web Services -> Web Service for a bottom-up scenario.
Generate Java bean skeleton Equivalent to File -> New -> Other... -> Web Services -> Web Service for a top-down scenario.
Configure Handlers Launches the Configure Handlers wizard.
Generate Sample JSPs Launches that subset of the Web Service Client wizard that generates Sample JSPs from a Java proxy.

3.6 Behind the Scenes

There are several extension points and frameworks, and several examples of their use, incorporated into the Web services tools. This chapter provides a glimpse of the key extension points and a couple of significant frameworks.

3.6.1 Extension Points

 
Plugin Extension Point Remarks
com.ibm.env DynamicWizard Used to define dynamic wizards and, optionally, couple them to newWizards, importWizards, exportWizards and popupMenus extensions.
com.ibm.env actionDialogPreferenceType Used by dynamic wizards to enable or disable the "do not show me this dialog box again", and to control their appearance in the Popup Dialog Selection preference page.
com.ibm.etools.webservice.consumption wsfinder Used to plug in objects that help to locate Web services in the workspace by looking for specific patterns (WSDL files, deployment descriptors, etc). Not yet used within WTP.
com.ibm.etools.webservice.consumption WebServiceStartServerType Used to plug in objects that manage startup details specific to different kinds of servers. Though currently used within WTP, this extension point is likely to be removed.
com.ibm.etools.webservice.consumption serverDefaulter Used to plug in algorithms to compute a reasonable runtime target for projects that do not have a runtime target.
com.ibm.etools.webservice.consumption.ui objectSelectionWidget The second page of the Web service wizard is where the user selects the object from which they will build their Web service. Since the selection controls differ from object type to object type (eg. Java, EJB, WSDL...), the selection controls are contributed to the page via this extension point. Extensions for Java and EJB selection are included in the WTP.
com.ibm.etools.webservice.consumption.ui publicUDDIRegistryType Used to declare known public (internet) UDDI registries to the wizards and the Web Services Explorer.
com.ibm.etools.webservice.consumption.ui privateUDDIRegistryType The com.ibm.etools.webservice.uddi.registry plugin uses this extension point to contribute its private registry configuration page to the end of the Web service wizards. This extension point is likely to be removed, with the contents of the com.ibm.etools.webservice.uddi.registry plugin being pulled right into this plugin.
com.ibm.etools.webservice.consumption.ui webServiceServerRuntimeType Used to extend the Web service (creation) wizard with pages and logic that handle the development, assembly, deployment and installation tasks for Web services of a specific Web service implementation type, using a specific Web service runtime, and for execution on a specific runtime target (server).
com.ibm.etools.webservice.consumption.ui webServiceClientType Used to extend the Web service (creation) and Web service client wizards with pages and logic that handle the development, assembly, deployment and installation tasks for Web service clients of a specific Web service implementation type, using a specific Web service runtime, and for execution on a specific runtime target (server or client container).
com.ibm.etools.webservice.consumption.ui webServiceTest Used to plug Web service test facilities into the Web service tools.
com.ibm.etools.webservice.consumption.ui clientProjectType Used to plug in project types that can accept a JAX-RPC Web service client and that would appear in the Project Topology preference page.
com.ibm.etools.webservice.explorer wsexplorerType Used to plug in alternative WSDL/UDDI exploration tools to the Web Services Explorer.
com.ibm.etools.webservice.uddi.registry privateUDDIRegistryType Used by providers of specific private UDDI registries to add their registries to the private registry configuration page (which is in turn extended into the wizard using com.ibm.etools.webservice.consumption.ui's privateUDDIRegistryType extension point).
There are also two frameworks that help address two key requirements of the Web services tools. One requirement is that all the work done by the Web services tools be accomplished, where possible, in a variety of user interface environments including, but not limited to, Eclipse. The other requirements is that the Web services wizards in Eclipse exhibit page sequences that are highly dynamic and extensible.

3.6.2 The Environment Command Framework

The Environment Command Framework or ECF provides the means for encapsulating and coordinating the execution of the maximum amount of tools code in the form of reusable, stateful Command objects that are not tied to any particular user interface environment. The ECF defines “Command Fragments” as a means for organizing Commands into a tree that is progressively flattened and executed for a given scenario. The ECF manages the flow of state between Command objects, and manages the execution, undoing, and redoing of Commands. The ECF makes heavy use of URIs to manipulate resources regardless of their location in an Eclipse workspace, a filesystem, an HTTP server, or so forth. Examples of user interface environments are Eclipse SWT dialogs and wizards, Eclipse headless commands, Java command line tools, ANT tasks, JUnit testcases, Web services and batch processes.

The framework, as well as a command line implementation of it, can be found in com.ibm.env.core. An Eclipse implementation of the framework can be found in com.ibm.env.

3.6.3 The Dynamic Wizard Framework

The Dynamic Wizard Framework or DWF provides for the assembly of highly dynamic and extensible wizards. It also provides boilerplate extensions to the Eclipse newWizards, importWizards, exportWizards and popupMenus extension points to permit DWF wizards to be plugged into these Eclipse extension points with no adapter code and only a small amount of extension XML. The sequence of pages in a DWF wizard is not fixed. Rather, the determination of the “next” page is made on demand based upon up-to-the-minute state and/or known extensions to DWF extension points. The DWF provides for the abstract binding of (non-visual) ECF Command objects and Command state data to (visual) SWT Widgets and Widget state. In this manner, a DWF wizard becomes an overlay over a Command Fragment tree.

The framework can be found in com.ibm.env.

4.0 Provide Feedback to Us

We encourage development/design feed back on the wtp-dev mailing list. You can subscribe to the list via this link.

For usage questions, discussion of bugs, and strange behaviour please post to the eclipse.webtools newsgroup. Information on the Web Tools Platform newsgroup can be found here.