 | Level: Intermediate Dan Jemiolo (danjemiolo@us.ibm.com), Advisory Software Engineer, IBM
12 Jun 2007 One of the most powerful features of the WS-DistributedManagement (WSDM) standard is the Advertisement capability -- it defines a standard for notifications describing the life cycle of a manageable resource. When combined with WS-Notification (WSN), WSDM Advertisement can help solve one of the trickiest problems in a self-managing IT system -- how to "bootstrap" the system by alerting management clients to the manageable resources they should be monitoring. Today this configuration can be done with manual intervention and the hardcoding of resource information, but this does not make for a very adaptable system. In this article, the author will show how manageable resources that are implemented with Apache Muse can take advantage of its WSDM Advertisement features to make startup and discovery a more dynamic and flexible process.
The goal of the WSDM Advertisement capability is to alert management applications (and any other interested parties) of the creation and destruction of a manageable resource. When a resource is created, the implementation of WSDM Advertisement should send a standard notification to all subscribers telling them the location of the new resource (using an endpoint reference, EPR). Similarly, when a resource is destroyed, the implementation should send another notification telling subscribers that the resource is no longer available. The consumers of the advertisements can sign up for the notifications using WSN subscriptions. The flow of information in an advertisement-based system is illustrated in Figure 1:
Figure 1. The flow of WSDM Advertisement operations in a system
Steps 1-3 are as follows:
- A management application subscribes with an existing "advertisement publisher"
resource whose job is, among other things, to alert subscribers of the creation and destruction of new resources. This subscription happens using WSN operations.
- Manageable resources come online and the advertisement publisher becomes aware of them, either through its own monitoring or by being alerted through some internal system API.
- The advertisement publisher packages up an event report using the WSDM Event Format (WEF) and sends it to all subscribers via WSN operations.
The content of the WEF-formatted events sent by the publisher must comply with what is described in the WSDM MUWS specification, Part 2 (see Resources). An example of the unique content that is found in a standards-compliant "resource creation" event is provided in Listing 1. The event data includes the EPR of the newly-created resource so that the advertisement consumer can then communicate with it directly; destruction advertisements carry similar identifying information.
Listing 1. Content found in a standards-compliant resource creation event
<muws2:CreationNotification>
<muws1:ManageabilityEndpointReference>
<wsa:Address>http://12.34.56.789/database/server</wsa:Address>
<wsa:ReferenceParameters>
<db:ResourceId>DatabaseResource-1</db:ResourceId>
</wsa:ReferenceParameters>
</muws1:ManageabilityEndpointReference>
</muws2:CreationNotification>
|
Before you learn to enable the WSDM Advertisement capability, you must be familiar with building Web service endpoints with Apache Muse and understand the general ideas behind WSDM and WSN. If you want to get more background on WSDM, WSN, and Muse before you begin, please follow the links in the Resources section.
Enabling WSDM Advertisement with Apache Muse
The Apache Muse project includes a Java interface for the WSDM
Advertisement capability, as well as three different Java implementation classes for
that interface. The three implementations each provide a different level of breadth as
far as monitoring resource types and publishing advertisements; all three send standards-compliant advertisements using WSN and WEF and all are easy to configure in your Muse application. The following sections describe the different implementations of WSDM Advertisements so you will know which one to use for your scenario.
Configuration for a single resource type
Adding the WSDM Advertisement capability to one of your resource types so that
advertisements are sent each time it is instantiated is as easy as adding an extra <capability/> element to your resource definition in the Muse
descriptor file, muse.xml. All you have to do is open your muse.xml file, find the <resource-type/> element that represents your resource, and add
the following XML underneath it:
Listing 2. Configuring so advertisements are sent on each instantiation
<capability>
<capability-uri>http://docs.oasis-open.org/wsdm/muws/capabilities/Advertisement
</capability-uri>
<java-capability-class>org.apache.muse.ws.dm.muws.adv.impl.SimpleAdvertisement
</java-capability-class>
</capability>
|
As always, the <capability-uri/> element alerts Muse
as to the actual capability being used (WSDM Advertisement) while the <java-capability-class/> element tells it which implementation
class is used for that capability. The subsequent sections alter this XML simply by
changing the name of the Java class used in this element. For this scenario, org.apache.muse.ws.dm.muws.adv.impl.SimpleAdvertisement is used because it only publishes notifications for the resource that has defined it. If you have other resources defined in muse.xml, they will not be the subject of advertisements unless you add this XML to their definitions as well.
Configuration for all resource types
It is useful to be able to limit advertisement to just a few specific resource types as
in the previous section, but many times you need to send advertisements for all resources defined by your application. In this situation, you need to make a few modifications:
- Create a new resource type with the following capabilities:
- WSN NotificationProducer.
- WSDM Advertisement.
- This article refers to the new resource type as "advertisement publisher," but you can call it whatever you want in your muse.xml definition. All that matters is that it can be reached via WSN and sends messages using WSDM Advertisement.
- Remove the reference to the
SimpleAdvertisement class and
replace it with org.apache.muse.ws.dm.muws.adv.impl.BroadcastAdvertisement. This
class is written so that it sends advertisements for every resource that is
created within the Muse application. By adding this implementation of WSDM Advertisement
to the publisher resource's definition, the advertisement can be configured once and
applied to all resources in the application, even as definitions are
added and removed from muse.xml.
- Remove any
<capability/> definitions in your other resources that refer to the WSDM Advertisement capability.
There is one more thing to note about configuration: When creating a publisher resource, you should make sure that it is the first resource defined in muse.xml. The Muse runtime initializes resources in the order they appear in the muse.xml file and if some of your resources are instantiated at start up, then it's important that your publisher already be instantiated so it can send its notifications. Any resources instantiated before the publisher will never be included in its stream of advertisements.
A special case: Configuration for service group entries
The BroadcastAdvertisement implementation class from the
last section will cover the case where WS-ServiceGroup (WSSG) entries are created and
destroyed, sending out notifications to any interested subscribers; however, this is not quite the semantics that most service group users desire. The WSSG spec describes scenarios wherein a client can subscribe directly with a service group (not some "publisher resource") in order to find out about modifications to its list of entries. While it's technically possible to achieve the same results by having clients talk to a publisher resource instead of a service group, it would be ideal to implement all of the WSSG scenarios exactly as described. Fortunately, Muse has an answer.
If you add the WSDM Advertisement capability to a service group resource (using a <capability/> element) and use org.apache.muse.ws.dm.muws.adv.impl.ServiceGroupEntryAdvertisement as your implementation class, your service group clients will be able to subscribe to the special service group modification topics described by the WSSG spec and receive advertisements directly from the service group resource. The content of the WEF events includes the standard advertisement data as well as some additional data defined by the WSSG spec; an example of the WSSG-defined data is provided in Listing 3:
Listing 3. WS-ServiceGroup-defined data
<wsrf-sg:EntryAdditionNotification>
<wsrf-sg:ServiceGroupEntryEPR>
<wsa:Address>http://12.34.56.789/database/service-group-entry</wsa:Address>
<wsa:ReferenceParameters>
<db:ResourceId>SGEntryResource-1</db:ResourceId>
</wsa:ReferenceParameters>
</wsrf-sg:ServiceGroupEntryEPR>
<wsrf-sg:MemberServiceEPR>
<wsa:Address>http://12.34.56.789/database/server</wsa:Address>
<wsa:ReferenceParameters>
<db:ResourceId>DatabaseResource-1</db:ResourceId>
</wsa:ReferenceParameters>
</wsrf-sg:MemberServiceEPR>
</wsrf-sg:EntryAddtionNotification>
|
This implementation class only works if the resource in question implements the WSSG ServiceGroup capability. It only handles the special case of service group entry resources and will not send advertisements for any other resource type.
Enabling consumers to receive WSDM Advertisements
There are two easy ways to set up your advertisement consumers to start receiving advertisement notifications:
- Have them send a WSN Subscribe message to the resource that is in charge of publishing advertisements. This requires that the client application know who the publisher resource is ahead of time so it can subscribe.
- Configure Muse's implementation of WSDM Advertisement to automatically subscribe a
consumer and start sending advertisements as soon as it is initialized. This can be done
by adding the initialization parameter shown in Listing 4 to the capability definition in muse.xml:
Listing 4. Initialization parameter addition
<capability>
<capability-uri>http://docs.oasis-open.org/wsdm/muws/capabilities/Advertisement
</capability-uri>
<java-capability-class>org.apache.muse.ws.dm.muws.adv.impl.SimpleAdvertisement
</java-capability-class>
<init-param>
<param-name>initial-consumer-reference</param-name>
<param-value>/consumer-epr.xml</param-value>
</init-param>
</capability>
|
The XML in bold provides the implementation with the name of a file that contains
the EPR of the advertisement consumer (in this case, the file is named consumer-epr.xml, but you can name the file whatever you want). When the capability is initialized, it will create a WSN subscription that will send all advertisement notifications to the EPR provided in the given file. This configuration trick works with all three of the Muse implementation classes.
Once the initial subscription is in place, the traditional pub-sub model of WSN takes over -- advertisements are sent in the same way other WSN notifications are and consumers do not need any special interface or logic to process these events.
In conclusion
WSDM Advertisement is a powerful capability that is surprisingly easy to enable using
the Apache Muse framework: All of the event data is filled in automatically, integration
with WSN is seamless, and the implementation is flexible enough to let you control how much data you advertise (and to whom). The use of WSDM Advertisement is a very efficient way to automate some parts of the system initialization process so that managers and manageable resources can find out what other resources are online and start leveraging them immediately. For Muse adopters, this is as simple as plugging in one more capability to their resource definitions.
Resources Learn
-
Read the WSDM MUWS
specification, Part 2 which provides the details behind how an implementation of WSDM Advertisement should behave.
-
Learn about the Apache Muse programming model which 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:
-
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 products and technologies
-
Download Apache Muse 2.2.0 for your own (and to build and test and the code that is illustrated in this article).
Discuss
About the author | | | 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. |
Rate this page
| |
