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:
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:
There are three groups of information presented in the view:
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:
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.
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:
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:UDDI registries
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.
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.
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:
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.
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).
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.
The wizard allows you to:
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.
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.
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.
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":
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).