Before you start
This section describes what to expect from this tutorial and how to get the most out of it.
A brief introduction
Those of you who have been following IBM's support for the Web Services Distributed Management (WSDM) standard through delivery of WSDM run time and tooling are probably aware of the Autonomic Integrated Development Environment (AIDE) made available on IBM alphaWorks earlier this year. As a logical next step in the support of an open standard like WSDM, the run-time code was contributed to the Apache Muse project, and keeping in step, a new revamped version of the tooling for WSDM is now available as part of the Eclipse TPTP (Test and Performance Tools Platform). While the run time provides a stable reference implementation of the WSDM specifications and a programming model for building WSDM endpoints, the tooling lets you visually model a WSDM interface in an IDE, generate the endpoint code that follows the Muse programming model, and also test a sample deployment of the generated endpoint with your custom implementation added to it.
The tooling is available as part of the Build to Manage download in the Eclipse TPTP project. It is manifested as a set of plug-ins that provide editors for various WSDM-related constructs like capabilities, managed resource types, and so on, and Muse-specific artifacts like a run-time deployment descriptor. Also available in TPTP is a Managed Agent Explorer that lets you test the endpoints built using the tooling in addition to introspecting existing endpoints.
This saga started with the tutorial "Create a WSDM interface for an HTTP server using Apache Muse," which demonstrated how to use Apache Muse to create a WSDM-compliant interface for a manageable resource. That prompted the tutorial "Create a WSDM endpoint using the Eclipse TPTP Build to Manage tooling" so you could see an alternate way to build a WSDM interface for the Apache HTTP server without having to worry about Web services artifacts like Web Service Definition Language (WSDL) and schema files. There's also an article ("Why open source for the WSDM open standard?") to detail the tooling, explain why an interface should be built with open source, and show how you can affect the development of the run time and the tooling. Although not offered as a package, these resources fit nicely together to provide a more complete view of WSDM tooling.
About this tutorial
This tutorial uses a hands-on approach to help you find, install, and configure Apache Muse, the stable release of the WSDM tooling in Eclipse TPTP 4.3, and the latest development builds of WSDM Tooling in TPTP 4.4. After all, you can pursue the other tutorials without them. This is meant to be an introductory tutorial; for more on effortlessly building WSDM endpoints, try the other tutorials mentioned (and keep an eye out for upcoming tutorials on developerWorks).
This tutorial is divided into three major sections:
- Obtaining and installing Apache Muse
- Obtaining and installing the WSDM tooling in Eclipse TPTP 4.3 (the stable release)
- Obtaining and installing the tooling development builds in TPTP 4.4
This tutorial is for developers who have an understanding of the installation process for software. Because you will be using this understanding as a basis for other tutorials, it is also a good idea to have a high level of understanding of WSDM concepts and a good grasp of Web services in general. The intent of the tooling is to hide the complexities of Web services development and Apache Muse artifacts while advocating a standard programming model. But, familiarity with Web services will help you follow the tasks closely. Java development experience using an IDE such as Eclipse is also greatly helpful.
Prerequisites for Eclipse TPTP can be found at http://www.eclipse.org/tptp/home/downloads/drops/TPTP-4.3.0-200611160100C.html#requirements.
Getting and installing the Apache Muse run time
If you are installing the Eclipse tooling, you can skip to the next section, because when you install the tooling you will install the Apache Muse run time as part of that installation. Therefore, when you build endpoints using the tooling, the Apache Muse run time is added as part of the deployable package that the tooling generates.
However, if you want to use the Apache Muse run time without any Eclipse tooling support, you can get it individually and use it. The Apache Muse run time is available in both source and binary form at the Apache Muse Web site http://ws.apache.org/muse.
To get and install the Apache Muse run time:
- Download the latest version of Apache Muse in binary form from http://www.apache.org/dist/ws/muse/2.1.0/bin/muse-2.1.0-bin.zip.
- Extract it into a folder; for example, c:\muse. This folder now looks like the one shown in Figure 1.
Figure 1. Extracted Apache Muse binary
- The bin folder contains the scripts that you will use for merging WSDL files that you create (wsdlmerge) and command-line tooling for creating skeletal Java™ code and Muse descriptor files from the merged WSDL (wsdl2java). The scripts are available for both Windows® and Linux® platforms.
- Some of the files required by Apache Muse need to be downloaded from other servers as they are not packaged with the Apache Muse download. Within the bin folder, there is an update_install.bat (or .sh) script. Open a command prompt and run this (and of course make sure you have an active Internet connection). You will see the following on the console:
Figure 2. The update_install script
This script also creates a new lib folder that contains the following:
Figure 3. What's in the lib directory
There is a common folder that contains JAR files that Muse needs for standard functions like parsing WSDL and other XML files. The other folders contain the JAR files necessary for endpoints generated from the command-line tooling to be deployed on the various containers that Muse endpoints can run in, such as Java Platform, Enterprise Edition (Java EE) application servers and OSGi containers.
- The installation in now complete. You can build new endpoints by running the tools under the bin folder with WSDL files that you may have already created using other tools. You can also take the WSDL files produced by the Eclipse TPTP tooling when generating a new endpoint project and use them as input to the wsdl2java command-line tool found in the bin folder. You can also try out the existing samples by first building them and then taking the output and deploying it either on an OSGi container like Eclipse Equinox, a Java EE application server like Apache Tomcat, or the WebSphere® Application Server (see Resources). The samples are organized under the container they are meant to be run on.
Figure 4. What's in the samples directory
You can edit the build.xml file for each of the samples to provide the correct values for each of the variables specified at the top of the build file.
- To build the samples you will need to use Apache Ant. After you have Apache Ant installed and added to your system path, you can go to each of the samples folder (where the build.xml file is located; the child nodes are shown in Figure 4) and run ant from there. You can also use the run target (by doing an ant run) for the samples under eclipse-osgi to build and run the sample. For the Java EE samples, the default action is to build a WAR file that you can then deploy manually into a Java EE application server.
For more information on the samples, see the Muse documentation (see in Resources for a link).
Installing the WSDM Tooling in Eclipse TPTP 4.3
The latest stable version of the WSDM tooling can be found in Eclipse TPTP 4.3 that was released in December 2006. Installation of the WSDM tooling is currently a multistep process; however, efforts are underway to reduce the number of steps involved. You can either install the various packages manually or use the update manager approach. In either case, these are the high-level packages to be installed.
- Eclipse 3.2 (Callisto) with prerequisites required for TPTP
- TPTP 4.3 (Test and Performance Tools Platform) run time
- WTP 1.5 (Web Tools Platform) and its prerequisites
- WSDM Tooling and Managed Agent Explorer extensions plug-ins
- Apache Muse 2.0 run time
Installation of Eclipse 3.2 must be done manually in any case. Because the update manager approach is the easiest, I will follow that.
- Download the Eclipse Callisto distribution from http://www.eclipse.org/callisto/plugin-dev.php. The actual download is at http://download.eclipse.org/eclipse/downloads/drops/R-3.2.1-200609210945/index.php. Select the correct download for your platform (Windows, Linux, and so on). For this example, I will use Windows. Assume you install this by extracting the downloaded ZIP file at c:\wsdm-tooling. This folder will contain the eclipse subfolder.
- Start Eclipse and choose any workspace.
Start the Eclipse Update Manager by navigating to Help > Software Updates > Find and Install:
Figure 5. Starting the Eclipse Update Manager
- Select the Search for new features to install option and click Next.
Figure 6. Looking for new features
- Choose the Callisto Discovery Site and click Finish.
Figure 7. Choosing Callisto
In the window shown in Figure 8, choose a mirror site (the first one is usually fine) and click OK.
Figure 8. Choose your mirror
- In the Search Results dialog box, you can now choose the various features you want to install.
Figure 9. Installing features
Select the following:
- Choose Batik PDF 1.6.0..., Batik 1.6.0..., Eclipse Project Equinox bundle feature 3.2.1... from under Enabling Features.
- Select Graphical Editors and Frameworks > Graphical Editor Framework 3.2.1....
- Select Eclipse Modeling Framework (EMF) 2.2.1..., XSD Schema Infoset Model 2.2.1..., EMF Service Data Objects (SDO) 2.2.0... and Java EMF Model 1.2.1... from under Models and Model Development.
- Select everything from under Test and Performance except TPTP Reporting for BIRT 4.2.0... (which appears twice in this subcategory, first and last in the subcategory). Note that you are installing the 4.2.2 version -- you will update this to 4.3 later on.
- Finally pick everything: Web Standard Tools (WST) Project 1.5.1... and Java EE Standard Tools (JST) Project 1.5.1 from under Web and Java EE Development.
Finally click Next. Choose to accept the license terms in the following window (you can click on each feature shown on the list in the left to see the individual licenses).
All the features to be downloaded and installed are shown in the following window. You may choose to install different features in different locations on the disk so that you can individually modify each of them in the future. But for this example, I will use the default install location.
Figure 10. Checklist for installable features
On clicking Finish, the Eclipse update manager downloads the required plug-ins and features. This may take some time, so be patient. Select Install All in the window that appears after the packages are downloaded.
Figure 11. Confirming the installable features
This installs all the features. When you are presented with the option to restart the workbench, select Yes.
Figure 12. Restart the workbench
Now go back to update manager. You will now install the latest stable release of TPTP and the WSDM tooling, which is part of the Build to Manage Tech Preview component. Choose Search for new features and click Next.
Figure 13. Installing the latest stable release of TPTP
Choose Test and Performance Tools Platform (TPTP) Updates. This option was added when you installed the earlier version of TPTP.
Now you need to add the update site for the TPTP tech previews. Click New Remote Site.
Figure 14. Adding update site for the TPTP tech previews
TPTP Tech Previews Update Sitefor Name, provide http://download.eclipse.org/tptp/updates/techpreview for the URL, and click OK.
Figure 15. Providing name and URL
The site you just added is shown in the list of sites to include in the search and is also chosen by default. Click Finish.
Figure 16. And there's your site
Choose one of the mirrors (typically the first one) and click OK. You will have to do this once for the TPTP updates and once for the TPTP Tech previews updates.
Figure 17. Selecting two more mirrors
Eclipse update manager will down the available updates and show you a window like the one shown in Figure 18. Open Test and Performance Tools Platform (TPTP) updates and you will see TPTP 4.3.0 Features. Open that node and choose everything underneath it except the TPTP Reporting with BIRT 4.3.0. Then click Next.
Figure 18. Don't choose BIRT
Then open up the TPTP Tech Previews Update Site and open the Build-to-Manage Toolkit node. Choose Apache Muse 2.0.0..., Managed Agent WSDM 4.3.0..., and Tooling for Web Services Distributed Management (WSDM) 4.3.0... under this. You shouldn't see any errors; if you do see errors, click on the Select Required button. If the errors still don't go away, then double check if you followed all the steps above. When everything looks fine, click Next.
Figure 19. Picking the correct features
- Choose to accept the license in the next wizard page and click Next. In the following wizard page, you can leave use the default installation location and click Finish. The updates will be downloaded. Choose to Install All. After the downloaded updates have been installed, restart the workbench when presented with the option. You will probably see some errors on startup in the Error log. You will fix those in the next step.
- The last step is to install the Apache Muse run time by copying the Apache Muse JAR files into the respective plug-ins that have been installed. Due to legal reasons, the Apache Muse JAR files are not shipped with the tooling, even though the plug-ins to hold those JAR files are. The Apache Muse project provides the 2.0 release JAR files organized in the same plug-in structure as a downloadable ZIP file at http://ws.apache.org/muse/update/btm-muse-2.0-download.zip. Download this file and then extract it into the c:\wsdm-tooling folder. This adds the respective JAR files into the Apache Muse plug-ins in the c:\wsdm-tooling\eclipse\ plug-ins folder.
Also in the TPTP 4.3 tech preview release of the WSDM tooling, help on using the tooling is available within the Eclipse Workbench. In the installed workbench, you can choose Help > Help Contents to bring up the list of help topics. The Using the Managed Agent Explorer section has topics that deal with the Managed Agent Explorer and the Modeling and generation of Web services Distributed Management Endpoints deals with using the WSDM tooling.
However, the topics under the latter section are missing their images. To add them, first download this (file), which contains the images and extract into a temporary location, say c:\temp.
Browse to the plug-ins folder in the location where you installed the WSDM tooling (for example, c:\wsdm-tooling\eclipse\plug-ins) and find the org.eclipse.tptp.wsdm.tooling.doc.user_4.3.0.v200610250100.jar plug-in JAR file.
Figure 20. Adding the images to the help files
Open with an Archival utility. Drag and drop the images folder from c:\temp into the archive. Make sure that you have configured the archival utility to not retain full path names when adding new files to the archive.
Now restart the Eclipse workbench with the
-cleancommand-line option. If everything has been installed properly, you should see no new errors in the Error Log. You can also use the testing instructions in this article (http://www.eclipse.org/tptp/monitoring/documents/tutorials/tptp_wsdm_setup_4.3.html#4).
Now that you have installed the tooling successfully, you can start using it. See Resources for links to other articles on developerWorks that show you how to use the tooling.
Installing the latest development builds in TPTP 4.4
The WSDM tooling in TPTP 4.4 is currently under development with a planned general release by end of June 2007, together with the Eclipse Europa release (http://wiki.eclipse.org/index.php/Europa_Simultaneous_Release). At the time of this tutorial, a number of bugs in the WSDM tooling in 4.3 have been fixed and some new features have been added or are currently being worked on. If you would like to take advantage of these and are willing to work with development builds that may not be fully tested, you can use the instructions in this section to get and use the TPTP 4.4 builds.
These instructions are different from the instructions in the previous section because you will use the Eclipse Extension Locations mechanism to separate the various components of the installation so that components can be updated individually.
Eclipse lets you create extension locations where you can separately install individual features and components and then link them to your Eclipse installation. You will create separate extension locations for the prerequisites required by the TPTP run time, the TPTP run time itself, prerequisites that are specific to the WSDM tooling, and finally for the WSDM tooling itself.
The development builds of TPTP 4.4 are available at http://www.eclipse.org/tptp/home/downloads/?ver=4.4.0. If candidate builds are available, you can pick them; otherwise, click on the link to the latest development build. If you want the latest and the greatest, always go for the development builds!
Figure 21. Choosing your development builds
An all-in-one build that includes the Eclipse SDK, the prerequisites, and TPTP run time is available. If you get this, you only need to add Web Tools Platform (WTP), the WSDM tooling component, and the Apache Muse run time. However, this download weighs in at around 150MB. This means that whenever you need to update your installation to the latest development build, you will need to perform this 150MB download. If this is not a problem, get this build and you can skip steps 3 through 5, 7, and 9.
Figure 22. All-in-one pack, big but convenient
- In this tutorial, I will take the approach of installing each of the components separately. This way, when you need to do updates you can update the components individually. You do need to check on a regular basis or when updating one component if the TPTP download instructs you to get a newer version of some of the prerequisite components.
Following are the prerequisites you need from the TPTP download page:
Figure 23. TPTP download prerequisites
While Eclipse Web Tools Platform and Graphics Editor Framework are marked as optional, they are required for the WSDM tooling. The only thing you don't need in the above list is Java EMF Model.
- First, go to the Eclipse SDK 3.3 link, download the package for your platform, and extract it into, say, c:\wsdm-tooling-dev.
Download the extensions.zip file, also available in Resources. Unzip this into the Eclipse installation folder you used before (c:\wsdm-tooling-dev). This creates the following folders:
Figure 24. Building extension folders
Within each of the extension folders that were created, there will be an Eclipse folder containing an .eclipsextension file. This file describes the contents of the extension location and is required by Eclipse to recognize the extension location and add a link to it so that the plug-ins installed in these extension locations are available within the Eclipse workbench. For example, within the ext-location-emf, the eclipse folder contains a .eclipseextension file with these contents:
id=org.eclipse.emf name=EMF version=2.2.2
- Now you will download and extract each of the individual components. Go to the Equinox download Web site, and then navigate the latest 3.3 stream integration build and download the smaller package (the non-SDK package). Extract it into c:\wsdm-tooling-dev\ext-location-equinox. In general, in doing any of this, respond Yes for any windows that ask about overwriting existing files.
- Click on the link to the Eclipse Modeling Framework SDK 2.2.2. It is important to pick the 2.2.2 version. Download the ZIP file and extract it into c:\wsdm-tooling-dev\ext-location-emf.
Click on the links to Eclipse Web Tools Platform (WTP) 2.0 to download that first (this is the non-SDK package and will suffice for your needs). You will also select links to download the prerequisites for WTP 2.0. Specifically, you need to download the Data Tools Platform (DTP) driver and the GEF driver . Download these ZIP files and save them in some temporary location.
Figure 25. Download the Web Tools Platform ZIP
Extract all the ZIP files downloaded for WTP into c:\wsdm-tooling-dev\ext-location-wtp.
At the top of the TPTP download page, just below the all-in-one download links, you will link to download all the TPTP plug-ins. Download the run time plug-ins and extract them into the c:\wsdm-tooling-dev\ext-location-tptp folder.
Figure 26. Download all the TPTP plug-ins
Scrolling down on the same page, under the Technology Previews section, you will find a link to download the WSDM tooling plug-ins. Download them and extract the ZIP file into the c:\wsdm-tooling-dev\ext-location-wsdm folder.
Figure 27. Download the WSDM tooling plug-ins
Now you need to add the Apache Muse 2.0 run time to the WSDM plug-ins you just installed. Note that unlike in 4.3, you cannot simply extract the package you download from the Apache Muse Web site because the plug-in names have changed slightly between the 4.3 release and current/future 4.4 builds.
First download the package of Apache Muse JAR files from http://ws.apache.org/muse/update/btm-muse-2.0-download.zip.
In Resources, you can download the Muse20Copier.jar, which contains a simple Java program to analyze the downloaded ZIP file and copy the JAR files into the correct plug-in locations within your WSDM tooling installation. You can run this program from the command prompt providing the complete location of the downloaded ZIP file as the first argument and the installation location of your WSDM tooling component as the second argument. Assuming you download the file to c:\temp and followed Step 9 to install the WSDM tooling plug-ins, you'd run the following on the command line from the folder where Muse20Copier.jar is present:
java -jar Muse20Copier.jar c:\temp\btm-muse-2.0-download.zip c:\wsdm-tooling-dev\ext-location-wsdm
This copies the JAR files and you should see the copied JAR files in the console.
Now start up the Eclipse workbench and choose Help > Software Updates > Manage Configuration.
Figure 28. Managing configurations
In the resulting Product Configuration window, click Add an extension location.
Figure 29. Adding an extension location
You need to add each of the extension locations one by one. First, let's add the extension location for Equinox. Browse to the extension location folder for Equinox and click OK.
Figure 30. Adding the Equinox extension location
Do not restart the workbench at this point. Add all the extension locations under wsdm-tooling-dev and after adding the last one, when provided with the option to restart the workbench, click Yes. When one extension location has been added, you may have to click on Eclipse SDK node to bring up the link to add an extension location.
- That completes the installation. Upon restarting the workbench, if everything has been installed properly, you should see no new errors in the Error Log. You can also use the testing instructions in this article (http://www.eclipse.org/tptp/monitoring/documents/tutorials/tptp_wsdm_setup_4.3.html#4).
Keep a note of the actual version of the various components you are installing -- preferably the actual file names. You could make a table where each extension location is a single row with the corresponding downloaded file names in the next column; that way, when there is a new development build available (usually a daily occurrence), you can compare and see if you need to update any of the extension locations you've used. If indeed you need to update, while it may seem tempting to just overwrite the contents of an extension location, it is safer to delete all files within the eclipse folder of the extension location except for the .eclipseextension file before extracting the new download.
In the future, if you need to update a particular component, you can just modify the files in that extension location. Typically, you will delete the contents of the plug-ins and features folders and replace them with the newly downloaded content. Make sure, however, that you do not delete the .eclipseextension file and that after updating the file, you start Eclipse with the
-clean command-line option.
A word of caution -- these are development builds and are prone to have some bugs. You can always bring up installation and usage issues on the Eclipse TPTP mailing lists and open bugs and requests for new features (see "Why open source for the WSDM open standard?" in the Resources section to show you how).
Now you have the tools to build a WSDM interface for the ubiquitous Apache HTTP server, whether you use a hand-coded method or use the tooling integrated into Eclipse to model, generate, and test WSDM interfaces. You can now go on to gain a broader understanding of the nuances of working with Web Services Distributed Management.
- "Create a WSDM endpoint using the Eclipse TPTP Build to Manage tooling" (developerWorks, February 2007): This companion tutorial shows you how to build a WSDM interface for the ubiquitous Apache HTTP server without having to worry about Web services artifacts like WSDL and schema files.
- "Why open source for the WSDM open standard?" (developerWorks, February 2007): This article gives you an overview of the Apache Muse and Eclipse TPTP run time and tooling for WSDM, a description of the motivation for building this in open source, and an explanation of how you can influence both the development of the run time and the tooling.
- "Create a WSDM interface for an HTTP server using Apache Muse" (developerWorks, November 2006): In this tutorial get a demonstration of how you can use Apache Muse to create a WSDM-compliant interface for a manageable resource.
- "Keep your WSDM endpoints trim with Apache Muse" (developerWorks, December 2006): This tutorial shows you how to use Apache Muse 2.0 to create WSDM interfaces for resource types that have hundreds or thousands of instances.
- OASIS Web Services Distributed Management (WSDM) Technical Committee: Keep current with the latest announcements.
Get products and technologies
- Eclipse TPTP: Grab the prerequisites for Eclipse TPTP.
- http://ws.apache.org/muse: The Apache Muse run time is available in both source and binary form at the Apache Muse Web site.
- Eclipse Equinox: Eclipse Equinox is an implementation of the OSGi R4 core framework specification, a set of bundles that implement various optional OSGi services and other infrastructure for running OSGi-based systems.
- Apache Tomcat: Apache Tomcat is the servlet container used in the official Reference Implementation for the Java Servlet and JavaServer Pages technologies.
- WebSphere Application Server 6.1: This is a Java 2 Enterprise Edition and Web services technology-based application platform; besides the regular version, you can download the Express version (a ready-to-go package including a Java EE app server, sample applications, development tools, and wizards) or the Community Edition (a free, lightweight version).
- Apache Ant: Apache Ant is a Java-based build tool, kind of like Make, but without Make's wrinkles.
- Build to Manage toolkits forum: You can discuss the use of the Build to Manage toolkits in Eclipse TPTP with experts and other practitioners in this forum.
- Eclipse tooling package support forum: This forum lets you share concerns and questions about downloading, installing, or using the Eclipse tooling package.
Dig deeper into Tivoli (service management) on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.