Understanding WSRF, Part 2: Working with WS ... › developerworks › education › gr-wsr… · See Resources to download the complete WSDL file covered in this tutorial. Section

Understanding WSRF, Part 2: Working withWS-ResourceLifetime, WS-ServiceGroup andWS-BaseFaultsSkill Level: Introductory

Babu Sundaram ([email protected])Grid SpecialistFreelance Writer

22 Mar 2005

"This tutorial further explains how to use stateful resources in the statelessenvironment of Web services. It explains how to destroy WS-Resources and how toadd them to logical groupings. It also explains the various faults defined in WSRF."

Section 1. Before you start

Who should take this tutorial?

This tutorial introduces the concepts behind the Web Service Resource Framework(WSRF). Specifically, it explains the concepts of WS-ServiceGroups andWS-BaseFaults and how to create, use, and manipulate them. It also explains theimmediate and scheduled destruction of WS-Resources usingWS-ResourceLifetime.

This tutorial should be read by users who wish to create Web services-basedapplications that require the use of "stateful resources." Although the most commonapplication of this concept is currently grid services, the concepts in this tutorialapply to any Web services application that requires a notion of "state."

Because this is a conceptual tutorial, it requires no actual programming, butfamiliarity with programming concepts, such as objects and properties, will behelpful. It does, however, discuss the creation of a Web Services DescriptionLanguage (WSDL) file, so a general knowledge of XML in general and Web servicesin particular will be helpful. Basic WSDL concepts are covered in Part 1 of thisseries, Understanding WSRF, Part 1: Using WS-ResourceProperties. (See

Working with WS-ResourceLifetime, WS-ServiceGroup and WS-BaseFaults© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 43

mailto:[email protected]

http://www.ibm.com/developerworks/edu/gr-dw-gr-wsrf1-i.html

http://www.ibm.com/legal/copytrade.shtml

Resources for other links to useful background information.)

What is this tutorial about?

Part 1 of this series, Understanding WSRF, Part 1: Using WS-ResourceProperties,introduced the overall area of the Web Services Resource Framework, whichprovides a standard way to use stateful resources in the inherently statelessenvironment of Web services. In addition to covering the concept of a WS-Resource,that tutorial looked at manipulating WS-Resources according to the messageexchange patterns established in the WS-ResourceProperties specification.

This tutorial picks up where Part 1 left off, discussing WS-ResourceLifetime,WS-ServiceGroup, and WS-BaseFaults specifications. During the course of thetutorial, we will:

• Provide a brief review of the overall WS-Resource concept

• Look at destroying WS-Resources directly

• Schedule WS-Resources for termination at a later time

• Create a WS-ServiceGroup

• Add ServiceGroupEntries to and remove them from a ServiceGroup

• Retrieve single and multiple ServiceGroupEntries from a ServiceGroup

• Examine the concept of a standard BaseFault

• Learn how to extend BaseFaults to serve other purposes

• Show how all of these tasks fit into a WSRF-related WSDL file

Note that WSRF as a specification defines the structure of a WSDL file thatdescribes these operations. That WSRF file can then be used by implementations inany language. This tutorial describes the creation of the WSDL file and shows theresulting SOAP messages.

It's important to understand that the WSRF specifications define what should bedone, but not how it should be done. The actual implementation of the conceptsdescribed here is left to the application. In Part 4 of this series, UnderstandingWSRF, Part 4: Using the Java Core WSRF classes, we'll discuss thisimplementation using the Core Java WSRF classes provided by The GlobusAlliance.

Prerequisites

Because this tutorial does not involve programming, the only tool required is a texteditor for creating WSDL files. We will, however, reference WSRF-related WSDLfiles.

developerWorks® ibm.com/developerWorks

Working with WS-ResourceLifetime, WS-ServiceGroup and WS-BaseFaultsPage 2 of 43 © Copyright IBM Corporation 1994, 2008. All rights reserved.


http://www.globus.org/wsrf



See Resources to download the complete WSDL file covered in this tutorial.

Section 2. The story so far

Web Services Resource Framework

When you have an application in which the various players, such as servers andclients, are geographically separated, you often find that some form of Web servicescan make it easier to get information from one place to another. One problem withthis solution, however, is the inherent stateless nature of Web services. There is nopersistent connection, like that of a database client with a database server. The onlyinformation available at the time of a request is the information that is part of thatrequest.

That's fine if you're just requesting the current temperature for Albuquerque or IBM'scurrent stock quote. But when you're building an enterprise application or acomputational grid, that's a problem.

Not that there aren't ways to indicate state in a Web services application. There are.Lots of ways, in fact, which is part of the problem. In order to create a "standard"way of doing things, The Globus Alliance came up with the Web Services ResourceFramework (WSRF), a standardized means for using Web services to manipulatestateful resources.

The organization's work was separated into several documents:

• Modeling Stateful Resources With Web Services: This document explainsthe overall concept of WS-Resources and shows how all of the conceptslaid out in subsequent documents fit together.

• WS-ResourceProperties: This document explains how to define andmanipulate a WS-Resource.

• WS-ResourceLifetime: This document explains how to destroy aWS-Resource.

• WS-ServiceGroup: This document explains how to create logicalgroupings of WS-Resources and how to control and manipulate thosegroupings.

• WS-BaseFault: This document defines the basic error message that anyWSRF application must implement and how to extend it to create newerrors.

• WS-Notification: This group of documents explains how to enable anapplication to provide publish-subscribe capabilities for various application

ibm.com/developerWorks developerWorks®


http://www.ibm.com/developerworks/library/ws-resource/ws-modelingresources.html

http://www.globus.org/wsrf#relevant


events.

Part 1 of this series, Understanding WSRF, Part 1: Using WS-ResourceProperties,covered the first two items, laying the groundwork for this tutorial, which talks aboutWS-ResourceLifetime, WS-ServiceGroup, and WS-BaseFault. Part 3 of this series,Understanding WSRF, Part 3: Using WS-Notification, covers WS-Notification. Inaddition, Understanding WSRF, Part 4: Using the Java Core WSRF classes, detailsthe use of the Globus Core WSRF classes to implement the ideas in parts 1-3.

WS-Resources

The most important concept up to this point is the idea of the WS-Resource. AWS-Resource is the combination of a Web service with a stateful resource. Astateful resource is any item that exists even when you're not interacting with it, suchas a file, a database or, in the case of our example, a satellite.

A resource properties document represents the stateful resource. Consider theresource properties document for our satellite:

<satProp:GenericSatellitePropertiesxmlns:satProp="http://example.com/satellite"xmlns:counterProp=

"http://example.com/satellite/CounterSatelliteProperties"><satProp:latitude>30.3</satProp:latitude><satProp:longitude>223.2</satProp:latitude><satProp:altitude>47700</satProp:altitude><satProp:pitch>49</satProp:pitch><satProp:yaw>0</satProp:yaw><satProp:roll>32</satProp:roll><satProp:focalLength>

21999992</satProp:focalLength><satProp:currentView>

http://example.com/satellite/2239992333.zip</satProp:currentView><counterProp:currentCount>

92828</counterProp:currentCount>

</satProp:GenericSatelliteProperties>

The Web Services Description Language (WSDL) file describes the Web service,and to "hook" them together as a WS-Resource, we'll reference the resourceproperties document type from the portType, as in:

<portType name="SatellitePortType"wsrp:ResourceProperties=

"tns:GenericSatelliteProperties">...

</portType>

Once we've created the WS-Resource type, WSRF defines a way to interact with it.

Working with WS-Resources

Once we've defined a WS-Resource, what can we do with it? Well, WSRF defines





standard messages, such as GetResourceProperty andSetResourceProperty, that enable us to work with the object. We instructed, forexample, the system to change the altitude of our satellite's orbit by making achange to the altitude property for the WS-Resource that represented thesatellite and the Web service.

To do that, we used an EndpointReference, as defined in the WS-Addressingspecification. An endpoint reference includes the URI for the Web service, as well asother information, such as where replies should go. Especially useful forWS-Resources is the ability to include additional information to identify the specificWS-Resource.

That's the essence of WSRF. You create WS-Resources and you manipulate themthrough their properties. For example, in the next section, we'll look at expiringWS-Resources by manipulating their TerminationTime property.

Section 3. WS-ResourceLifetime: Message exchangepatterns

Destroying a WS-Resource

Having just spent an entire tutorial explaining how to create WS-Resources, it mayseem kind of silly to turn around and destroy them, but it's all part of the natural lifecycle. WS-Resources are born when they're requested and die when they're nolonger needed.

That is, if they're set up and used properly. All of the WS-Resources we've createdso far can be destroyed directly, using a Destroy message, as you'll see in Destroythe WS-Resource. In that case, the client sends the "destroy" message and waits tohear that the instruction has been carried out.

Sometimes, however, that's not what we want. Maybe we only want a resource toexist for a specified period of time, no matter if we're still connected to the system.Or maybe we only want the WS-Resource to "time out" if we haven't used it in awhile.

Both possibilities -- immediate and scheduled destruction -- can be handled usingthe techniques in the WS-ResourceLifetime specification. (Note that "immediate andscheduled destruction" are also termed "explicit and soft-state" lifetime managementin Globus lingo.)

In either case, it's important to understand that only the WS-Resource -- theassociation between the stateful resource and the Web service -- is destroyed. Boththe resource itself and the Web service are unaffected.




Let's see how it works.

Create the WS-Resource

Before we go any further, we need to something to destroy. Now put down thatbazooka and don't get excited. We're talking about a WS-Resource here.

As we learned in Part 1, we can send a "create" message:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Header/><SOAP-ENV:Body>

<createSatellitexmlns="http://example.com/satellite"/>

</SOAP-ENV:Body></SOAP-ENV:Envelope>

The result is a SOAP message containing the endpoint reference for theWS-Resource the operation created:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header/><SOAP-ENV:Body>

<wsa:EndpointReferencexmlns:wsa=

"http://www.w3.org/2005/02/addressing"xmlns:sat=

"http://example.org/satelliteSystem"><wsa:Address>

http://example.com/satellite</wsa:Address><wsa:ReferenceProperties>

<sat:SatelliteId>SAT9928

</sat:SatelliteId></wsa:ReferenceProperties>

</wsa:EndpointReference></SOAP-ENV:Body>

</SOAP-ENV:Envelope>

This endpoint reference uniquely identifies the WS-Resource in question, so we canuse it to destroy that WS-Resource.

Destroy the WS-Resource

When we're ready to destroy a WS-Resource, we can use its endpoint reference tocreate the SOAP request:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:sat="http://example.org/satelliteSystem"xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/ws

rf-WS-ResourceLifetime-1.2-draft-01.xsd"><SOAP-ENV:Header>

<wsa:Action>http://docs.oasis-open.org/wsrf/2004/06/WS-Resour

ceLifetime/Destroy





</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">

http://example.com/satellite</wsa:To><sat:SatelliteId>SAT9928</sat:SatelliteId>

</SOAP-ENV:Header><SOAP-ENV:Body>

<wsrl:Destroy /></SOAP-ENV:Body>


Assuming everything goes well, we'll receive an acknowledgement:


xmlns:sat="http://example.org/satelliteSystem"xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/w

srf-WS-ResourceLifetime-1.2-draft-01.xsd"><SOAP-ENV:Header>

<wsa:Action>http://docs.oasis-open.org/wsrf/2004/06/WS-Resourc

eLifetime/DestroyResponse</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">

http://example.com/myClient</wsa:To>


<wsrl:DestroyResponse /></SOAP-ENV:Body>


That may not seem like much of an acknowledgement, but as long as we receive it,we know everything worked properly. Should everything not work properly, we'll getone of the fault messages discussed in WSRF faults: WS-ResourceLifetime. We'llalso get a fault message if we try to access the WS-Resource after it's beendestroyed.

We can also schedule the destruction of the WS-Resource for later.

Schedule destruction of a WS-Resource

We don't always want to destroy a WS-Resource on the spot. In some cases, wesimply want to keep a WS-Resource active for a specific period of time and let it gothe way of the dinosaur. To do that, we'll need to attach a TerminationTimeproperty to the WS-Resource, which means adding it to the resource propertydocument. for our satellite, that means something like:

<satProp:GenericSatellitePropertiesxmlns:satProp="http://example.com/satellite"xmlns:counterProp=

"http://example.com/satellite/CounterSatelliteProperties"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/wsr

f-WS-ResourceLifetime-1.2-draft-01.xsd"><satProp:latitude>30.3</satProp:latitude><satProp:longitude>223.2</satProp:latitude><satProp:altitude>47700</satProp:altitude><satProp:pitch>49</satProp:pitch><satProp:yaw>0</satProp:yaw><satProp:roll>32</satProp:roll>




<satProp:focalLength>21999992

</satProp:focalLength><satProp:currentView>

http://example.com/satellite/2239992333.zip</satProp:currentView><counterProp:currentCount>

92828</counterProp:currentCount><wsrl:TerminationTime>

2005-12-31T12:00:00</wsrl:TerminationTime><wsrl:CurrentTime>2005-2-15T03:24:57</CurrentTime>

</satProp:GenericSatelliteProperties>

If we don't specify a time zone, as in this case, Greenwich mean time is assumed.

Notice that in addition to the TerminationTime, we've added the CurrentTime.This property frees us up from the hassle of synchronizing clocks, as you'll see next.

Getting the CurrentTime and TerminationTime

With clients on different systems, the potential exists for serious problems with clocksynchronization. For example, suppose we wanted to specify that the satelliteWS-Resource we just created should expire in four hours. Choosing a time relativeto the client could be a problem because, in the case of scheduled destruction, it'sthe server that actually destroys the reference.

Fortunately, the WS-Resource carries with it its own "current time." Because it's partof the resource property document, we can request it like any other property:


xmlns:sat="http://example.org/satelliteSystem"xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/ws

rf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/ws



ceProperties/GetMultipleResourceProperties</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">



<wsrp:GetMultipleResourceProperties><wsrp:ResourceProperty>

wsrl:CurrentTime</wsrp:ResourceProperty><wsrp:ResourceProperty>wsrl:TerminationTime</wsrp:ResourceProperty>

</wsrp:GetMultipleResourceProperties></SOAP-ENV:Body>


In this case, we've requested both the CurrentTime and the TerminationTime,so the response contains both of them:





xmlns:sat="http://example.org/satelliteSystem"xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/w

srf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/w



ceProperties/GetMutlipleResourcePropertiesResponse</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">



<wsrp:GetMultipleResourcePropertiesResponse><wsrl:CurrentTime>

2005-2-15T03:24:57</wsrl:CurrentTime><wsrl:TerminationTime>

2005-2-15T03:30:00</wsrl:TerminationTime>

</wsrp:GetMultipleResourcePropertiesResponse></SOAP-ENV:Body>


Within the application, we can then use the CurrentTime to determine and set anew TerminationTime.

Note that while we can request the CurrentTime and TerminationTime just likeany other resource property, we can't set them just like any other resource property.CurrentTime is read-only, and TerminationTime must be set using themessages we'll see next.

Set a new TerminationTime

Once we've determined the appropriate value for the TerminationTime, we cansend a SetTerminationTime message:


xmlns:sat="http://example.org/satelliteSystem"xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/ws

rf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/ws



ceLifetime/SetTerminationTime</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">



<wsrl:SetTerminationTime><wsrl:RequestedTerminationTime>

2005-2-15T07:24:00</wsrl:RequestedTerminationTime>




</wsrl:SetTerminationTime></SOAP-ENV:Body>


Notice that we're not setting the time by directly manipulating theTerminationTime property. This is because we need the system to enforce any ofits own time-related rules, such as not shortening the lifetime of a resource or notextending it past a certain point.

The response message contains the new TerminationTime and theCurrentTime:



srf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/w



ceLifetime/SetTerminationTimeResponse</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">



<wsrl:SetTerminationTimeResponse><wsrl:NewTerminationTime>

2005-2-15T07:24:00</wsrl:NewTerminationTime><wsrl:CurrentTime>

2005-2-15T03:25:08</wsrl:CurrentTime>

</wsrl:SetTerminationTimeResponse></SOAP-ENV:Body>


Unless the application itself has specific rules about setting the time, there are noparticular restrictions. You can even set the TerminationTime to a value in thepast, which has the same effect as sending a Destroy message.

Now we need to add this information to the WSDL file so these capabilities will beavailable from the Web service.

Section 4. WS-ResourceLifetime and the WSDL file

Additional includes

All of these messages, of course, have to be codified in the WSDL file, whichdescribes the actual Web service. Starting with the file we created in Part 1 -- you




can download a copy in Resources -- we can make the following additions toaccommodate managing the WS-Resource lifetimes, starting with the necessaryincludes:

<?xml version="1.0" encoding="UTF-8"?><definitions name="Satellite"

targetNamespace="http://example.com/satellite"xmlns="http://schemas.xmlsoap.org/wsdl/"xmlns:tns="http://example.com/satellite"xmlns:wsa=

"http://schemas.xmlsoap.org/ws/2004/03/addressing"xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/ws

rf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wsrpwsdl="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/w

srf-WS-ResourceLifetime-1.2-draft-01.xsd"xmlns:wsrlwsdl="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ResourceLifetime-1.2-draft-01.wsdl"xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

<wsdl:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl"

location="WS-ResourceProperties.wsdl" />

<wsdl:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.wsdl"

location="WS-ResourceLifetime.wsdl" />

<types><xsd:schema targetNamespace=

"http://example.com/satellite"xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:import namespace="http://schemas.xmlsoap.org/ws/2004/03/addressing"

schemaLocation="WS-Addressing.xsd" />

<xsd:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd"

schemaLocation="WS-ResourceLifetime.xsd" />

<xsd:element name="createSatellite"><xsd:complexType/>

</xsd:element>...

The WS-ResourceLifetime.wsdl file includes the definitions of messages such asDestroy and SetTerminationTime, while the WS-ResourceLifetime.xsd fileincludes the schema definitions for the CurrentTime and TerminationTimeelements, so we can simply reference them.

The resource properties document

In order to schedule the resource for later termination, we need to make sure thatCurrentTime and TerminationTime properties are part of the resource propertydocument, so we need to include them in the definition within the WSDL file:

...<xsd:element name="roll" type="xsd:float" /><xsd:element name="focalLength"

type="xsd:float" />




<xsd:element name="currentView"type="xsd:string" />

<xsd:element name="GenericSatelliteProperties">

<xsd:complexType><xsd:sequence>

<xsd:element ref="latitude" minOccurs="1"maxOccurs="1"/>

<xsd:element ref="longitude" minOccurs="1"maxOccurs="1"/>

<xsd:element ref="altitude" minOccurs="1"maxOccurs="1"/>

<xsd:element ref="pitch" minOccurs="1"maxOccurs="1"/>

<xsd:element ref="yaw" minOccurs="1"maxOccurs="1"/>

<xsd:element ref="roll" minOccurs="1"maxOccurs="1"/>

<xsd:element ref="focalLength"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="currentView"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="wsrl:CurrentTime"minOccurs="1" maxOccurs="1" />

<xsd:element ref="wsrl:TerminationTime"minOccurs="1" maxOccurs="1" />

<xsd:any/></xsd:sequence>

</xsd:complexType></xsd:element>

</xsd:schema>

</types>...

Now all we have to do is define the operations and add them to the binding.

The operations and binding

The various messages we're using, such as DestroyResponse andSetTerminationTimeRequest, are defined in the WS-ResourceLifetime.wsdl file,so we only need to reference them:

...<message name="CreateSatelliteRequest">

<part name="request" element="tns:createSatellite"/></message>

<message name="CreateSatelliteResponse"><part name="response" element="tns:createSatelliteResponse"/>

</message>

<portType name="SatellitePortType"wsrp:ResourceProperties="tns:GenericSatelliteProperties">

...<operation name="removeTarget">

<input message="wsrpwsdl:SetResourcePropertiesRequest"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/SetResourceProperty"/>

<output message="wsrpwsdl:SetResourcePropertiesResponse"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/SetResourcePropertyResponse"/>

</operation>




<operation name="destroySatellite"><input message="wsrlwsdl:DestroyRequest"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceLifetime/Destroy"/>

<output message="wsrlwsdl:DestroyResponse"wsa:Action="http://docs.oasis-open.org/wsr

f/2004/06/WS-ResourceLifetime/DestroyResponse"/></operation>

<operation name="renewSatellite"><input message=

"wsrlwsdl:SetTerminationTimeRequest"wsa:Action="http://docs.oasis-open.org/wsr

f/2004/06/WS-ResourceLifetime/SetTerminationTime"/><output message=

"wsrlwsdl:SetTerminationTimeResponse"wsa:Action="http://docs.oasis-open.org/wsrf/200

4/06/WS-ResourceLifetime/SetTerminationTimeResponse"/></operation>

</portType>

<binding name="SatelliteSoapBinding"type="tns:SatellitePortType">

<soap:binding style="document"transport="http://schemas.xmlsoap.org/soap/http"/>...<operation name="removeTarget">

<input><soap:body use="literal"/>

</input><output>

<soap:body use="literal"/></output>

</operation><operation name="destroySatellite">


</input><output>


</operation><operation name="renewSatellite">


</input><output>


</operation></binding>

<service name="SatelliteService"><port name="SatellitePort"

binding="tns:SatelliteSoapBinding"><soap:address location=

"http://example.com/satellite"/></port>

</service>

</definitions>

Now we're ready to handle the immediate or scheduled destruction of resources.One place that ability comes in handy is in the management of WS-ServiceGroups.




Section 5. WS-ServiceGroup

What we're going to accomplish

In this section, we're going to look at the concept of ServiceGroups, which enableus to group together Web services and WS-Resources according to various rules.

We'll start by creating a new ServiceGroup and determining its membership rules.We'll then create a new WS-Resource and add it to the new ServiceGroup. Fromthere, we'll look at two ways to find out about the membership of a ServiceGroup.

In WS-ServiceGroups and the WSDL file, we'll look at some slightly more advancedways of integrating these actions into your WSDL file.

Let's start by finding out just what a ServiceGroup really is.

ServiceGroups

Once an application gets sufficiently large and complex, any number of reasons forgrouping resources together start to come into focus. You might want to limit accessbased on a user's or a service's role, or perhaps you want to provide a registry ofavailable services, or alternatives for a single service.

Whatever the reason, WSRF handles the problem through the use ofServiceGroups. A ServiceGroup is a WS-Resource that groups togetherpointers to other WS-Resources and to plain Web services.

Let's look at that again.

A ServiceGroup is a WS-Resource. That means a couple of things to us. First, itmeans that the ServiceGroup is a combination of a Web service with a statefulresource. In this case, the stateful resource is the group of entries theServiceGroup contains, and because it's a WS-Resource, that group of entries isrepresented by the ServiceGroup's resource property document.

It also means the ServiceGroup is identified by an endpoint reference by which wecan refer to it and that we can perform the same operations on a ServiceGroupthat we can perform on any other WS-Resource, such as creating or destroying it, oraccessing its properties.

Create the ServiceGroup

The first step in using a ServiceGroup is to create it. Because a ServiceGroupis just a WS-Resource, we'll create it just as we created every other WS-Resource --




with a Create message:



<createSatGroupxmlns="http://example.com/satellite"/>


and as before, the response includes the endpoint reference for the newWS-Resource:



<createSatGroupResponsexmlns="http://example.com/satellite">





<sat:SatGroupId>SATGRP3

</sat:SatGroupId></wsa:ReferenceProperties>

</wsa:EndpointReference></createSatGroupResponse>


OK -- so what do we actually have? Up to now, we've always started by defining theresource property document for a WS-Resource, but we didn't do that here becauseit's already been defined for us, as you'll see next.

ServiceGroup ResourceProperties

The resource property document for a ServiceGroup is defined in theWS-ServiceGroup.wsdl file, so we don't have to do that. In practice, the actualdocument looks something like this:

<wssg:ServiceGroupRP><wssg:MembershipContentRule

MemberInterface="sat:AuditedSatellitePortType" /><wssg:MembershipContentRule

MemberInterface="sat:CounterPortType"ContentElements="sat:audited" />

<wssg:MembershipContentRuleContentElements="sat:approvedBy" />

<wssg:Entry>...</wssg:Entry><wssg:Entry>...</wssg:Entry>

</wssg:ServiceGroupRP>




We'll talk about Entry elements in a minute, in ServiceGroup Entry elements. We'llstart with the MembershipContentRule elements. These elements define thecriteria a ServiceGroupEntry must meet before it can be added to theServiceGroup.

The MemberInterface attribute lists the portTypes that must be implemented byany service in the ServiceGroup. The portType, remember, is defined in theservice's WSDL file. We'll see more about implementing them in Implementingmultiple portTypes.

The second attribute, ContentElements, specifies elements that must be includedin the ServiceGroupEntry's Content element. Let's see more about that as welook at the ServiceGroupEntry.

ServiceGroupEntries

A ServiceGroupEntry is also a WS-Resource, so it also has a resource propertydocument that defines its state and a WS-Address that identifies it. It defines arelationship between a ServiceGroup and a service, and includes optional content,so the resource property document looks something like this:

<wssg:ServiceGroupEntryRP><wssg:ServiceGroupEPR>





<sat:SatGroupId>SATGRP3

</sat:SatGroupId></wsa:ReferenceProperties>

</wsa:EndpointReference></wssg:ServiceGroupEPR><wssg:MemberEPR>

<wsa:EndpointReference xmlns:wsa=http://www.w3.org/2005/02/addressing"

xmlns:sat="http://example.org/satelliteSystem">

<wsa:Address>http://example.com/satellite

</wsa:Address><wsa:ReferenceProperties>



</wsa:EndpointReference></wssg:MemberEPR><wssg:Content>

<sat:approvedBy>BossManBing

</sat:approvedBy></wssg:Content>

</wssg:ServiceGroupEntryRP>

The ServiceGroupEPR is the endpoint reference for the ServiceGroup, while the




MemberServiceEPR refers to the actual Web service or WS-Resource to which theServiceGroupEntry refers.

The Content element is additional information that may be included in theServiceGroupEntry. In this case, we've added an approval code that indicatesthat the service may be added to the group even though it doesn't implement theCounterPortType or AuditedSatellitePortType portTypes.

ServiceGroup Entry elements

Now we can come back to the Entry elements in the ServiceGroup's resourceproperty document. In this case, each entry identifies the ServiceGroupEntryresource and provides a pointer to the actual service, so the ServiceGroup'sresource property document looks something like this:

<wssg:ServiceGroupRP><wssg:MembershipContentRule

MemberInterface="sat:AuditedSatellitePortType" /><wssg:MembershipContentRule

MemberInterface="sat:CounterPortType"ContentElements="sat:audited" />


<wssg:Entry><wssg:ServiceGroupEntryEPR>





<sat:SatGroupEntryId>SATGRPENTRY28981

</sat:SatGroupEntryId></wsa:ReferenceProperties>

</wsa:EndpointReference></wssg:ServiceGroupEntryEPR><wssg:MemberServiceEPR>


ttp://www.w3.org/2005/02/addressing"xmlns:sat=





</wsa:EndpointReference></wssg:MemberServiceEPR><wssg:Content>



</wssg:Entry><wssg:Entry>

<wssg:ServiceGroupEntryEPR>





http://www.w3.org/2005/02/addressing"xmlns:sat=







http://www.w3.org/2005/02/addressing"xmlns:sat=








</wssg:Entry></wssg:ServiceGroupRP>

The ServiceGroupEntryEPR points to the ServiceGroupEntry object we sawin the previous panel, ServiceGroupEntries, while the MemberServiceEPR refers tothe actual service or WS-Resource added to the ServiceGroup. The Contentelement shows the Content element from the ServiceGroupEntry.

Getting back to our example, however, we've just created this ServiceGroup, sowe'll need to add all this information, starting with the MembershipContentRules.

Adding MembershipContentRules

Once we've created a ServiceGroup, we can add one or moreMembershipContentRules. Because they're part of the ServiceGroup'sresource property, we can add each one with an Insert message:


xmlns:sat="http://example.org/satelliteSystem"xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wssg=""http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ServiceGroup-1.2-draft-01.xsd"><SOAP-ENV:Header>





ceProperties/SetResourceProperties</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">

http://example.com/satellite</wsa:To><sat:SatGroupId>SATGRP3</sat:SatGroupId>


<wsrp:SetResourcePropertiesxmlns:satProp="http://example.com/satellite">

<wsrp:Insert><wssg:MembershipContentRule

MemberInterface="sat:AuditedSatellitePortType" />

</wsrp:Insert><wsrp:Insert>

<wssg:MembershipContentRuleMemberInterface="sat:CounterPortType"ContentElements="sat:audited" />

</wsrp:Insert><wsrp:Insert>


</wsrp:Insert>

</wsrp:SetResourceProperties></SOAP-ENV:Body>


Here, we've addressed the message to the ServiceGroup WS-Resource andadded properties that match the rules we saw in ServiceGroup ResourceProperties.The server returns a SetResourcePropertiesResponse message thatacknowledges the change:



6/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"><SOAP-ENV:Header>


ceProperties/SetResourcePropertiesResponse</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">



<wsrp:SetResourcePropertiesResponse></wsrp:SetResourcePropertiesResponse>


Now the ServiceGroup itself is ready, so we can start adding entries.

Adding a new entry

In order to add an entry to the ServiceGroup, we'll need the endpoint reference forthe service or WS-Resource to add. We'll also need any relevant Content. Forexample, we can add satellite SAT8557 to the ServiceGroup:






6/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wssg=""http://docs.oasis-open.org/wsrf/2004/0


<wsa:Action>http://docs.oasis-open.org/wsrf/2004/06/WS-ServiceGroup/Add




<wssg:Add><wssg:MemberEPR>





</wssg:MemberEPR><wssg:Content>



</wssg:Add></SOAP-ENV:Body>


Here, we're specifying the endpoint reference for the service to add and any requiredContent. You can also add the InitialTerminationTime element to specify aTerminationTime for the resulting ServiceGroupEntry.

In response, the server sends the endpoint reference for the newServiceGroupEntry:



6/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"><SOAP-ENV:Header>

<wsa:Action>http://docs.oasis-open.org/wsrf/2004/06/WS-Servi

ceGroup/AddResponse</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">



<wsrp:AddResponse></wsa:EndpointReference>




</sat:SatGroupEntryId>




</wsa:ReferenceProperties></wsa:EndpointReference>

</wsrp:AddResponse></SOAP-ENV:Body>


We can add as many resources as we want, as long as they don't violate any of theMembershipContentRules.

Retrieving a ServiceGroupEntry

At this point, we have added the MembershipContentRules and one or moreentries to the ServiceGroup, so the resource property document looks like it did inServiceGroup Entry elements. Now let's look at pulling the information back out.

For example, say we want to do some star counting. The ServiceGroup contains anumber of WS-Resources we can use. If we only want one, the simplest way to get itis to use a GetResourceProperty message:



srf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wssg="http://docs.oasis-open.org/wsrf/2004/06/w

srf-WS-ServiceGroup-1.2-draft-01.xsd"><SOAP-ENV:Header>


ceProperties/GetResourceProperty</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">



<wsrp:GetResourceProperty>wssg:Entry

</wsrp:GetResourceProperty></SOAP-ENV:Body>


The response contains a single Entry element:


xmlns:sat="http://example.org/satelliteSystem"xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:wsrp=

"http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd">

<SOAP-ENV:Header><wsa:Action>

http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/GetResourcePropertyResponse







<wsrp:GetResourcePropertyResponse><wssg:Entry>

<wssg:ServiceGroupEntryEPR><wsa:EndpointReference

xmlns:wsa="http://www.w3.org/2005/02/addressing"

xmlns:sat="http://example.org/satelliteSystem"><wsa:Address>














</wssg:Entry></wsrp:GetResourcePropertyResponse>


That element includes the MemberServiceEPR, which is the endpoint reference forthe service or WS-Resource. Once we have that, we can interact with it just as wedid in Part 1. It makes no difference whether we received the endpoint referencefrom a CreateResponse or a GetResourcePropertyResponse. We have anendpoint reference, so we can interact with the service or WS-Resource itrepresents.

Retrieving multiple entries

In Part 1, we used the QueryResourceProperties message to query acrossproperties, but we can also use it to retrieve multiple properties with the same name.For example, we can retrieve all of the Entry elements for the ServiceGroup:



6/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wssg="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ServiceGroup-1.2-draft-01.xsd">






<SOAP-ENV:Header><wsa:Action>

http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/QueryResourceProperties




<wsrp:QueryResourceProperties><wsrp:QueryExpression

Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">

/*/Entry</wsrp:QueryExpression>

</wsrp:QueryResourceProperties></SOAP-ENV:Body>


The response includes all of the Entry properties:



6/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wssg="http://docs.oasis-open.org/wsrf/2004/0



ceProperties/QueryResourcePropertiesResponse</wsa:Action><wsa:To SOAP-ENV:mustUnderstand="1">



<wsrp:GetResourcePropertyResponse><wssg:Entry>


xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:sat=






<wsa:EndpointReferencexmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:sat=




</sat:SatelliteId>




</wsa:ReferenceProperties></wsa:EndpointReference>

</wssg:MemberServiceEPR><wssg:Content>



</wssg:Entry><wssg:Entry>


xmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:sat=






<wsa:EndpointReferencexmlns:wsa="http://www.w3.org/2005/02/addressing"xmlns:sat=








</wssg:Entry></wsrp:QueryResourcePropertiesResponse>


We could also use the XPath expression to limit the Entrys retrieved. For example,we could retrieve only those with an audited element. Once we have the response,we can use our client application to look through each Entry and interact with theservice represented by each MemberServiceEPR.

Removing ServiceGroupEntries and ServiceGroups

Once we've added a service to the ServiceGroup, how do we remove it? Theanswer lies in the ServiceGroupEntry and the fact that it's a WS-Resource. Toremove a service from the ServiceGroup, simply retrieve the endpoint referencefor ServiceGroupEntry and use it to send a Destroy message. In this case,you're only destroying the link between the resource and the group. If you destroythe resource, however, you should also destroy any ServiceGroupEntry objects




that refer to it.

Similarly, if you destroy the ServiceGroup, you should also destroy all of theServiceGroupEntry resources it contains.

Now let's see how all of this translates into a WSDL file.

Section 6. WS-ServiceGroups and the WSDL file

What we can do with WSDL files

You already know that a WSDL file describes a Web service. So far, we've used theWSDL file to define messages and to use messages defined in other WSDL files.We then took those messages, and created operations and portTypes, then wetook the portTypes and used them as the basis for bindings to create portswithin services (see Figure 1).

Figure 1. The process so far

In this section, we're going to look at simplifying that process. First, we'll add thecapability to create the ServiceGroup. From there, we'll add the rest of thefunctions we used in WS-ServiceGroup.

Creating the ServiceGroup

The first step is to add the ability to create a ServiceGroup WS-Resource. We cando this much as we did it earlier when creating the satellite WS-Resources, exceptthat we don't have to define the resource property document because it's alreadybeen defined in WS-ResourceProperties.wsdl:



"http://schemas.xmlsoap.org/ws/2004/03/addressing"xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/wsr

f-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wsrpwsdl="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/wsr

f-WS-ResourceLifetime-1.2-draft-01.xsd"xmlns:wsrlwsdl="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ResourceLifetime-1.2-draft-01.wsdl"xmlns:wssg="http://docs.oasis-open.org/wsrf/2004/06/w




srf-WS-ServiceGroup-1.2-draft-01.xsd"xmlns:wssgwsdl="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ServiceGroup-1.2-draft-01.wsdl"xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">





<wsdl:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ServiceGroup-1.2-draft-01.wsdl"

location="WS-ServiceGroup.wsdl" />

<types><xsd:schema targetNamespace=

"http://example.com/satellite"xmlns:xsd="http://www.w3.org/2001/XMLSchema">



<xsd:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd"



</xsd:element>

<xsd:elementname="createSatelliteResponse">


<xsd:elementref="wsa:EndpointReference"/>

</xsd:sequence></xsd:complexType>

</xsd:element>

<xsd:element name="createSatGroup"><xsd:complexType/>

</xsd:element>

<xsd:elementname="createSatGroupResponse">




</xsd:element>

<xsd:element name="latitude"type="xsd:float" />

<xsd:element name="longitude"type="xsd:float" />

...</xsd:schema>

</types>

<message name="CreateSatelliteRequest"><part name="request"

element="tns:createSatellite"/></message>

<message name="CreateSatelliteResponse"><part name="response"




element="tns:createSatelliteResponse"/></message>

<message name="CreateSatGroupRequest"><part name="request"

element="tns:createSatGroup"/></message>

<message name="CreateSatGroupResponse"><part name="response"

element="tns:createSatGroupResponse"/></message>

<portType name="SatGroupPortType"wsrp:ResourceProperties="wssg:ServiceGroupRP">

<operation name="createSatGroup"><input message="tns:CreateSatGroupRequest"

wsa:Action="http://example.com/CreateSatGroup" /><output message="tns:CreateSatGroupResponse"

wsa:Action="http://example.com/CreateSatGroupResponse" /></operation>

</portType>


<operation name="createSatellite">...

Now all of that is familiar by now; we've created the messages, and a portTypethat references the wssg:ServiceGroup resource property document type.

But how do we add it to a service that already interacts with theGenericSatelliteProperties type?

Implementing multiple portTypes

If you haven't done much work with WSDL files, you may be wondering how we canpoint the service at a ServiceGroup, when it's already pointing at theGenericSatelliteProperties type. The answer lies in the function of theportType. It's more than just a definition but a type of interface. After all, it simplydefines operations, or functions, and their signature, or the data the operationexpects. The actual implementation depends on the binding.

Following through, we can add a binding for the new portType, then add it to theservice by adding on additional port:

...<operation name="renewSatellite">


</input><output>



<binding name="SatGroupSoapBinding"type="tns:SatGroupPortType">

<soap:binding style="document"




transport="http://schemas.xmlsoap.org/soap/http"/><operation name="createSatGroup">


</input><output>




binding="tns:SatelliteSoapBinding"><soap:address

location="http://example.com/satellite"/></port><port name="SatGroupPort"

binding="tns:SatGroupSoapBinding"><soap:address

location="http://example.com/satellite"/></port>

</service>

</definitions>

In this way, we are said to be implementing the portType . So far, this serviceimplements the SatellitePortType and SatGroupPortType portTypes.

We can use this ability to easily add the other capabilities laid out in thespecifications. But first, we'll add the ability to add resource properties to theServiceGroup.

Adding properties to the ServiceGroup

Adding the ability to add properties to the ServiceGroup is straightforwardbecause the SetResourcePropertyRequest andSetResourcePropertyResponse messages are already defined inWS-ResourceProperties.wsdl, so we can simply reference them:

...<message name="CreateSatGroupResponse">

<part name="response"element="tns:createSatGroupResponse"/>

</message>





<operation name="addMemberContentRules"><input message=

"wsrpwsdl:SetResourcePropertyRequest"wsa:Action="http://docs.oasis-open.org/wsr

f/2004/06/WS-ResourceProperties/SetResourceProperty" /><output message=

"wsrpwsdl:SetResourcePropertyResponse"wsa:Action="http://docs.oasis-open.org/wsrf/2004/0

6/WS-ResourceProperties/SetResourcePropertyResponse"/>




</operation>

</portType>...


<soap:binding style="document"transport="http://schemas.xmlsoap.org/soap/http"/>

<operation name="addMemberContentRules"><input>

<soap:body use="literal"/></input><output>


</operation>

<operation name="createSatGroup"><input>




...

We already have a portType that acts on the ServiceGroup, andWS-ResourceProperties.wsdl defines the appropriate messages, so we justneed to create the operations and implement them in the binding.

Retrieving ServiceGroup properties

Retrieving the resource properties of the ServiceGroup is even easier becauseWS-ServiceGroups.wsdl defines not only the messages but also a portType,complete with operations. That means all we need to do is create a binding and anew port for the service, as we've done so far:

... </operation></binding>

<binding name="ServiceGroupSoapBinding"type="wssg:ServiceGroup">

<operation name="GetResourceProperty"><input>








location="http://example.com/satellite"/></port>




<port name="ServiceGroupPort"binding="tns:ServiceGroupSoapBinding">

<soap:addresslocation="http://example.com/satellite"/>

</port>

</service>

</definitions>

We can go through the same process to add the ServiceGroupEntry andServiceGroupRegistration portTypes, the latter of which includes the Addoperation we used to create a new ServiceGroupEntry. (We'll see the full WSDLfile next.)

But there's an additional advantage to using these pre-defined portTypes. Thesimplify fault handling, as you'll see in the next section, WS-BaseFaults.

The final WSDL file

Here's the final WSDL file:



"http://schemas.xmlsoap.org/ws/2004/03/addressing"xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"xmlns:wsrp="http://docs.oasis-open.org/wsrf/2004/06/wsr

f-WS-ResourceProperties-1.2-draft-01.xsd"xmlns:wsrpwsdl="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl"xmlns:wsrl="http://docs.oasis-open.org/wsrf/2004/06/wsr

f-WS-ResourceLifetime-1.2-draft-01.xsd"xmlns:wsrlwsdl="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ResourceLifetime-1.2-draft-01.wsdl"xmlns:wssg="http://docs.oasis-open.org/wsrf/2004/06/wsr

f-WS-ServiceGroup-1.2-draft-01.xsd"xmlns:wssgwsdl="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ServiceGroup-1.2-draft-01.wsdl"xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">





<wsdl:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ServiceGroup-1.2-draft-01.wsdl"

location="WS-ServiceGroup.wsdl" />

<types><xsd:schematargetNamespace="http://example.com/satellite"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">



<xsd:import namespace=




"http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceLifetime-1.2-draft-01.xsd"



</xsd:element>

<xsd:elementname="createSatelliteResponse">




</xsd:element>

<xsd:element name="createSatGroup"><xsd:complexType/>

</xsd:element>

<xsd:elementname="createSatGroupResponse">




</xsd:element>

<xsd:element name="latitude"type="xsd:float" />

<xsd:element name="longitude"type="xsd:float" />

<xsd:element name="altitude"type="xsd:float" />

<xsd:element name="pitch"type="xsd:float" />

<xsd:element name="yaw"type="xsd:float" />

<xsd:element name="roll"type="xsd:float" />

<xsd:element name="focalLength"type="xsd:float" />

<xsd:element name="currentView"type="xsd:string" />

<xsd:elementname="GenericSatelliteProperties">


<xsd:element ref="latitude"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="longitude"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="altitude"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="pitch"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="yaw"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="roll" minOccurs="1"maxOccurs="1"/>

<xsd:element ref="focalLength"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="currentView"minOccurs="1" maxOccurs="1"/>

<xsd:element ref="wsrl:CurrentTime"minOccurs="1" maxOccurs="1" />

<xsd:elementref="wsrl:TerminationTime" minOccurs="1" maxOccurs="1" />

<xsd:any/>





</xsd:element>

</xsd:schema>

</types>

<message name="CreateSatelliteRequest"><part name="request"

element="tns:createSatellite"/></message>

<message name="CreateSatelliteResponse"><part name="response"

element="tns:createSatelliteResponse"/></message>

<message name="CreateSatGroupRequest"><part name="request"

element="tns:createSatGroup"/></message>

<message name="CreateSatGroupResponse"><part name="response"

element="tns:createSatGroupResponse"/></message>





<operation name="addMemberContentRules"><input message=

"wsrpwsdl:SetResourcePropertyRequest"wsa:Action="http://docs.oasis-open.org/wsr

f/2004/06/WS-ResourceProperties/SetResourceProperty"/><output message=

"wsrpwsdl:SetResourcePropertyResponse"wsa:Action="http://docs.oasis-open.org/wsrf/200

4/06/WS-ResourceProperties/SetResourcePropertyResponse"/></operation>

</portType>


<operation name="createSatellite"><input message="tns:CreateSatelliteRequest"

wsa:Action="http://example.com/CreateSatellite" /><output message="tns:CreateSatelliteResponse"

wsa:Action="http://example.com/CreateSatelliteResponse" />

</operation>

<operation name="getAltitude"><input message=

"wsrpwsdl:GetResourcePropertyRequest"wsa:Action="http://docs.oasis-open.org/wsr

f/2004/06/WS-ResourceProperties/GetResourceProperty"/><output message=

"wsrpwsdl:GetResourcePropertyResponse"wsa:Action="http://docs.oasis-open.org/wsrf/200

4/06/WS-ResourceProperties/GetResourcePropertyResponse"/></operation>

<operation name="getOrientation">




<input message="wsrpwsdl:GetMultipleResourcePropertiesRequest"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/GetMultipleResourceProperties"/>

<output message="wsrpwsdl:GetMultipleResourcePropertiesResponse"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/GetMultipleResourcePropertiesResponse"/>

</operation>

<operation name="checkOrientation"><input message=

"wsrpwsdl:QueryResourcePropertiesRequest"wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-Re

sourceProperties/QueryResourceProperties"/><output message=

"wsrpwsdl:QueryResourcePropertiesResponse"wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-Re

sourceProperties/QueryResourcePropertiesResponse"/></operation>

<operation name="addTarget"><input message=

"wsrpwsdl:SetResourcePropertiesRequest"wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceProperties/SetResourceProperty"/>



</operation>

<operation name="moveToTarget"><input message=




</operation>

<operation name="removeTarget"><input message=




</operation>

<operation name="destroySatellite"><input message="wsrlwsdl:DestroyRequest"

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/WS-ResourceLifetime/Destroy"/>

<output message="wsrlwsdl:DestroyResponse"wsa:Action="http://docs.oasis-open.org/wsr

f/2004/06/WS-ResourceLifetime/DestroyResponse"/></operation>

<operation name="renewSatellite"><input message=

"wsrlwsdl:SetTerminationTimeRequest"wsa:Action="http://docs.oasis-open.org/wsr

f/2004/06/WS-ResourceLifetime/SetTerminationTime"/><output message=

"wsrlwsdl:SetTerminationTimeResponse"wsa:Action="http://docs.oasis-open.org/wsrf/200

4/06/WS-ResourceLifetime/SetTerminationTimeResponse"/></operation>




</portType>

<binding name="SatelliteSoapBinding"type="tns:SatellitePortType">

<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

<operation name="createSatellite"><input>



</operation><operation name="getAltitude">


</input><output>


</operation><operation name="getOrientation">


</input><output>


</operation><operation name="checkOrientation">


</input><output>


</operation><operation name="addTarget">


</input><output>


</operation><operation name="moveToTarget">


</input><output>


</operation><operation name="removeTarget">


</input><output>


</operation><operation name="destroySatellite">


</input><output>


</operation><operation name="renewSatellite">


</input>




<output><soap:body use="literal"/>

</output></operation>

</binding>


<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

<operation name="addMemberContentRules"><input>



</operation>

<operation name="createSatGroup"><input>




<binding name="ServiceGroupSoapBinding"type="wssg:ServiceGroup">





<binding name="ServiceGroupEntrySoapBinding"type="wssg:ServiceGroupEntry">





<binding name="ServiceGroupRegistrationSoapBinding"type="wssg:ServiceGroupRegistration">

<operation name="Add"><input>



</operation><operation name="GetResourceProperty">


</input><output>










location="http://example.com/satellite"/></port><port name="ServiceGroupPort"

binding="tns:ServiceGroupSoapBinding"><soap:address

location="http://example.com/satellite"/></port><port name="ServiceGroupEntryPort"

binding="tns:ServiceGroupEntrySoapBinding"><soap:address

location="http://example.com/satellite"/></port><port name="ServiceGroupRegistrationPort"

binding="tns:ServiceGroupRegistrationSoapBinding"><soap:address location=

"http://example.com/satellite"/></port>

</service>

</definitions>

Section 7. WS-BaseFaults

What's a fault?

Wouldn't it be nice if everything always worked exactly right the first time and everytime?

It'd be nice to win the lottery, too.

Sure, some people do actually win the lottery, but chances are your applications arenot going to become 100 percent problem-free anytime soon. Particularly in anenvironment in which you have multiple systems trying to access objects for whichstate has been, essentially, simulated in a stateless environment, there are going tobe problems.

Clients are going to request WS-Resources that don't exist. They're going to try andadd them to ServiceGroups for which they don't qualify. They're going to createXPath expressions that aren't really XPath expressions.

It will happen. And you'll have to deal with it.

That's where faults come in.




Faults are to Web services what exceptions are to Java or C++. They're situationsthat may or may not be actual errors -- although they usually are -- but that need tobe handled outside the normal flow of the application.

Faults in WSDL

In a WSDL file, faults are defined in the same way as other messages, and specifiedin the operation to which they're relevant. Consider:

...<wsdl:message name=

"UnableToSetTerminationTimeFault"><wsdl:part

element="wsrl:UnableToSetTerminationTimeFault"name="UnableToSetTerminationTimeFault"/>

</wsdl:message><wsdl:message name=

"TerminationTimeChangeRejectedFault"><wsdl:part

element="wsrl:TerminationTimeChangeRejectedFault"name="TerminationTimeChangeRejectedFault"/>

</wsdl:message><wsdl:portType name="ScheduledResourceTermination"

wsrp:ResourceProperties ="wsrl:ScheduledResourceTerminationRP">

<wsdl:operation name="SetTerminationTime"><wsdl:input message=

"wsrlw:SetTerminationTimeRequest"wsa:Action="http://docs.oasis-open.org/wsr

f/2004/06/wsrf-WS-ResourceLifetime/SetTerminationTime"/><wsdl:output message=

"wsrlw:SetTerminationTimeResponse"wsa:Action="http://docs.oasis-open.org/wsrf/2004/0

6/wsrf-WS-ResourceLifetime/SetTerminationTimeResponse"/><wsdl:fault message=

"wsrlw:UnableToSetTerminationTimeFault"name="UnableToSetTerminationTimeFault"/>

<wsdl:fault message="wsrlw:ResourceUnknownFault"

name="ResourceUnknownFault"/><wsdl:fault message=

"wsrlw:TerminationTimeChangeRejectedFault"name="TerminationTimeChangeRejectedFault"/>

</wsdl:operation></wsdl:portType>

This small excerpt from WS-ResourceLifetime.wsdl shows the definition of twofault messages, UnableToSetTerminationTimeFault andTerminationTimeChangeRejectedFault, which can potentially be returnedinstead of the typically SetTerminationTimeResponse, should something gowrong when processing a SetTerminationTimeResponse. We can define asmany faults as we want for a particular operation.

WS-BaseFaults

When you're dealing with an application written by someone else, the last thing youwant to have to do is try to read their mind when it comes to errors. You want to beable to interpret them immediately and move on. To facilitate that in a WSRF-basedoperation, the WS-BaseFaults specification defines a basic format for standard




errors, then provides a way to extend that basic format for more specific purposeswithout losing the original structure.

The central concept is that of a BaseFault. A BaseFault looks something likethis:

<BaseFault><Timestamp>2005-2-15T03:24:57</Timestamp><OriginatorReference>

<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/02/addressing"

xmlns:sat="http://example.org/satelliteSystem"><wsa:Address>




</wsa:EndpointReference></OriginatorReference><ErrorCode dialect=

"http://www.example.com/NeutronErrorMessages">PolarityUnchangedError

</ErrorCode><Description>

Unable to reverse the polarity of the neutron flow!</Description>

</BaseFault>

All of these values are optional, except the Timestamp, which indicates when thefault actually happened. The OriginatorReference is the endpoint reference ofthe Web service generating the fault, and the ErrorCode and Descriptiondescribe the actual problem. The dialect attribute is a URL that enables us tospecify how to interpret the ErrorCode. The specification mentions mapping errorcodes to POSIX errno messages, for example.

We can also add a FaultCause element that includes another BaseFault. Thisenables us to chain errors together.

Creating new faults

You can use a BaseFault as is, letting the client application parse the informationand determine the problem, but it's much more common to extend the BaseFaultto create more specific faults. We accomplish this by using an XML schema tocreate the new type. We could, for example, create a newSatelliteNotRespondingFault like so:

<xsd:complexTypename="SatelliteNotRespondingFaultType">

<xsd:complexContent><xsd:extension base="wsbf:BaseFaultType">

<xsd:sequence><xsd:element name="LastReboot"

type="xsd:dateTime" /></xsd:sequence>

</xsd:extension></xsd:complexContent>




</xsd:complexType>

<xsd:element name="SatelliteNotRespondingFault"type="wsrl:SatelliteNotRespondingFaultType"/>

This enables us to return a fault such as:

<SatelliteNotRespondingFault><Timestamp>2005-2-15T03:24:57</Timestamp><Description>

Cannot connect to satellite</Description><LastReboot>2005-2-10T09:43:02</LastReboot>

</SatelliteNotRespondingFault>

In this case, we've provided extra information in the form of the LastRebootelement, but just the fact that this is a SatelliteNotRespondingFault prettymuch gives the whole story to the client. In fact, most of the faults defined by WSRFspecifications extend the BaseFault just enough to create a newly named fault anddon't add any additional information. Just knowing what kind of fault has beenreturned provides all the necessary information.

Let's look at the different types of faults defined by the WSRF specifications.

WSRF faults: WS-ResourceProperties

The WS-ResourceProperties specification defines the following faults, to be sent inresponse to the appropriate events:

• ResourceUnknownFault: This fault applies to all of the variousoperations and indicates that the message refers to an endpoint referencethe Web service doesn't recognize.

• InvalidResourcePropertyQName: When requesting a property orproperties, this fault indicates that the client is trying to get or set aResourceProperty that doesn't exist on the WS-Resource in question.

• InvalidSetResourcePropertiesRequestContent: In this case, thedata that was sent in the SetResourcePropertyRequest doesn'tconform to the schema for the appropriate resource property document.

• UnableToModifyResourceProperty: In this case, the resourceproperty the client is attempting to set is read-only.

• SetResourcePropertyReqestFailed: This is a general errorindicating that the server was unable to add or change the resourceproperty.

• UnknownQueryExpressionDialect: When querying resourceproperties, this fault indicates that the client is attempting to evaluate aquery in a dialect the service doesn't recognize. At this time, XPath V1.0and V2.0 are defined.




• InvalidQueryExpression: In this case, the query doesn't conform tothe specified dialect.

• QueryEvaluationError: This is a general error indicating somethingwent wrong while processing the query.

WSRF faults: WS-ResourceLifetime

The WS-ResourceLifetime specification defines four faults that pertain to theimmediate or scheduled destruction of a WS-Resource:

• ResourceUnknownFault: As in WS-ResourceProperties, this faultindicates that the client is attempting to access a WS-Resource thatdoesn't exist or that the Web service doesn't know about.

• ResourceNotDestroyedFault: This fault indicates that theWS-Resource wasn't destroyed. The actual error message may give moreinformation as to why.

• UnableToSetTerminationTimeFault: This is a general faultindicating the service couldn't make the requested change.

• TerminationTimeChangeRejectedFault: In this case, the client isattempting to make a change that doesn't conform with the internal rulesof the WS-Resource.

WSRF faults: WS-ServiceGroup

The WS-ServiceGroup specification defines three faults:

• UnsupportedMemberInterfaceFault: This fault indicates that theservice the client is attempting to add doesn't implement any of therequired portTypes.

• ContentCreationFailedFault: In this case, the request to add aWeb service doesn't have the appropriate Content element, as definedin the MembershipContentRules for the ServiceGroup.

• AddRefusedFault: This is a general fault indicating that the resourcecouldn't be added.

Section 8. Summary




Summary

This tutorial has discussed some of the aspects of working with WS-Resources,such as destroying, expiring, and grouping them. These activities are covered in theWS-ResourceLifetime and WS-ServiceGroup specifications. The tutorial alsodiscussed the management of faults through the creation and extension ofBaseFaults, as discussed in the WS-BaseFaults specification.

The tutorial presented the following topics:

• A brief review of WS-Resources and WS-ResourceProperties

• Immediate destruction of WS-Resources

• Scheduled expiration of WS-Resources

• The creation and management of ServiceGroups

• The addition and removal of ServiceGroupEntries

• Integrating information from externally defined WSDL files byimplementing portTypes

• The creation and customization of fault messages

• Customized fault messages defined in WSRF




Resources

• This tutorial is Part 2 in a series on Understanding WSRF. Be sure to read Part1: Using WS-ResourceProperties, Part 3: Publish-Subscribe withWS-Notification and Part 4: Using the Java Core WSRF classes.

• Download part2WSRF.wsdl for the complete WSDL file covered in this tutorial.

• The main location for WSRF documentation is at The Globus Alliance Web site,but the latest specifications can be found at OASIS.

• Check out The WS-Resource Framework at Globus.org.

• Learn more about Web Services Resource Properties 1.2 at OASIS.org.

• WS-ResourceLifetime (WSRF-RL)

• WS-ServiceGroup (WSRF-SG)

• WS-Base Faults (WSRF-BF)

• The actual recommdendations for SOAP and WSDL are maintained by theWorld Wide Web Consortium, and IBM is one of the companies that proposedWS-Addressing.

• Read "Merging grids and Web services" for more information.

• Be sure to read "Using WSDL in SOAP applications."

• "Deploying Web services with WSDL: Part 1" offers an introduction to Webservices.

• Read "Discover SOAP encoding's impact on Web service performance" toimprove performance by changing your encoding style.

• "The hidden impact of WS-Addressing on SOAP" looks at the current state ofthe "Web services revolution."

• You can find more information on the developerWorks SOA and Web serviceszone.

• The XML and XPath V1.0, XPath V2.0, and XML Schema recommendations aremaintained by the World Wide Web Consortium.

• Read "A survey of XML standards."

• developerWorks offers tutorials titled "Introduction to XML" and "Get started withXPath."

• You can also find more resources in the developerWorks XML zone.

About the author

Babu Sundaram





part2WSRF.wsdl


http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrf

http://www.w3.org/2002/ws/#drafts

http://www.w3.org/TR/wsdl

http://www.w3.org

http://www.w3.org

http://www.ibm.com/developerworks/library/specification/ws-add/

http://www.ibm.com/developerworks/grid/library/gr-web/

http://www.ibm.com/developerworks/webservices/library/ws-soap/index.html

http://www.ibm.com/developerworks/webservices/library/ws-intwsdl/index.html

http://www.ibm.com/developerworks/webservices/library/ws-soapenc/index.html

http://www.ibm.com/developerworks/webservices/library/ws-address.html

http://www.ibm.com/developerworks/webservices/

http://www.ibm.com/developerworks/webservices/

http://www.w3.org/TR/2004/REC-xml-20040204/

http://www.w3.org/TR/xpath

http://www.w3.org/XML/Query#specs

http://www.w3.org/XML/Schema#dev

http://www.w3.org

http://www.ibm.com/developerworks/xml/library/x-stand1.html

http://www.ibm.com/developerworks/edu/x-dw-xmlintro-i.html

http://www.ibm.com/developerworks/edu/x-dw-xxpath-i.html

http://www.ibm.com/developerworks/edu/x-dw-xxpath-i.html

http://www.ibm.com/developerworks/xml/


Babu Sundaram has been actively involved with grid computing research since theearly days of Globus Toolkit. He was part of the Globus implementation team duringhis internship at Argonne National Labs. He holds a bachelor's degree in mechanicalengineering and master's degree in computer science. He is pursuing hisdoctoral-level research in computer science at the University of Houston. He haspublished many papers in various conferences and grid-related workshops, and alsoco-authored sections of a few books about grid computing. He loves teaching and, attimes, works as lecturer teaching courses on Web services and aspects of gridcomputing. He welcomes feedback and can be reached at [email protected].



mailto:[email protected]


Documents

Understanding WSRF, Part 2: Working with WS ... › developerworks › education › gr-wsr… · See Resources to download the complete WSDL file covered in this tutorial. Section