LAVADORA Project



Tutorial

The use of the plug-in is fairly simple, but some details might seem unclear for the first-time user. It is also a good thing to know where and what to look for where searching for Lavadora in Eclipse's UI. The tutorial is divided into following sections:
General introduction

All data managed by plug-in is presented in single view, available through standard  view selection dialog -  Window/Show View. The view can be positioned in a perspective as any other Eclipse's view. Below we have a fragment of Workbench window (Java perspective) with Lavadora's view:


Lavadora's main view


There are three groups of information presented in the view:
  • per-project plug-in data, which includes generated Web Service clients, which comprise of Java files, WSDL document and its logical structure and (if created) Web Service information for the given project.
  • list of all user defined references to UDDI registries. For each of them you can see URL addresses for publishing and browsing in this registry (if provided) and also a list of created in it Business descriptions
  • list of all user defined references to existing Web Services. Each such a position consists of URL address of the given Web Service and a logical structure of its WSDL description
All functionality of the plug-in is accessible through view's context menu. Wizard for creating new Web Service clients is also accessible through the icon in the tool bar and through (File/)New/Other.../WebServices/New Web Service client option.

Lavadora stores its per-project data in ".wsdata" folder of every project with was previously initiated (for instance by generating a Web Service client) and all other data in location relative to particular workspace. Projects appear in the view only if they are initiated and open.

Creating Web Service clients

Creating a client for an arbitrary Web Service is a simple task. You do this by opening New Web Service Client Wizard. The wizard allows you to create a client in three ways:
  • By choosing one from the list of already defined references to Web Services (web references)
  • By specifying an exact URL address to the service WSDL document  (you have also a possibility to look for it in one of defined UDDI registries)
  • By choosing a WSDL file from some location in the workspace.
After choosing the second option you are provided with a possibility to add this URL address to the web references list.

New Web Service Client Wizard

Now you have to only specify an arbitrary (but project specific) name for your client, choose which source folder generate sources to (you can have several projects open and each of them can possibly have a number of such folders defined). Optionally you can choose which package the files should be generated to. If you don't do it the files will be generated to the package created based on given WSDL document namespace. Click "Finish" and that's it.

As a small help Lavadora will try to choose, whether it's possible a source folder for you according to selection in the plug-in view or in the Package Explorer (Lavador's view has preference). Please always check if this is what you actually want, though it is no problem making a mistake - you can always safely delete your client.

After code generation there is performed (if this was the first client in this project) a project initialization, which comprises of updating project's classpath and (accordingly to settings in plug-in's preferences) coping all necessary libraries. New files are compiled and you are ready to communicate with the Web Service. For meaning of generated files please refer Axis WSDL2Java documentation.

Lavadora keeps track of all generated files and packages. You can safely move, rename and delete them.

Generated Web Service client

Each client has associated WSDL of its Web Service. You  can browse its structure and edit it. After saving changes will be reflected in the structure.

Web Service references

You can add a new web reference while creating new Web Service client, or you can do it through the context menu of the plug-in's view. Second option gives you a possibility to explicitly supply an URL address of service's WSDL document or to look for it in one of defined UDDI registries:

New Web reference

When searching for a web service in UDDI registry you can start by looking for a business, which hopefully supplies the service you're interested in, published service interface (tModel) or the service itself. In each case you can use the following search criteria to narrow a number of returned results:
  • beginning of the name
  • classification code in one of (currently two - NAICS97 and NAICS02) classification systems
You can additionally bound number of returned search results (type 0 for unlimited amount). In order not to search for code descriptions you can choose one from the code tree:

Classification codes tree


Finding your way through returned results set is described in the next section. After successful creation of web reference you can browse a logical structure of a cached copy of your service's WSDL document and if you want to, copy this file into an arbitrary location in the workspace. You do this by using the context menu of respecting element of the plug-in's view.


UDDI registries

All information needed to access a particular UDDI registry, such as URL addresses for inquiry of and publishing in UDDI registries is grouped in a single graphical  representation of such registry - a reference to this registry. Below you have a new UDDI registry addition dialog.

Creating new UDDI registry reference

You don't have to specify all the data, but a address for inquiry and an arbitrary name is required. When you create a particular registry reference to be able to publish in it you need to have an account, given by the provider of this registry - these are the values to be entered in the "User name" and "Password" fields.

After creation of UDDI registry reference, if you have provided publishing information you are asked if you wish Lavadora to download any existing in this registry data published through this account some time earlier. If you decide not to do it you can synchronize Lavadora's data with the registry at any moment in the future.

All functionality regarding UDDI registries is now accessible, as usual through its context menus:

UDDI registry context menu

When you have
created a reference to a registry you can browse the data published in it. To do so, use its context menu or select it when searching for WSDL document, while you are creating a Web Service client or a new web reference.

Search results are presented in a form of a tree. The structure of this tree tries to closely mirror structure and relations between various notions existing in UDDI registries. For more information refer to UDDI data structure and UDDI API specifications.

UDDI registry search results dialog

Many elements which are present in registries have a description(s) associated with them. You can see it
in the text field on the right after selecting a particular element in the tree control. There is also a category bag and/or identifier bag (sets of key-valued entries) associated with some services and businesses. After selecting them in the tree control you can see all the data in the table on the right.

When searching for WSDL document URL you have to expand the tree until you find a URL address hopefully pointing to WSDL description, then you have to expand it to see if it actualy points to a valid WSDL document. If it does, the structure of this document will appear. Then you will be able to press "Finish". Why Lavadora doesn't do any automated search? It could - why not - its quite simple, but after browsing through several UDDI registries I've noticed that they are filled with garbage. This plug-in, in its first release has an experimental nature, so you better see for your own where people place URLs to their WSDL files.

To publish information about your businesses and Web Services in UDDI registries you need an account in this registry and in case of publishing information about a Web Service you need to create the Web Service itself and to have
already published informations about your business.

To publish information about your business in the registry you simply open the business creation dialog (through the context menu of a particular UDDI registry reference).

Adding new business to UDDI registry

You have to specify at least a name of the business, and you can additionally specify for it a classification code, a classification system and some arbitrary description. When we have a business published in a registry we can think about publishing information about a Web Service, but first - its creation.

Creating your own Web Services

Creation of your own Web Services is very simple and (because of that) limited in some way. You can pick up in any project exactly one class (which doesn't mean, you can't do it many times) which will supply methods which in turn will define the interface of your Web Service. To do so you have to select a class in the Package Explorer and using the context menu (as depicted below) invoke Class-to-Web-Service Conversion Wizard.

Invoking class-to-web-service conversion wizard

The wizard allows you to:
  • select which methods of the class are to be exposed as Web Service operations
  • which project specific libraries should be included (i.e. copied to web server) during Web Service deployment
  • provide deployment specific information, such as: external URL of your web server (the URL under it's visible on the Internet), local path to a directory containing, installed on this web server Axis package (by default this would be: C:\Program Files\Java\jakarta-tomcat-5.0.19\webapps\axis), web server manager login and password
  • provide Web Service specific information (after clicking "Next" button), which in this release comprises only of a name of the Web Service and a namespace for generated WSDL service description document.
Class-To-Web-Service Conversion Wizard

Limitations include:
  • Exposure only of methods returning or having as parameters (arrays of) simple types and following, standard Java types:
    • java.lang.String
    • java.util.Calendar
    • java.math.BigDecimal
    • java.math.BigInteger
    • javax.xml.namespace.QName
  • Exposure only of methods throwing no exceptions at all or throwing a java.rmi.RemoteException
Those limitations are introduced in order to provide users with ease of use and will be removed in next releases. There's also currently no way to deploy your Web Service to a remote web server (unless you do it by hand) or to a web server other than Tomcat 5.0, but this is the first release after all...

After clicking "Finish" button the source code of the class is corrected (there's added implements statement for java.rmi.Remote interface and for each selected method it is added a throws statement for java.rmi.remoteException. You have to do nothing more - your Web Service is ready for publishing and deployment. There's also a new position in the Lavadora's view, containing basic information about your new Web Service - the implementation class, its exposed methods and URL address for contacting it. You can see it at the picture below. Note that there's no restriction about having in the same project a Web Service interface class and an arbitrary number of clients of any Web Services.

New Web Service

You deploy your Web Service to and undeploy from a web server using a context menu of the element representing Web Service information. During deployment all project classes and all selected earlier libraries are copied into appropriate folders in the Axis directory tree and the Axis Admin Service is contacted to register the new Web Service.

You can now see in your browser a WSDL document describing your new, deployed Web Service. Its URL address can be copied to the clipboard (option in context menu) for pasting it in a browser, or in any other place - you can for instance add a new web reference supplying it in the New Web Reference Wizard or create a client of this Web Service - as described in previous sections.

Publishing of information in UDDI registry about thus created Web Service cannot be simpler: you have to open a dialog window for publishing a Web Service (context menu of selected Web Service element), select UDDI registry, select business which will from now on be the official provider of this Web Service, add some description and click OK.

Publishing new Web Service

That's all. This way of dealing with Web Services is the aim of the Lavadora Project. To be able to present it I had to make some limitations and I hope to remove them in the near future.

Plug-in preferences

The last part of this tutorial is the explanation of the meaning of plug-ins preferences. They are accessible through the standard Workbench's preferences dialog (Window/Preferences). There is a position named "Web Services":

Preferences

You can specify default path to axis and default web server URL to save typing, each time you create new Web Service. You can also specify how all projects should be initialized - by copying all required libraries to specified subfolder in the directory containing a project or just by setting a project's classpath to some external library locations (you need to specify all or none of them).


Quick links
SourceForge.net Logo