Generic HTML SOAP Client:
Calling WSDL-Described Web Services via an Interactive HTML Form

What is this?

This document explains how you can use the Moby libraries to provide users with interactive HTML forms for calling existing Web Services (described with a WSDL file). There is nothing Moby-dependent about this code, so you could use it as a general Web Service interactive proxy, but it is the basis for Daggoo, hence its inclusion in the Moby codebase. The servlet described here proxies requests to the original Web Service.

The Java code used here provides a similar functionality to that of The Generic SOAP Client at soapclient.com or this one, but mine is free (as in speech), and you can easily customize its behaviour.

Sections

• What are the prerequisites?
• Step 1: Deploy the servlet
• Step 2: Call services
• Step 3 (optional): Spice-up the service interface
• Questions?

What are the prerequisites?

The following should be (pre-)installed:

1. A Java Runtime Environment 6.0 update 6 or later
2. A Java Servlet container, such as Apache Tomcat. If you don't have one set up, here's a very quick guide.
3. The SoapServlet Web Archive (WAR) that will actually provide the service's HTML interface.
4. An existing WSDL file, with the Web Service deployed of course

Step 1: Deploy the servlet

The WAR file needs to be deployed in the Servlet container. How you do this depends on the container. For Tomcat, the easiest way is to use the management Web interface (e.g. http://your.servlet.host:8080/manager/html, but change 8080 appropriately if you had to follow Step 0) and upload the WAR.

1. Specification of WAR Upload

2. Successful deployment

Step 1: Call services

I. Load up the servlet in your Web browser (the URL will be something like http://localhost:8080/SoapClient. The first screen will simply ask you what WSDL describes the service you want to call.

II. Fill in the form. In the example below, two parameters suffice, but of course other WSDLs may have more than one method, different parameters, etc..

III. Voilà! Now you have your Web Service output, wrapped in a small HTML doc for viewing purposes.

Spice-up the service interface

There are two main way you might want to customize SoapServlet. First, you may just think the look and feel is ugly (I agree). In this case, you can change the wsdl_ask.css, wsdl_input.css or wsdl_result.css files in the WAR's stylesheets directory. These three cascading stylesheets correspond to the Web pages in steps I, II and III above. The common.css file is also used by all pages.

The second, more involved way to change the appearance and/or behaviour of the servlet is to provide a DataRecorder. The DataRecorder interface is used to provide interception callback methods during the HTML generation and Web Service calls the servlet performs. For example, PBERecorder intercepts servlet messages in order to record on-the-wire data and add both AJAX components (floating hints) and extra links in the HTML interface. Watch the video below to see how different the interaction is from the example screenshots shown above. All the browser interaction between 1:20 and the end of the video is controlled by the PBERecorder intercepting and messaging SoapServlet messages. This demonstrates the nice separation of concerns between the WSDL parsing/calling, and the user interface. The yellow screens are solely under the control of the DataRecorder, using the passthrough mechanism.

To use SoapServlet for your own more complex WS-calling system, simply implement a DataRecorder and register it with the servlet. This can be done at the Java code level with the SoapServlet.setRecorder() method, or in the WAR's WEB-INF/web.xml file by uncommenting the context-param called dataRecorder, setting the param-value to the fully qualified class name you wrote that implements DataRecorder. Make sure your DataRecorder has a no-args constructor if your going to use this autoloading functionality. Also make sure you include your new class in the WAR's WEB-INF/classes directory too!

To help you in writing a DataRecorder, the diagram below shows where your DataRecorder can affect the servlet:

Questions?

If anything is unclear or doesn't work as advertised, please e-mail me and I'll try to correct the issue: gordonp @ ucalgary.ca