Web Services Explorer

Developers Guide

Author: Gilbert Andrews

This document has been written to help developers improve and utilize the important features of the WSE.

Overview

The WSE was created to test, and publish webservices. There are three parts of the WSE including:

UDDI

WSDL

WSIL

Three of these areas will be discussed at some length in the article. The UDDI and WSIL areas are decreasing in importance so less attention will be given to these.

How to access the code

The WSE is contained within the Web Tooling Platform(WTP) project code. The exact plugin is org.eclipse.wst.ws.explorer contained in the wtp cvs repository.

Where is it launched

The WSE is launched from a few places already in WTP. The Webservices team created the WSE and are the main users. There are a number of scenarios that facilitate the launching of the WSE.

• Launch the WSE from the J2EE perspective.

1. Choose the J2EE perspective and choose run-> Launch the webservices explorer.

• Launch the WSE when using the service wizard

1. Right click on a Java file and under the webservices directory choose Create a webservice.

2. Right click on a wsdl file and under the webservices directory choose Create a skeleton webservice.

• Launch the WSE when using the client wizard

1. Right click on a wsdl and under the webservices directory choose Create a webservice client.

Where is the launch JSP

The WSE is launched from wsexplorer.jsp. Looking at the figure below we can see this is contained in the wsexplorer folder. All of the JSP code is contained in this directory. In the general directory we can also see some other JSP code that helps facilitate the launch.

General Division of Code

The code is divided into three areas. the JSP's, Java source and everything else.

The JSP's

Overview

The Java Server Pages(JSP) consist of a great portion of the code in the WSE. A JSP can contain Java source, html and Java script. The JSP's end with a .jsp and are easily recognizable. These JSP's are compiled and at runtime are formed into a Java Servlet by the server. The html code to be used by browser is then formed up based on requests from the browser. The newly formed Java Servlet typically looks like what might be found in Figure 4.

The reason I mention these Java Servlets are that in the past it has been necessary to actually debug through these when finding and solving problems in the WSE. This is normally done by running a build script in self hosting. The build script can be designed to compile the JSP's into servlets. Then debug statements can be placed in the servlets.

JSP Code Structure

Looking at Figure 1 we can see the JSP code it is all contained under the wsexplorer directory. Note there is the main folder which holds the launch point then there are ten other folders. Thes folders contain the rest of the JSP's in the plugin. Here are the ten folders and a breif description of the types of function contained within.

Be aware that the main purpose of the WSE is to provide three main pages. These pages due the duty of providing WSDL, UDDI and WSIL capabilities. The directories alluded to below are the general directories. Within each of the 3 main categories are subcategories. For instance There are general actions that the WSE uses there is an action directory also specifically for the WSDL. These are tasks that are used often in that page.

Action - Here you find the general action JSP types. These are common tasks that are performed again and again by all JSP pages.

CSS – Common CSS templates.

Favorites – Common JSP's related to the favorite wizard .The favorites will be covered later on in more detail.

Images – all general images are kept here ie jpg.

Scripts – As mentioned before Java scripts are use quite extensively and this is where you find common scripts.

Figure 4 Java Servlet

UDDI – Universal Description Discovery and Integration(UDDI) contains JSP's used to publish and find web services to UDDI repositories.

WSDL – Web Service Description Language(WSDL) contains JSP's related to the task of displaying and utilizing a WSDL.

WSIL – Web Service Inspection Language(WSIL) contains JSP's used to read WSIL documents and find services through this venue.

WSDL, UDDI, WSIL and Favorites Are The Face

The above statement alludes to the fact that the WSE has a face in its four pages. This face is made up of forms that are contained in JSP's.

WSE Design

The design of the WSE is consistent throughout the four views. The design includes a model, view, controller concept. To implement this design JSP's and Java source are used in conjunction.

General Design

The design of the WSE follows the pattern shown in the diagram. It starts with the WSE on one of its various forms. The user makes some request by entering data into the web browser. Then a link is selected and either some java script is run if or the form is submits to the Jetty server. Within the form is an action JSP that the server evaluates. Normally there is an action Java source file of the same name that the JSP executes. This updates the Controller class with status and properties to be held in one of the perspective classes. The action JSP then sets the navigator, properties and status JSP's as the next to be evaluated. The three new JSPS are then processed by the server and info is gathered in the form of status and properties from the Controller/Perspective classes.

WSDL design

The most important function of the WSE is its role as a WSDL test engine. Therefore I will dedicate the majority of this paper to the design of this function.

The first and most import duty of the WSDL page is to open the WSDL. This includes analyzing the WSDL and using the XSD model provided. The actual code that is followed starts with OpenWSDLAction.jsp. The OpenWSDLAction.java, is called and then the WSDLElement. The WSDLElement gets a definition file from the WSDL4J which contains WSDL and XSD parts.

Using WSDL4J

The WSDL file contains two parts, WSDL parts and an XSD schema. Both of these parts may be distributed over a number of files and locations and that explains why the WSE handles the WSDL4J in the way that it does.

As in the diagram the WSE needs to convert a WSDL URL which points to a WSDL location into a WSDL4J model. The WSE hands in the WSDL URL and get back a WSDL definition file. This definition holds two types of data as we see in the diagram, the pure WSDL constructs that are accessed using WSDL4J API and the XSD constructs which are accessed using the eclipse XSD Model API. So This incorporates two sets of code that the WSE using all the time here are the imports to look out for.

XSD

org.eclipse.xsd

WSDL4J

javax.wsdl

Once the WSE gets the WSDL definition file it then extracts the data and creates its own model to suit its needs of forming a SOAP message to send to and invoke the service. Even in the internal WSE model it still uses the eclipse XSD model classes. The WSDL parts will often have there own version in our model. Another words we will wrap our model classes around the WSDL4 class. You will see examples of this as we go further.

Getting The Schema List

The first data the WSE extracts is the XSD schema imports. A list of these schema is kept in the WSDLElement class. This is done currently by accessing extensibility objects in the WSDL definition file. We then do an exhaustive search to gather all the schema that are attached. The XSD model does a lot of this gathering for us mostly we are interested in making sure we have our own list of imported schema and referenced schema. In order for the WSE to take advantage of the power of the eclipse XSD model we place the WSDL into a ResourceSet. This is a concept used by the EMF models to keep track of data such as schema.

In the diagram above we are handed one schema from the extensibility object in the WSDL definition file as we check all the possible imports and references our list in WSDLElement grows to five.

Building The WSE Model

Now the WSE is ready to create its own model from the WSDL info in the definition file. We get this info from WSDL4J classes that represent parts of a WSDL file. If you do not know all the parts in there you might want to touch up as you will see them come up shortly.

The first significant part we need look at is the service element. We get the WSDL4J elements and there could be more then one. This is done by calling getServices() on the WSDL file. We then create our model class WSDLServiceElement for each service.

Each Service Element has a port in the WSDL4J model our model doesn't represent this as it is one to one with service. Each port may have one or more bindings. We therefore keep track of the binding objects using a WSDLBindingElement. Each binding then has a porttype since it is also one to one we just keep a copy in the binding element. The porttype may have one or more operations. We keep track of each operation in a WSDLOperationElement.

As you see in the diagram below our internal model keeps track of the elements of the WSDL starting from the service and working down to each operation.

A Loaded WSDL Page

When the WSDL has been loaded and the internal model has been built the user can use the three pages available. The “Navigator on the left”, the “Details” page on the right and the “Status” page below.

The WSDL Details Page

There may be more then one service available, if this is the case you can go to the original location of the WSDL and see a list of the services available. As it happens this page also has the bindings available and some other utility methods. As you can see you can import the WSDL to the workbench or the file system by selecting the first two links under the “other actions”. You can start the web service wizard or add this WSDL as a favorite. Notice this WSDL has one service “AddressBookService” by selecting this link you will be taken to the “Binding Details” page seen below.

The Binding Details

The “Binding Details” page is shown below. On this page we can see the “Operations” section with operations available on this service. There is also a section available to add endpoints where the service exists. When the user chooses an operation the WSE proceeds to the operations page.

The Invoke a WSDL Operation Page

As you can see below when an operation is selected the input parameters for the page are displayed for the user to place there inputs. Once the inputs are placed on the page and the user selects invoke the parameters are formed and validated. The soap message is then formed up and sent. The return parameter is then displayed in the status pane.

In order to provide all the info and actions available the model view controller design is used. We have seen part of the model used by the WSE to facilitate this now we will look at some of the remaining techniques and flow that accomplishes the array of capabilities provided.

The “Invoke a WSDL Operation” page starts by loading a JSP known as InvokeWSDLOperationForm.jsp. The input parameters are needed so a call is made to the internal model to provide the parts to display. The InvokeWSDLOperationForm has a reference to the WSDLOperationElement this in turn has a reference to the Operation located in the WSDL4J model. In order to show the user the input parameters the getOrderedBodyParts(). Which returns the input parameters from the Operation class in the WSDL4J model. The JSP will then go through the Input parts and create an XSD model as well as all the html needed for the input on the Operations Page.

The Input Parameters