Create a WSDM endpoint using Build to Manage tooling from the Eclipse TPTP project

An easier, IDE driven way to build a WSDM interface that uses the Apache Muse run time

Build a Web Services Distributed Management (WSDM) interface for the Apache HTTP server without having to worry about Web services artifacts like Web Services Description Language (WSDL) and schema files, using refreshed tooling for WSDM in the Eclipse open source project. In a previous tutorial, you learned how to accomplish this task by hand coding the artifacts required by the Apache Muse run time and using the command-line utilities in Muse. In this tutorial, you do the same but in a faster, easier way. By the end of this tutorial, you will be accomplished at using the tooling integrated into Eclipse to model, generate, and test WSDM interfaces.

Share:

Balan Subramanian (bsubram@us.ibm.com), Advisory software engineer, IBM

Photo of Balan SubramanianBalan leads the Web Services Distributed Management (WSDM) development team in the Tivoli Autonomic Computing group at IBM in Research Triangle Park, delivering run times and tooling for WSDM. His team delivers the open source Apache Muse WSDM run time and the tooling for WSDM in the Eclipse TPTP project to which he is a committer. Balan earned a Master's degree in Computer Science from George Mason University and has been with IBM since 2002. He is interested in Web services, grid computing, autonomic computing, social networking and robotics. He has published several articles and filed multiple patent applications, particularly in the areas of problem determination, autonomic computing and Web services.



13 February 2007

Before you start

Learn 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). 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 Test and Performance Tools Platform (TPTP). While the runtime 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 Eclipse TPTP 4.3. 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 runtime 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.

About this tutorial

This tutorial uses a hands-on approach to help you build WSDM interfaces for existing applications and IT resources. Rather than delve into the intricate details of the artifacts that define an endpoint, this tutorial takes a task-based approach that a developer or architect with a high-level knowledge of WSDM can quickly grasp. Advanced WSDM developers, who are well aware of the complex artifacts required for creating anything more than a simple endpoint, will appreciate the simplicity and quick turnaround that the tooling provides. Through a number of screen shots and code snippets, this tutorial gets you up and running with WSDM endpoint development in no time.

Tasks that you should perform are typically in separate sections and the section title carries a Task prefix. Each task contains a discrete set of steps. A number of screenshots are included in the tutorial. Typically, only portions of the screen are shown (to save space). However, each screenshot is accompanied sometimes by a link to the full screenshot where it is useful to see the entire context in which a user action is taken.

I use the "Create a WSDM interface for an HTTP server using Apache Muse" tutorial as a reference throughout this tutorial (when I say the "other tutorial," this is what I am referring to). It will help you compare and understand how to use the tooling for WSDM to generate WSDM endpoints that use the Apache Muse run time. The artifacts generated in this tutorial will look very similar to the artifacts that you create by hand in "the other tutorial."

This tutorial is meant to be an introductory tutorial on effortlessly building WSDM endpoints. As such, a number of advanced features are skipped and not even identified in the interest of time and simplicity. These features will be covered in future tutorials that you can expect to see very soon on your favorite destination for leading-edge technical articles, developerWorks!

Prerequisites

This tutorial is for developers who have a high level of understanding of the Web Services Distributed Management 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. However, familiarity with Web services will help you follow the tasks closely. Java™ programming experience using an IDE such as Eclipse is also helpful.

System requirements

Much of the development in this tutorial is done in the Eclipse IDE with the Test and Performance Tools Platform (TPTP) plug-ins installed. The first section of this tutorial explains how to set up the Eclipse TPTP installation and the tooling for WSDM on top of it. Prerequisites for Eclipse TPTP can be found at http://www.eclipse.org/tptp/home/downloads/.

To run the endpoint generated in this tutorial and see it in action as a management interface to Apache Tomcat, you must have Apache Tomcat installed on your machine. Apache Tomcat 5.0 is recommended because you can use the same 1.4-level JDK, which is the supported Java runtime for Eclipse TPTP.


Setting up the development environment

The first step in setting up the tooling is retrieving the necessary components from the TPTP Web site. The instructions on the TPTP Web site cover the installation of all TPTP components in full detail. This section covers installing only the pieces that you need for WSDM endpoint development in Eclipse.

The basic prerequisite is Eclipse 3.2. I assume that you have Eclipse 3.2 installed for your platform. If not, you can find it at http://www.eclipse.org/downloads/. You can then install the other prerequisites from the TPTP Web site link as well as all the TPTP components.

As an alternative, you can download the Eclipse TPTP all-in-one download at http://www.eclipse.org/tptp/home/downloads/. In either case, you will have to install Web Tools Platform (WTP) and its prerequisites (GEF and JEM -- links for which are found on the same download page). Finally, you need to install the WSDM tooling plugins

The tooling for WSDM is available as part of the Build-to-Manage package at http://www.eclipse.org/tptp/monitoring/resources/download/btm/index.html. You need to download only the Eclipse Plugins under the WSDM section. An installation guide is also available at this site. To make things simpler, I only outline the basic steps here. Other tutorials on the developerWorks Web site detail the installation of both stable and development releases, along with some strategies for componentizing the installation.

Your next step is to install the WSDM tooling plug-ins. Download the WSDM tooling plug-ins package and extract this ZIP file into the TPTP installation folder -- the folder that contains the eclipse folder.

The WSDM tooling plug-ins use and package the Apache Muse run time into the endpoints built using them, so the Apache Muse run time must be added to the TPTP installation. Download this ZIP file from Apache Muse and extract it into the TPTP installation folder (which contains the eclipse folder).

This completes the installation. If you had started Eclipse in the middle of any of the preceding steps, start it again from a command line with the -clean option. This refreshes the configuration and enables Eclipse to pick up the newly installed plug-ins.


Modeling a WSDM interface, creating a manageable resource type model

A WSDM interface is manifested as a WSDM endpoint that talks WSDM on one side and communicates with the actual resource on the other. The actual deployment and life cycle may vary -- the endpoint may be hosted external to the actual resource or co-deployed and it may have a different lifetime than the resource itself (it may exist and remain online while the actual resource it implements may be stopped).

Creation of a WSDM interface first requires that a manageable resource type be defined. This is a typical top-down approach where you first describe the general characteristics of a resource and then define the various capabilities it provides. If one such capability is not part of the WSDM specifications, you define that capability as well. Then you can generate the actual WSDM interface from this manageability model.

Task: Create a WSDM project

  1. Start Eclipse and open the Java development perspective. This can be accomplished by choosing Window > Open Perspective > Java.
  2. Now create a project to hold the artifacts you will generate with the tooling. This enables the tooling to adequately validate the files that are being generated. Go to File > New > Project. In the resulting window, scroll down to Tooling for Web Services Distributed Management and choose Manageability Endpoint Project.
    Figure 1. Create a new maneability endpoint project
    Create a new maneability endpoint project

    You'll then provide a name for the project. For this tutorial, use ApacheWSDMModels. When you press Finish, the new project is created and the necessary builders and validators are assigned to it in the background.

Next you create a manageable resource type definition using the Manageable Resource Type editor. A manageable resource type serves as an aggregating model of capabilities either defined in the WSDM specifications or defined by the user within the same workspace. In the former case, the capability definitions are built into the tooling. You can think of a resource type definition as an aggregation of capabilities similar to how a Java class (an abstract one is more appropriate for this analogy) collectively inherits multiple interfaces.

Task: Create a manageable endpoint type definition

  1. Right click on the newly added project and choose New > Other. In the resulting window choose New WSDM Manageable Endpoint Type under Tooling for Web Services Distributed Management.
    Figure 2. Create a new WSDM manageable resource type file
    Create a new WSDM manageable resource type file
  2. Click Next. This opens the Manageable Endpoint Type wizard. Provide a name for the endpoint such as HttpServer. The wizard automatically prefills some of the other fields. You can override the namespace field: use http://www.example.com/http-server for this tutorial.
    Figure 3. Create a manageable endpoing namespace
    Create a manageable endpoing namespace
  3. As discussed previously, a manageable endpoint type is an aggregation of capabilities that provide the real function of the endpoint. Some capabilities that apply to all endpoints are prescribed by the WSDM specifications of which only two are mandatory. In the next window, you are presented with a list of capabilities classified by type of capability -- whether it is core to management or supportive, whether it is built on or user defined.

    Identity and ManageabilityCharacteristics are chosen by default and cannot be unselected as they are required of all WSDM endpoints. Under User Defined Capabilities, you see the various capabilities that do not come built into the tooling and which the user has defined in the same workspace within other projects. Because you started fresh you do not see any capabilities listed under that section. Resource Property and Resource Lifetime capabilities are in their own section as they are typically chosen as a set of capabilities.

    In addition to the mandatory capabilities, the HTTP Server endpoint requires some predefined capabilities. Capabilities provide both properties and operations -- the former representing the resource state that the resource intends to expose and the latter the management operations that can be executed on the resource. (A discussion of the properties to be exposed by the HTTP server endpoint is in the next section.) For now, you will only name the properties and the built-in capabilities that provide them:
    • ResourceId provided by Identity capability (chosen by default; mandatory)
    • ManageabilityCharacteristics provided by capability of same name (chosen by default; mandatory)
    • Caption, Description, Version provided by Description capability
    • OperationalStatus provided by capability of same name
    Choose the above capabilities and continue to the next window in the wizard. There are two more capabilities that you need for your endpoint but I'll skip them for now (this gives me an excuse to try some more screens in the tooling later). As you may appreciate, the tooling relieves you from having to know the intricate details of capabilities defined in the WSDM spec (though you can look at them in detail in the tooling if you so desire).
    Figure 4. Select the capabilities for the manageable endpoint type definition
    Select the capabilities for the manageable endpoint type definition
  4. Click Finish. This opens the Manageable Endpoint Type editor. This editor shows the current capabilities that this endpoint type will provide and lets you add more.
    Figure 5. Manageable Endpoint Type editor
    Manageable Endpoint Type editor
    Also in your project, you will see a new HttpServer.mrt file. (The extension stands for Manageable Resource Type.)
  5. Click Add Capability to open a window that lets you add more predefined and user-defined capabilities as you had before. Note that capabilities that are already included in the endpoint type are not shown.

    Though you have added some of the capabilities that provide the properties you intend for the HTTP server to expose, you have not added the capabilities that provide the actual operations to work with these properties. Therefore, go ahead and add all the Resource property capabilities and resource lifetime capabilities. You can do this by choosing the root level nodes. Click OK and you see these capabilities in the manageable endpoint type definition editor. Don't forget to save your changes.
    Figure 6. Add capabilities
    Add capabilities
    You can also create new capability definitions from within this editor. To do this, use the link to the WSDM Manageable Endpoint Capability Editor under the New Custom Capability section. You will add custom capabilities in the next section.

Modeling management capabilities

In this section, I'll define the manageability capability of the Apache Tomcat server. A lot of background information about the Apache Tomcat server's configuration files and typical manageable properties can be found in the other tutorial; look at Section 1 for a description of the Apache Tomcat server files and Section 2 for an overview of possible properties that can be exposed for management.

To keep in line with that tutorial, I'll use the same properties. However, because the tooling is intended to cover these simpler scenarios without much ado, I will also add more properties and operations to spice things a bit.

Resource properties

The WSDM-defined properties the endpoint will expose are:

  • The ResourceId: Part of the WSDM MUWS (Management Using Web Services) capability, it allows identification of individual instances of the same type such as multiple tomcat instances.
  • The ManageabilityCapability: A collection of URIs of the capabilities supported by this resource.
  • The Caption, Description, and Version: User-readable strings that help management applications that interact with WSDM resources show relevant information in their respective consoles about the resources being introspected/worked on.
  • The OperationalStatus: An indication of whether the resource is "up and running," This is one of the properties that typically changes during the lifetime of the resource. In comparison, the previous three properties typically will stay static after the resource (and its endpoint) is initialized.

Also, I will also include some generic HTTP server properties that are typically available across multiple HTTP servers, such as:

  • ThreadsPerChild: Number of request handling threads per server process. Default is 250.
  • Listen: Port number the server is listening on. Default is 80.
  • ServerName: Full host name and port that the server uses to identify itself.

These properties are exposed through the http://www.example.com/http-server namespace.

Task: Creating a capability definition

  1. Either right click on the project or choose the project that you had created (ApacheWSDMModels) and click New > Other. Under Tooling for Web Services Distributed Management, choose New WSDM Manageability Endpoint Capability.
    Figure 7. Create a new WSDM manageability endpoint capability
    Create a new WSDM manageability endpoint capability
  2. Enter HttpServer as the capability name and edit the Namespace to be http://www.example.com/HttpServer. Change the prefix to http. Click Finish.
    Figure 8. Create new custom capability
    Create new custom capability
  3. A new capability definition is created and the capability editor is displayed. Each capability definition is represented by three files of the same name - an .mcap file which is actually a WSDL fragment that contains the operations, a .xsd file which is a schema that contains the property definitions and a .rmd file that contains metadata about the properties. You can see these three files under the project in the Navigator view.
    Figure 9. Capability editor
    Capability editor

The capability editor provides separate tabs for defining exposed properties, available manageability operations, and topic definitions to which a resource providing this capability will publish events to.

Task: Declaring exposed properties

  1. In the capability editor, switch to the Properties tab. The left side of the editor shows currently exposed properties and the right side the metadata for each property. Consequently, the selections on the right side change according to the property chosen on the left. Click Add.
    Figure 10. Capability editor Properties tab
    Capability editor Properties tab
  2. In the window that opens, add a ThreadsPerChild property. I'd suggest using primitive values whenever possible; if you use object types then you might experience serialization/deserialization issues that are outside the scope of this introductory article. In this manner, I will transcend slightly from the other tutorial; I'll leave the defaults for the metadata because this property will be Writable, Mutable, and Always present.
    Figure 11. Adding a ThreadsPerChild property
    Adding a ThreadsPerChild property
  3. Similarly, I'll will add the other two properties, Listen and ServerName. The former is Writable, Mutable, and Always present. Whereas the latter is ReadOnly, Mutable, (in other words, changeable by the server) and Always Present. The former is an integer and the latter is a String.
    Figure 12. Adding Listen and ServerName properties
    Adding Listen and ServerName properties
  4. Now let's set some defaults. Choose the ThreadsPerChild property and click Edit Metadata. In the resulting window, click Add Default.
    Figure 13. Editing property definitions for ThreadsPerChild
    Editing property definitions for ThreadsPerChild
    Enter a value in the entry field that appears. As discussed previously, I will use 250. Click OK. Similarly, set default for the Listen property to 80. In the capability editor you can see the default values by expanding each property node.
    Figure 14. Setting properties
    Setting properties
  5. Save the capability definition (typically using the CTRL-S keys).

As and when you save the changes you make to the capability definition, the definition is validated. All the concerned files are validated for both syntactic and semantic validity. The results are reported in the Error Log. You can open the Error Log by clicking Window > Show View > Error Log. If this option is not available after Show View, click Other and you can find this option under PDE Runtime.

Figure 15. Show error log
Show error log

The Error Log shows all warnings and error messages associated with the definitions (both capability and resource type). At this point, there are warnings that you can ignore for now.

Figure 16. Error log
Error log

Task: Declaring operations

  1. Switch to the Operations tab in the capability definition editor. On the left you can see the set of operations that a resource providing this capability will provide ("implement"), empty to start with. On the right you can see details of each operation including return types, parameters, and faults thrown. I will define two simple operations, start and stop, as prescribed in the other tutorial. However, to make things a little interesting, I provide a parameter to the stop operation that lets you specify a delay after which the server should be stopped. Click Add.
    Figure 17. Operations tab
    Operations tab
  2. Enter start for operation name and specify void as the return type. For this operation there are no parameters, so you will specify none. Click OK. You can see that operation has been added. Also note that the BaseFault type is automatically added. This is a fault that is thrown for any operation. At this point, other fault types are not available and no custom faults can be specified in the tooling.
    Figure 18. Add start operation
    Add start operation
  3. Similarly, you can add the stop operation. For this operation I enter a parameter named delay of type int. This represents the delay in seconds after which the server will be shut down. A specification of 0 indicates immediate shutdown.
    Figure 19. Add stop operation with delay parameter
    Add stop operation with delay parameter
  4. Save the capability definition. Make sure that there are no errors in the Error Log. This completes the definition of the capability.

Task: Adding the capability definition to the manageability resource type definition

  1. Open the HttpServer.mrt file by double clicking on it. This opens the manageability resource type editor. Alternatively, right click on the HttpServer.mrt file and choose Open With > WSDM Manageable Endpoint Type Editor.
  2. A list of capabilities that this resource type provides is shown based on what you added when you created this resource type definition. Click Add Capability at the bottom of the list. The resulting window shows the remaining capabilities -- both predefined and custom defined -- that can be added to the resource type. At the bottom of the list you will find the capability definition you just created. (Note that all the capability definitions from all projects in the workspace are shown here. There can be capabilities with the same name defined in different projects, and, if so, use the path shown within the parenthesis next to the capability name to determine which one to add to the resource type.) Choose the HttpServer capability you defined and click OK.
    Figure 20. Selecting defined capability
    Selecting defined capability
  3. Save the manageability endpoint resource type definition. At this point the resource type definition is validated. In this example, based on what you have done so far, an error shows up and the file is marked with a red decorator in the Package Explorer.
    Figure 21. Error with validation
    Error with validation
    The problem is that you used the same namespace (http://www.example.com/http-server) for both the resource type HttpServer and capability definition HttpServer. This is a typical, albeit simplistic, example of some of the validation the tooling saves you from having to do when putting together Web services artifacts needed for a WSDM endpoint. To resolve the issue, slightly change the namespace of resource type definition to http://www.example.com/HttpServer. When you save this change, the files are revalidated and the file is no longer marked as invalid.
    Figure 22. Change manageable endpoint namespace
    Change manageable endpoint namespace

Generating code and building the endpoint implementation

Typically, the modeling tasks you have done so far with the tooling are performed by an IT architect or systems analyst. A developer can then take these models and use the tooling to generate the skeleton code that he can then implement. The tooling, however, does more than just generate the skeletons.

It ensures that all the Web services artifacts like the schemas and WSDL files are merged properly and still semantically valid. This is no easy task as you may have realized from the other tutorial or from your past experiences with Web services programming. A number of conventions need to be followed, and the tooling relieves you from having to know it all.

Also, the tooling packages the generated code and artifacts into Eclipse projects -- either for deployment on an application server or as an OSGi bundle. Assuming Eclipse is your primary IDE, you can now build, deploy, and test manageability endpoints from within the same IDE.

In this section, you will first generate code and then follow the reference tutorial to hook in the actual resource, the Apache HTTP server. I will focus only on the simplest way to generate code. Other advanced tooling options are covered in other articles.

Task: Generate skeletal endpoint code

  1. Bring up the Package Explorer view (Window > Show View > Package Explorer). Right click on the HttpServer.mrt file. Choose Generate Java Code.
    Figure 23. Generate Java code
    Generate Java code
  2. The resulting window provides some options. First, you need to select a projectizer from the drop-down box. Projectizers create the correct Eclipse projects, which can finally be deployed into the corresponding container (Java Platform, Enterprise Edition (J2EE) application server or OSGi container). For this example, select the first option Axis J2EE.
    Figure 24. Select a projectizer
    Select a projectizer
  3. Next, provide a name for the output project. This project is created (if it does not exist) in the default location, within the current workspace folder. You can provide a different location by unchecking the Use default location checkbox and providing a location either by typing it in or by using the Browse button. If the project already exists, you can overwrite the contents by keeping the Overwrite files if necessary checkbox checked. For this endpoint, you will use ApacheHttpServerImpl as the project name. Enter this name and click Finish.
    Figure 25. Enter the name for the output project
    Enter the name for the output project
  4. A number of actions take place during the creation of the project and the artifacts and progress is shown in the window. All you need is a little patience.
    Figure 26. Generating the output project
    Generating the output project
  5. A new Web project is created in the workspace. It will show a few errors, but nothing that you need to worry about. You can now work on this project to add the implementation code and when done, test it or package it for actual deployment in production.
    Figure 27. A new Web project is created
    A new Web project is created

The generated Web project is similar to any Web project you could have built from scratch in the Eclipse IDE, except much of the content has already been added, including skeletal code for the custom capabilities, the Apache Muse run time JAR files, Web services artifacts like WSDLs and schemas, and Apache Muse-specific artifacts like descriptor files.

In addition, an Apache ANT build file has also been added that lets you build the project by hand, typically outside the Eclipse IDE.

You will now take a look at some of the generated artifacts. I will provide information on the Java source toward the end because that is what you will be changing.

If you had been really attentive during the code generation process, you would have noticed than an additional file with the .dd extension was created in the ApacheWSDMModels project as shown in Figure 27. This is a deployment descriptor template that is generated and used during code generation to create the final Muse deployment descriptor file. It is saved here so that you can edit it and customize code generation. The deployment descriptor and advanced code generation will be covered in a future article.

JAR files

Opening up the Web app libraries, you can see a number of JAR files that have been added automatically.

Figure 28. Opening Web app libraries
Opening Web app libraries

These are all required by the endpoint for various tasks, including XML processing, SOAP message processing, WSDL processing, and so on. Most important are the Apache Muse JAR files, which provide the run-time environment for the endpoint that follows the prescribed programming model and implementations of the standard WSDM capabilities.

Configuration files

Certain configuration files are automatically generated, including axis2.xml required by the Apache Axis engine (used by Apache Muse) and the web.xml that is required for all Web applications.

Figure 29. Configuration files
Configuration files

In addition, the Apache Muse descriptor file muse.xml is created. This file is very important because it describes the various aspects of this endpoint. The declarative descriptor file-based approach is quite central to the Apache Muse programming model.

Also note that a few Module Archive (.mar) files have also been added. These are required by Apache Muse.

Finally, notice the router-entries folder with an XML file within it. This relates to the persistence mechanism used by Apache Muse. The XML file contains the reference parameters for this instance of the HttpServer instance (which is why it is within a sub-folder of that name) that goes into creating the Endpoint Reference (EPR) for that instance. The presence of this file means that when the Muse run time is started, it creates one endpoint instance of this type.

You can, of course, create more instances at startup merely by adding new XML files in this folder with different reference parameters. For this example, I will stick to just the one that has already been generated.

Task: Adding the implementation code

  1. Open the JavaSource folder. You will see a package whose name is derived from the namespace you used for the capability definition. Within this package you will see an interface IMyCapability, which has the operations you defined and getters/setters for the properties you defined. Note that there is a setServerName() even though you defined the ServerName property as not writable. This has been corrected in newer versions of the tooling, but for now you should just ignore this method; the run time will not allow this operation to be invoked.
    Figure 30. IMyCapability interface
    IMyCapability interface
  2. The actual skeletal implementation is in the MyCapability class. Note that skeletal code is generated only for user-defined capabilities. For the standard WSDM capabilities that you included in your endpoint, the implementation is provided by the Apache Muse run time, and, hence, no source code is required for them. Open the Tasks view by clicking Window > Show View > Tasks. In the Tasks view, you can see the methods for which you have to explicitly add code. Clicking on a task takes you to the lines of code where modifications/additions are necessary.
    Figure 31. Methods for which you must add code
    Methods for which you must add code
  3. You will now add code for the start method that will use the Java exec method to start the HTTP server instance. This code is very similar to what is used in the other tutorial.
    Figure 32. Adding code to start method
    Adding code to start method
  4. In addition, you have added a StartFailedFault class whose implementation is a very simple extension of the BaseFault class.
    Figure 33. Adding StartFailedFault class
    Adding StartFailedFault class
  5. Similarly, you will implement the stop method next. However, this is slightly different from the implementation used in the referenced tutorial because you will introduce the specified delay before the HTTP server is shut down (in a real implementation, this would be done in a threaded manner). As before, you will add a StopFailedFault.
    Figure 34. Adding stop method
    Adding stop method
  6. Finally, there is one important piece of code you need to add, reading the actual property values from the Apache HTTP server's configuration file. You will borrow this piece of code from the other tutorial, with a few changes to suit what you have done so far. You will override the initialize() method that is called before the endpoint services any Web services calls, and add code that will read the configuration file and store the corresponding values in the exposed properties.
Listing 1. Important to add the ability to read server's configuration property values
public void initialize() throws SoapFault {
  super.initialize();
  Map configParams = null;
  try {
    configParams = readConfigFile("d:/apache2.2/conf/httpd.conf");
  } catch (IOException error) {
    throw new SoapFault("Error while reading httpd.conf.", error);
  }
  _ServerName = (String) configParams.get("ServerName");
  String portString = (String) configParams.get("Listen");
  String threadsString = (String) configParams.get("ThreadsPerChild");
  _Listen = Integer.parseInt(portString);
  _ThreadsPerChild = Integer.parseInt(threadsString);
}

protected Map readConfigFile(String filePath) throws IOException {
  BufferedReader reader = new BufferedReader(new FileReader(filePath));
  String nextLine = null;
  Map configParams = new HashMap();
  while ((nextLine = reader.readLine()) != null) {
    nextLine = nextLine.trim();
    // ignore comments and blank lines
    if (nextLine.length() == 0 || nextLine.charAt(0) == '#'
        || nextLine.charAt(0) == '<')
      continue;
    int space = nextLine.indexOf(' ');
    String name = nextLine.substring(0, space);
    String value = nextLine.substring(space + 1);
    configParams.put(name, value);
  }
  return configParams;
}

The tooling can also generate the client proxy code that you can use to interact with the endpoint from the same models used to generate the endpoint code. Typically, such proxies are used by management applications that are specific to such resource types (not generic ones). Now let's generate a client proxy so that you can write a test program for your endpoint.

Task: Generating the client proxy code

  1. Right click on the HttpServer.mrt file in the Package Explorer and choose Generate Java Code.
    Figure 35. Generating Java code
    Generating Java code
  2. In the first pull-down list box in the resulting window choose the Projectizer second option, Client Proxy. Enter the name of the project that will hold the client proxy code, for this example use ApacheHttpServerProxy. As you did earlier, you may choose to change the location where this project will be created and if it already exists whether to overwrite it.
    Figure 36. Enter the name of project to hold client proxy code
    Enter the name of project to hold client proxy code
  3. After you click Finish, a new Java project is created, which contains the client proxy code and the JAR files required by the proxy to invoke WSDM calls on the generated endpoint. However, it is missing one JAR file, the XercesImpl-2.7.1.jar. You can add this to the classpath of the Java project by copying it from the lib folder of the generated Web project ApacheHttpServerImpl and then adding it to the build path of the project.
    Figure 37. Adding Java project to the classpath
    Adding Java project to the classpath
  4. The MyService interface lists all the operations that can be called on the generated endpoint using this generated proxy. The proxy effectively hides all the Web services calls that need to be made on the endpoint to get anything out of it! Also, it provides granular operations for working with the resource properties, separate get(), update(), delete(), and insert methods. You will add a TestEndpoint class in the same package that uses this proxy (as shown in Listing 2).
Listing 2. Adding a TestEndpoint class
package com.example.www.HttpServer;

import java.net.URI;

import org.apache.muse.ws.addressing.EndpointReference;
import org.apache.muse.ws.addressing.soap.SoapFault;

public class TestEndpoint {
  MyService _endpoint = null;
  
  private void displayProperties() throws Exception{
    System.out.println("Properties of the HTTP server: ");
    System.out.println("Threads per child process = "  
                                          +_endpoint.getThreadsPerChild());
    System.out.println("Listening port = "+_endpoint.getListen());
    System.out.println("Server name = "+_endpoint.getServerName());
  }
  
  private void displayCapabilities() throws Exception{
    URI[] caps = _endpoint.getManageabilityCapability();
    System.out.println("HTTP servers provide the following capabilities:");
    for(int i=0; i<caps.length; i++){
      System.out.println(caps[i].toASCIIString());
    }
  }
  
  private void startServer(){
    try {
      _endpoint.start();
    } catch (SoapFault e) {
      e.printStackTrace();
    }
  }
  
  private void stopServer(int delay){
    try {
      _endpoint.stop(delay);
    } catch (SoapFault e) {
      e.printStackTrace();
    }
  }
  
  private void printUsage(){
    System.out.println("TestEndpoint <URI in EPR of endpoint> [start|stop]");
  }
  
  public static void main(String args[]){
    try{
      TestEndpoint tester = new TestEndpoint();
      if(args.length<1){
        tester.printUsage();
        return;
      }
      EndpointReference ref = new EndpointReference(new URI(args[0]));
      tester._endpoint = new MyServiceProxy(ref);
      if(args.length==1){
        tester.displayProperties();
        tester.displayCapabilities();
        return;
      }else{
        String operation = args[1];
        if(operation.equalsIgnoreCase("start")){
          tester.startServer();
        }else if(operation.equalsIgnoreCase("stop")){
          int delay = 0;
          if(args.length>2){
            delay = Integer.parseInt(args[2]);
          }
          tester.stopServer(delay);
        }
      }
    }catch(Exception e){
      e.printStackTrace();
    }
  }
}

Deploying and testing the endpoint

The Eclipse IDE comes with a lot of goodies for testing the code you have so painstakingly built. However, to test the generated endpoint, you must have an application server installed.

The easiest to find would be Apache Tomcat 5.0. Download and install Apache Tomcat 5.0 on your machine. While 5.5 is the latest version, I'd suggest using 5.0 for JDK compatibility. You can test the endpoint by exporting the Web project as a WAR file, deploying it on Tomcat, and running the test client against it.

But there is an easier way to perform all testing within the workbench by using embedded Tomcat. Assume that Tomcat is installed at d:\tomcat.

Task: Deploying the endpoint for testing

  1. Right click on the generated Web project (ApacheHTTPServerImpl) and choose Run As > Run on server.
    Figure 38. Running ApacheHTTPServreImpl
    Running ApacheHTTPServreImpl
  2. In the resulting window you are presented with a list of options, possible server run times that can be used from Eclipse in an embedded fashion for deployment and testing. Pick Tomcat V5.0 Server under Apache and click Next.
    Figure 39. Selecting the server type
    Selecting the server type
  3. The specifics of the Apache Tomcat installation are next. You can type in or browse to the Apache Tomcat installation folder (d:\tomcat). Remember that the JRE setting is important. You can leave it at the default workbench JRE if you are sure of what version the Workbench is currently using (this is what you provided to Eclipse on startup or the default JRE on your machine). You can also pick other installed JREs from the drop-down box or you can click on Installed JREs to see the currently installed JRE and add new JREs that may be available on your machine. In most cases, particularly for Apache Tomcat 5.0, the defaults will suffice.
    Figure 40. Specifying the installation directory
    Specifying the installation directory
  4. The next window shows Web applications that are hosted on this server. Because you started from your Web project, it has been added automatically. Click Finish.
    Figure 41. Web applications hosted on server
    Web applications hosted on server
  5. The Servers view opens and you can see the Tomcat server you added there. The server automatically starts after your Web application is published to it.
    Figure 42. Servers view
    Servers view
    Some messages also show up in the Console view. Finally, a browser will opens pointing to this URL: http://localhost:8080/ApacheHttpServerImpl/.

Surprisingly, nothing important appears in the browser window. However, recollect that you address a WSDM endpoint using an Endpoint reference. Next, you will provide the correct EPR to your test program. Also when you start the generated Web project, the Managed Agent Explorer launches and Eclipse switches to the profiling and monitoring perspective. The use of the Managed Agent Explorer is covered in another tutorial. For now, just switch back to the Java perspective and continue.

Task: Testing the endpoint

  1. Now that your endpoint is deployed and running, you can test it using the simple Java test program you wrote, from within the same Eclipse workbench. Right click on the ApacheHTTPServerProxy project and choose Run As > Run... Do not select the Java Application option however, tempting it might be, because you want to provide some configuration before running the test application.
    Figure 43. Testing the endpoint
    Testing the endpoint
  2. In the Run window, double click on Java Application on the left to create a new run configuration. Provide a name for the run configuration (like TestEndpoint). Then in the Main Class setting, select Browse. This opens a list of executable Java classes in this project (ones with a main() method). Select TestEndpoint, and click Apply to save the settings made so far.
    Figure 44. Running a Java application
    Running a Java application
  3. Switch to the Arguments tab. If you remember, you still need to provide the endpoint reference to your test program together with other optional commands. Because your EPR is only a URL, you can provide it in the Program arguments field. As a rule of thumb, if the name of the endpoint's Web project is foo and you had named the resource type definition bar, then the URL that goes into the EPR would be http://localhost:8080/foo/services/bar. So in this case, it would be http://localhost:8080/ApacheHttpServerImpl/services/HttpServer. Enter this and click Run.
    Figure 45. Program arguments
    Program arguments
    You will see the following output in the Console view:
Listing 3. Eureka! A successful endpoint creation!
Properties of the HTTP server: 
Threads per child process = 250
Listening port = 80
Server name = Balan-T41.ibm.com:80

HTTP servers provide the following capabilities:
http://docs.oasis-open.org/wsdm/muws/capabilities/Identity
http://docs.oasis-open.org/wsdm/muws/capabilities/ManageabilityCharacteristics
http://docs.oasis-open.org/wsdm/muws/capabilities/OperationalStatus
http://docs.oasis-open.org/wsdm/muws/capabilities/Description

You have successfully created an endpoint, deployed it, and tested it! Even though you performed all your deployment and execution (of both the endpoint and the test program) within the workbench, the test program made actual Web services calls to the endpoint and received SOAP responses. The beauty of the tooling is in hiding all these complexities from you so that you can focus on the actual functional aspects of the tooling.

The Eclipse workbench also provides the capability of monitoring HTTP packets that flow to and from the embedded application server instance. You use this capability to look at the actual SOAP messages flowing between the test program and our endpoint.

Task: Monitoring the SOAP exchanges

  1. Switch to the Servers view (or if it is not visible, bring it up by selecting Window > Show View > Other and choosing Servers under Server in the tree). Right click on the server instance added before. Choose Monitoring and select Monitor port 8080 (HTTP). This toggles the option to monitor this port.
    Figure 46. Monitoring the SOAP exchanges
    Monitoring the SOAP exchanges
  2. The workbench will monitor at a certain port and forward those requests/responses to port 8080; it provides a proxy for port 8080. To find out where the monitor is listening, select Properties. As you can see, the monitor port is 11471.
    Figure 47. Ports being monitored
    Ports being monitored
  3. Now you need to open the TCP/IP Monitor view, in which you can see the actual packets. Select Window > Show View > Other and select TCP/IP Monitor from under Debug.
    Figure 48. Selecting TCP/IP Monitor
    Selecting TCP/IP Monitor
  4. In the TCP/IP Monitor view, select XML for the Request and Response types.
    Figure 49. TCP/IP Monitor view
    TCP/IP Monitor view
  5. Before you run the test program, you must change the URL in the Endpoint Reference so that all message exchanges will flow through the monitor port 11471. Right click on the project (ApacheHTTPServerProxy) and select Run As > Run. In the Run configuration window (the run configuration TestEndpoint is typically chosen already; otherwise, you should chose it), switch to the Arguments tab and change the Program arguments to http://localhost:11471/ApacheHttpServerImpl/services/HttpServer. Click Run.
    Figure 50. Change the URL in the Endpoint Reference
    Change the URL in the Endpoint Reference
  6. You will see the original execution results in the Console view. Switch to the TCP/IP Monitor view. You can see a list of all the message exchanges and the actual SOAP messages. This is valuable information when tracing complex method calls made on a WSDM endpoint over a series of operations.
    Figure 51. List of all the message exchanges and the actual SOAP messages
    List of all the message exchanges and the actual SOAP messages

Summary

I hope you've enjoyed learning about an alternative way to build a WSDM interface for the ubiquitous Apache HTTP server without having to worry about Web services artifacts like WSDL and schema files. Taking both of the tutorials together -- the hand coding method from the previous tutorial and using the tooling integrated into Eclipse to model, generate, and test WSDM interfaces from this tutorial -- will provide a broader understanding of the nuances of working with Web Services Distributed Management.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Tivoli (service management), Tivoli, SOA and web services
ArticleID=195433
ArticleTitle=Create a WSDM endpoint using Build to Manage tooling from the Eclipse TPTP project
publish-date=02132007