Designing manageable resources with Apache Muse

Introducing best practices for creating manageability interfaces that are optimized for reuse

Dan Jemiolo (danjemiolo@us.ibm.com), Advisory Software Engineer, IBM

Dan Jemiolo is an Advisory Software Engineer on IBM's Autonomic Computing team in Research Triangle Park, NC. He led the design and development of Apache Muse 2.0 and continues to work on the project today. Dan also participates in the WS-RF TC as editor of the WS-ResourceMetadata specification and is involved in IBM's strategy for increasing adoption of Web services standards. He came to IBM just over two years ago after earning his Master of Science degree in Computer Science from Rensselaer Polytechnic Institute.

Summary: Do you want to evolve from creating WSDM-compliant projects with Apache Muse to creating WSDM-optimized projects? Any new user can use Apache Muse to design the Web services interface for a manageable resource, generate the necessary Java code, and build a deployable artifact with little thought towards the underpinnings of the Apache Muse runtime. But if you are creating Web services to expose a large number of manageable resources or even just a single resource that is fairly complex, it pays to understand the core concepts behind the Muse programming model. Read this article, and the following tutorial, to discover the core concepts that will take you from creating WSDM-compliant projects with Muse to creating WSDM-optimized projects with Muse.

Date: 03 Jul 2007
Level: Intermediate
Comments:

The Apache Muse project provides the tools so that a developer new to managed resource Web services interface design can perform the necessary tasks to building a WS-DistributedManagement (WSDM)-compliant interface -- designing and building the deployable artifact, as well as generating the Java™ code -- without having to completely understand how the Muse runtime operates. This is possible if you are planning only to expose a single (or few), simple manageable resource(s). If you're going for a large number of resources or even a single one that is somewhat complex, you are much better off understanding the core concepts of the Muse programming model. This article introduces you to the core concepts of the Muse programming tools and is coupled with next week's tutorial that leads you through designing and developing a system with multiple manageable resources

You should already be familiar with building simple Web service endpoints with Apache Muse, and you should understand the general ideas behind the Muse programming model and its code generation tool, WSDL2Java. You may wish to review the design document for Apache Muse if you have not done so already; the concepts in this document, when combined with the advice in this article, will help you write code that leverages the Apache Muse runtime effectively and that simplifies the maintenance phase of your project. Also, please feel free to see any of the associated articles and tutorials in the Resources section; there are many excellent tomes on using Muse tools to craft WSDM-compliant interfaces for managed resources.

The role of capabilities in designing manageable resources

Another WSDL tool: WSDLMerge

To get a jump on the tutorial that follows this article, let's take a quick look at WSDLMerge from the Apache Muse project. This utility was created because it is easier to develop WSDL files separately and then combine them before passing them onto code generation. But, because WSDL is defined the way it is, it's impossible to declare portTypes that combine operations from other portTypes, so WSDLMerge lets you:

1.Combine the portType element of each WSDL file into one portType (which will also incorporate all of the necessary messages and schema types).

2, Combine the WS-RF Document schema from each WSDL (if present) into a one merged WS-RF Document schema.

3. Create a binding based on the new portType using conventions needed for wsdl2java and Muse.

4. Create a service element that attaches to the new binding and portType.

When a manageable resource is exposed via Web services, it only has one proper interface, its WSDL document -- this is an important thing to remember as you read this article. The bulk of the WSDL document describes ways for modularizing and breaking down the implementation of a resource. The fundamental pieces of the Muse framework are in place to bridge between the concept of a single, rigid interface (WSDL) and a set of flexible, composable implementation classes. If you learn to approach each new manageable resource as a set of potentially disparate pieces of code all under the umbrella of one WSDL interface, you have conquered the biggest hill on the Muse learning curve. The article explains how to get into this mindset in this section.

Two of the fundamental goals of the WSDM specification are to standardize the way that manageable resources expose a set of core properties and operations and to provide guidance on the design of custom properties and operations. The core definitions, combined with the pattern for custom definitions, present developers with the opportunity to greatly reduce the complexity of their Web services (and the interactions between those services). This simplification takes place on two levels:

By reducing duplication of concepts between similar resource types.
By reducing duplication of concepts across disparate resource types.

Simplifying interfaces between similar resources

Explaining the two levels of simplification is best done with an example. Imagine that you have an IT system in which there are multiple servers and a management application that monitors their performance. For historical reasons (perhaps a change in vendor or an acquisition), half of the servers run IBM WebSphere Application Server 6.1 and half run BEA WebLogic Server 9.0. Your IT staff is responsible for maintaining both, and the management software must be configured to communicate with both using their proprietary interfaces. Both WebSphere and WebLogic are J2EE application servers, but when you factor in the cost of training staff and maintaining the two servers (and the management software), they're really two completely different products.

Why must they be so different? In the WSDM world, they don't have to be. From a WSDM perspective, no application should have to communicate differently between WebSphere and WebLogic just to perform systems management tasks on them -- they're both J2EE application servers and, while their proprietary interfaces can be different, their core functionality is mostly the same. A WSDM-inspired design to the problem of duplicate management software in our system would be to create a single Web service interface for J2EE management concepts and use it to expose both types of servers. This is the first level of interface simplification.

Notice that I'm not talking about creating two interfaces (with two separate WSDLs) that are very similar in nature -- the exact same WSDL is used for both WebSphere and WebLogic and then alternate implementation code is provided when necessary to handle the differences in the servers. The end result, from a client's perspective, is that all server resources appear to be exactly the same -- they are just J2EE application servers. This eliminates all of the duplicate logic, plug-ins, agents, etc., that have to be installed in order for the management software to deal with every version of every type of application server. The management software can now make more assumptions about the resource and not have to handle edge cases caused by different versions of application servers.

When designing a WSDL for an application server resource, you should reuse as many of the concepts and definitions in WSDM as possible before creating custom properties and operations. Those custom properties and operations -- the ones that are specific to application server resources -- would go in their own XML schema. You should also create a unique URI that represents this application server capability (or behavior) and add it to the WSDM ManageabilityCapability property to indicate to clients that, among other things, this resource has the properties and operations of a J2EE application server. If another brand of application server is ever added to the system, it could be exposed using the same WSDL, and you will be able to manage it even if the new server was released years after this management application was!

Simplifying interfaces between disparate resources

You can achieve the second level of interface simplification by looking at some of the custom properties and operations and generalizing a bit further. Expand this example scenario a bit by adding a group of database servers to the mix. Suppose that the management application is also in charge of monitoring installations of IBM DB2 Database Server -- a relational database is quite different from a J2EE application container, so you might think that completely different logic would be needed in order to take on this responsibility. This would mean that our opportunities to simplify the management of an IT system would be limited to situations where resources were very similar.

If you look at some of the J2EE management definitions, though, it shouldn't necessarily be so. Relational databases and J2EE application servers do have some things in common; a great example of these commonalities is performance metrics. There is no reason that things such as a server's thread pool size, request throughput, or number of dropped requests should be exposed differently between the two resources. With WSDM, performance-related properties and operations from the J2EE application server WSDL are extracted and used to define a "performance monitoring" capability that can be reused by any resource that acts as a server. A significant part of the management application just got simpler because it does not have to have specialized logic, agents, etc., for monitoring performance on applications servers versus database servers. Generalizing interfaces with WSDM and capabilities is making the system interactions smaller and more consistent -- this should make the debugging process much quicker.

Now that you know how to look at a Web service definition and start generalizing it for reuse across resource types, you need to determine the best way to reuse the implementation artifacts as much as possible. To do this, look at the Muse programming model.

The role of capabilities in implementing manageable resources

The Apache Muse design document provides an excellent introduction to the capability concept at a programming level:

All Muse resources are collections of smaller units of function called capabilities. The capability concept was initially described in WSDM MUWS 1.0 as a means of communicating to clients what data, operations, and behavior could be expected from the resource (over-and-above the basic contractual guarantees of the WSDL port type). Despite the use of capabilities to advertise behavior to clients, the way that capabilities are defined in the WSDM MUWS specification is reminiscent of the way Java developers break apart large pieces of software into smaller chunks of related tasks; the aggregation of capabilities like Identity, Configuration, and Relationships into a single web service interface suggests a similar model for server-side implementations. Muse has generalized the WSDM MUWS capability concept to make it easier for programmers to implement resources as reusable units of function rather than monolithic Java classes.

Given this definition of Muse capabilities, how can the design decisions made in our previous example apply to our Muse-based projects?

Capabilities as atomic units of function

Each Web services spec that is supported by Apache Muse is implemented in one or more capabilities. Each capability has an interface and a default implementation. The default implementation is what is referenced when Muse's code-generation tool, WSDL2Java, analyzes your WSDL and determines that you are using a given capability; you can swap in your own capability implementation so long as you implement the same interface when doing so.

If you follow the approach the Muse team took in implementing the standard capabilities, you can achieve the same level of flexibility and reuse with your custom capabilities. Any capabilty you define should include XML artifacts (WSDL and XML schema) and a Java interface that are reusable in multiple resource implementations. Only the implementation classes need to be different.

Continuing with the Muse pattern, your artifacts and interfaces can be packaged in a redistributable JAR file that can be copied into each application that implement the capability -- this ensures that each resource that includes the capability does so consistently. If you look in the /modules directory of your Muse distribution, notice that the standard capabilities are packaged like this -- interface files are in JARs under /modules/ws-fx-api and implementation files are in JARs under /modules/ws-fx-impl. You are encouraged to make the same split with your code to encourage reuse of capability concepts in other resource types.

Capabilities as building blocks for advanced features

Aside from the general benefits of reuse (maintaining less code, simplifying communication with management tools, etc.), there is another benefit of breaking down a resource implementation into capabilities -- it makes it easier to write advanced features that add and remove options gracefully. Most of your internal resource implementation logic is based on finding capabilities and using them to perform tasks, so it is easy to introduce logic like this:

Listing 1. Pseudo-code showing time-delayed tasks

if Capability A is present, then 
    invoke Method B
    
else if Capability C is present, then 
    invoke Method D, and 
    notify clients
    
else 
    fail with error message

This pseudo-code illustrates how, given guaranteed interfaces for certain features (capabilities), another capability can determine which tasks can be completed and which tasks must wait for another time. By adding and removing capabilites with Muse's pluggable resource definitions, you can change the behavior of a resource in response to external factors (such as turning off certain features in response to change in security policy) without breaking the rest of the resource implementation.

You can also augment certain resources that are very similar to others but have special roles (such as only your WebSphere servers face the public Internet, so you only want the performance monitoring capability on them). Responding gracefully to the presence of certain capabilities emulates (at a much more granular level) the ideals of Service Oriented Architecture.

In conclusion

This article has shown some of the design principles used by the Apache Muse team, principles that are meant to help with your own projects. By building manageable resources in the same way that the Muse team implemented the WSDM standard, you can take full advantage of the Muse framework and avoid the maintenance problems that come with rewriting or cut-and-paste coding. Most importantly, you'll be on your way towards achieving the simplicity of IT management that was the inspiration for WSDM in the first place.

Resources

Learn

The Apache Muse programming model is driven by four concepts -- the capability, the resource, the implied resource pattern, and the isolation layer.
The developerWorks Autonomic computing "library" on WSDM and Muse techniques is growing quite rapidly. For instance:
- "Create a WSDM interface for an HTTP server using Apache Muse" (November 2006) is a step-by-step guide to using Apache Muse to create a WSDM-compliant interface for a manageable resource.
- "Keep your WSDM endpoints trim with Apache Muse" (December 2006) shows you how to represent a large number of resources without an overwhelming increase in footprint.
- "Muse and WEF eases event reporting" (April 2007) demonstrates how the Muse implementation of WEF lets you create, send, and receive WEF events using a simple Java API.
- "Enforce resource property semantics with metadata" (April 2007) show you how applying WS-ResourceMetadata can secure WS-ResourceProperties with Apache Muse.
- "Optimal message processing with WS-Notification filters" (May 2007) explains the pros and cons of notification filters and how to use them in Apache Muse.
Visit the Apache Muse site for more on this Java-based implementation of the WS-ResourceFramework, WS-BaseNotification, and WS-DistributedManagement specifications, a framework designed to let users build Web service interfaces for manageable resources without having to implement all of the "plumbing" described by these standards.
Browse the technology bookstore for books on these and other technical topics.
Get in on the ground floor of WS-Notification specs and documents.

Get products and technologies

Download Apache Muse 2.1.0 for your own.
Go to the Autonomic Computing Toolkit to download great autonomic computing components like the Integrated Solutions Console.

Discuss