xmlxml.coverpages.org/wsdm-primer-muws-cd200602.doc · web viewthe local definitions next, we...

Web Services Distributed Management: MUWS PrimerCommittee Draft, February 24, 2006Document identifier:

wsdm-primer-muws-cd

Location:http://docs.oasis-open.org/wsdm/wsdm-primer-muws-cd.pdf

Editors:Bryan Murray, Hewlett-Packard <[email protected]>Kirk Wilson, Computer Associates <[email protected]>Mark Ellison, Ellison Software Consulting <[email protected]>

Abstract:The Web Services Distributed Management (WSDM) MUWS Primer provides an introduction to the WSDM MUWS specifications directed towards a wide audience of architects, developers, implementers and users. This primer does not provide a definitive specification of the WSDM. Rather, it is intended to provide an easily read and understood summary of the fundamentals for creating and using WSDM-compliant manageability consumers and manageable resources.

Status:This document is updated periodically on no particular schedule. Send comments to the editor.Committee members should send comments on this specification to the [email protected] list. Others should subscribe to and send comments to the [email protected] list. To subscribe, send an email message to [email protected] with the word "subscribe" as the body of the message.For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the WSDM TC web page (http://www.oasis-open.org/committees/wsdm/).The errata page for this specification is at http://docs.oasis-open.org/wsdm/wsdm-primer-cd-errata.pdf.

wsdm-primer-muws-cd February 24, 2006

Copyright © OASIS Open 2004-2006. All Rights Reserved. of 107

1

2

3

4

56

78

9101112

13141516171819

2021222324252627282930313233

1

2

http://www.oasis-open.org/committees/wsdm/

http://www.oasis-open.org/committees/wsdm/

mailto:[email protected]?body=subscribe

mailto:[email protected]





Table of Contents1 Introduction............................................................................................................................ 5

1.1 Namespaces......................................................................................................................... 52 Building a Manageable Resource..........................................................................................7

2.1 The Resource....................................................................................................................... 72.2 Exposing Resource Identity..................................................................................................7

2.2.1 The Resource Properties Document.............................................................................72.2.2 The WSDL Document...................................................................................................92.2.3 Example SOAP Messages..........................................................................................11

2.3 Adding a WSDM Capability................................................................................................132.3.1 Modifying the Resource Properties Document............................................................142.3.2 Examples of Description Capability Messages............................................................15

2.4 Manageability Characteristics.............................................................................................162.5 Adding Property Access Operations...................................................................................17

2.5.1 Modifying the WSDL Document..................................................................................172.5.2 Example of Property Access Operation Messages.....................................................21

2.6 Operational Status..............................................................................................................232.7 Metrics................................................................................................................................ 24

2.7.1 A Scenario for PDA Metrics.........................................................................................252.7.2 Metric Datatypes and Exposing Metrics......................................................................25

2.8 Extending a Capability........................................................................................................272.9 Adding Resource-specific Operations and Properties........................................................28

2.9.1 Adding Resource-specific Properties..........................................................................282.9.2 Adding Resource-specific operations..........................................................................28

2.10 Notifications...................................................................................................................... 292.10.1 Changes to the Resource Properties Document.......................................................302.10.2 Changes to the WSDL Document.............................................................................302.10.3 ManagementEvent Format........................................................................................31

2.10.3.1 Example..............................................................................................................................332.10.4 Creating a TopicSpace..............................................................................................34

2.10.4.1 Topics for Resource-Specific Metrics.................................................................................342.11 Building and Exposing a Metadata Document..................................................................35

2.11.1 Constructing PDA Device Metadata..........................................................................372.11.2 Metric Metadata.........................................................................................................39

2.11.2.1 PDA Resource-specific Metrics..........................................................................................402.11.2.2 Example PDA Resource Properties Document with Metrics..............................................42

2.12 State................................................................................................................................. 432.12.1 State Model Metadata...............................................................................................47

2.13 Advertising a Resource.....................................................................................................482.14 Operable Collections........................................................................................................49

3 Building Relationships..........................................................................................................523.1 WSDM Relationships and UML Associations.....................................................................52

3.1.1 Defining a Relationship Type.......................................................................................53



34

35363738394041424344454647484950515253545556575859606162

6364

6566676869

70717273747576

3

4

3.2 The Relationship Capability................................................................................................543.2.1 Relationships in the Resource Properties Document..................................................543.2.2 Querying Relationships by Type: WSDL Modifications...............................................55

3.2.2.1 An Example using QueryingRelationshipsByType...............................................................563.2.3 Relationship Events.....................................................................................................573.2.4 Relationship Metadata.................................................................................................593.2.5 Guidelines for Supporting the Relationships Capability...............................................59

3.3 Accessing Relationships as WS-Resources.......................................................................603.3.1 Accessing a MUWS Relationships as a WS-Resource...............................................603.3.2 Treating Relationships as Standalone Resources.......................................................61

4 Managing MUWS Resources...............................................................................................634.1 Discovering Resources.......................................................................................................63

4.1.1 Explicit Configuration...................................................................................................634.1.2 Resource Advertisement and Registries.....................................................................63

4.1.2.1 UDDI.....................................................................................................................................644.1.2.2 ServiceGroup........................................................................................................................644.1.2.3 Relationship Registries.........................................................................................................64

4.1.3 Using The MUWS Relationship Capability..................................................................644.1.3.1 Discovering Resources from Relationships..........................................................................654.1.3.2 Monitoring Relationships......................................................................................................66

4.1.4 Summary..................................................................................................................... 664.2 Managing and Monitoring...................................................................................................67

4.2.1 Discovering Manageability Capabilities.......................................................................674.2.2 Using Manageability Capabilities.................................................................................67

4.2.2.1 Determining Resource Identity.............................................................................................674.2.2.2 Obtaining Description and State Information........................................................................694.2.2.3 Configuring the Manageable Resource................................................................................704.2.2.4 Querying and Traversing Relationships...............................................................................70

5 Further Considerations.........................................................................................................725.1 Defining a Taxonomy in WSDM..........................................................................................72

5.1.1 Steps for Constructing a Taxonomy............................................................................745.2 Alternate Means of Accessing Manageability.....................................................................745.3 FCAPS Discussion.............................................................................................................755.4 The Web Services Platform................................................................................................75

5.4.1 Initial Focus.................................................................................................................765.4.1.1 Properties.............................................................................................................................765.4.1.2 Meta Data.............................................................................................................................765.4.1.3 Addressing............................................................................................................................765.4.1.4 Notification............................................................................................................................775.4.1.5 Versioning.............................................................................................................................775.4.1.6 Security.................................................................................................................................775.4.1.7 Registration, Discovery and Location...................................................................................78

5.4.2 Future Focus...............................................................................................................785.4.2.1 Policy....................................................................................................................................785.4.2.2 Name Resolution..................................................................................................................785.4.2.3 Transaction...........................................................................................................................79



77787980

81828384858687888990919293

949596

979899100101102103104

105106107108109110111112113114115116117118

119120121122

5

6

5.4.2.4 Flow......................................................................................................................................795.4.2.5 Negotiation...........................................................................................................................80

6 References........................................................................................................................... 81Appendix A. Complete XML Documents.......................................................................................83Appendix B. Acknowledgments..................................................................................................103Appendix C. Revision History.....................................................................................................104Appendix D. Notices................................................................................................................... 107



123124

125126127128129

130

7

8

1 IntroductionAfter reading this primer, the reader should be prepared to understand and implement the MUWS standard and the specification supporting the MUWS standard, such as WS-ResourceProperties [WS-ResourceProperties] and WS-BaseNotification [WS-BaseNotification]. The primary goal of the WSDM primer is to provide the reader with examples and to explain the use of the WSDM standards to achieve Information Technology (IT) management goals.

This primer addresses the experienced developer or architect wishing to learn how to construct the necessary XML documents related to MUWS, including XML schema [XML Schema], WSDL [WSDL], and SOAP [SOAP] messages supporting the MUWS message exchange patterns (MEPs). A basic familiarity with the MUWS and MOWS specifications is assumed. Explanations of concepts covered in the MUWS and MOWS specifications are generally not repeated in this document.

This document will provide concrete examples of how the necessary XML documents [XML] specified by MUWS are constructed. It helps the reader understand which elements must be included in a particular document in order to achieve a desired goal. While the WSDM specifications provide an abstract description of necessary XML documents, this primer provides concrete illustrations of those XML documents.

The reader should observe that neither the WSDM specifications nor this primer describe the physical, runtime construction of necessary XML documents as rendered within program code. Choosing an appropriate design and toolkit for the system hosting an implementation of the MUWS MEPs is beyond the scope of this primer.

Examples are developed throughout this primer of the following three main types of XML documents as used by MUWS:

XML representations of manageable resources described using XML Schema, as well as descriptions of the messages exchanged

Descriptions of the Message Exchange Patterns exposed by a manageability endpoint using WSDL

Examples of SOAP messages exchanged between a manageability consumer and the manageability endpoint of manageable resource

At this point, before continuing with this primer, the reader is encouraged to review the MUWS specification . Reading the MUWS specification at this point will help to fill-in some detail omitted from the preceding overview. Finally, reading the MUWS specification establishes a proper context for the remainder of this primer.

1.1 NamespacesCommon namespaces used throughout this primer are used with the following prefixes:

pda http://example.org/services/MyPdaDevice.xsd

pdaw http://example.org/services/MyPdaDevice.wsdl

pdae http://example.org/MyPdaTopics.xml

pda-rmd http://example.com/services/MyPdaDevice.rmd

relext http://example.org/services/GatewayRelationship.xsd



131132133134135136

137138139140141142

143144145146147

148149150151

152153

154155

156157

158159

160161162163

164165

9

10

muws-p1-xs http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd

muws-p2-xs http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd

muws-ev http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2-events.xml

exh http://example.org/services/localDefinitions.xsd

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

wsrf-rpw http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl

wsrf-bf http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-BaseFaults-1.2-draft-02.xsd

wsnt http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd

wsntw http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.wsdl

wstop http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd

rmd http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd

pbm http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-pbm.xsd

xs http://www.w3.org/2001/XMLSchema

w http://schemas.xmlsoap.org/wsdl

s http://schemas.xmlsoap.org/soap/envelope/

soapw http://schemas.xmlsoap.org/wsdl/soap/

wsa http://schemas.xmlsoap.org/ws/2005/08/addressing

Namespace declarations will not be provided in example code (XML) unless explicitly referred to in the text or is specific to that example. Please refer back to this table for the meaning of namespace prefixes. See Appendix A for an unabridged rendering of the example XML documents.



166167168169

170

11

12

2 Building a Manageable ResourceThis chapter of the primer illustrates how a set of features, including MUWS required properties, is provided for a manageable resource. This chapter also illustrates the message exchanges required to access the provided properties of a manageable resource.

In this chapter, we will add features to a manageability endpoint one step at a time. This step-wise approach is similar to how a developer would naturally implement and maintain the features of a manageability endpoint. Thus, the target namespace will not be changed for every section. By the conclusion of this chapter, will build up a complete implementation of a manageability endpoint. The final WSDL and schema documents as used for an example deployment are located in the Appendix of this primer.

2.1 The ResourceWe will use the same endpoint for all of our examples. Thus want to start with a name we can use in each example. We will use a PDA as our resource and use the name MyPdaDevice as the basis for names in our examples.

2.2 Exposing Resource IdentityThe Identity capability is the only required feature of a MUWS compliant manageability endpoint [MUWS Part 1]. To support the Identity capability a manageability endpoint implements the ResourceId property and the GetResourceProperty message exchange. Thus the simplest possible MUWS compliant manageability endpoint supports only the features of the Identity capability.

The MUWS specification requires the ResourceId property have a value that is unique across space and time. When different manageability consumers discover and identify resources in different ways, a unique value of the ResourceId property is useful to determine whether two endpoint references actually refer to the same manageable resource.

In a limited number of circumstances it may not be possible to define a unique and consistent value for the ResourceId property of a manageable resource. If this circumstance is present, then the CorrelatableProperties capability as defined in the MUWS specification may be used in determining whether two manageable resources discovered and identified by two different manageability consumers actually represent the same manageable resource.

In order to use the CorrelatableProperties capability it is necessary for the manageability endpoint to implement the GetResourceProperty message exchange as defined by the WS-ResourceProperties specification.

2.2.1 The Resource Properties DocumentIn the first step towards implementing a manageability endpoint we create a resource properties document schema for the resource properties to be supported. This schema is defined with a namespace under the control of the organization responsible for the schema. In our examples we assume that our organization controls the “example.org” domain. While it is not required, it is very handy if the schema document can be placed such that the namespace can be dereferenced. A namespace can be dereferenced if its URL can be used by a web browser to retrieve and view the schema document. For our example, we will place our schema document on the example.org server at the path “/services/MyPdaDevice.xsd”.

It is possible to just use the resource properties document already defined in MUWS part 1 for our simple first example. However, since we know we want to add additional capabilities to our



171172173174

175176177178179180

181182183184

185186187188189190

191192193194

195196197198199

200201202

203204205206207208209210211

212213

13

14

manageability endpoint for our resource in subsequent examples, we define our own resource properties document schema.

The ResourceId property is already defined in the MUWS schema within the IdentityPropertiesType complexType. An easy approach to achieve the right property reference is the following:

Create an empty complexType and sequence

Identify an element referring to the ResourceId property in the MUWS schema containing IdentityPropertiesType

Cut-and-paste the identified element into the empty complexType sequence created in step 1

This approach helps assure that any minOccurs and maxOccurs attributes are correctly defined.

By following this approach we can define the MyPdaDeviceProperties element. The name of the element can be whatever is appropriate for the type of resource and is not specified by MUWS. For our example, the schema appears as follows:

<xs:schema targetNamespace="http://example.org/services/MyPdaDevice.xsd"  elementFormDefault="qualified" attributeFormDefault="unqualified">



<xs:element name="MyPdaDeviceProperties"> <xs:complexType> <xs:sequence> <xs:element ref="muws-p1-xs:ResourceId"/> </xs:sequence> </xs:complexType> </xs:element>

</xs:schema>

Key aspects of our schema include:

the target namespace

the definition of XML namespace prefixes

the import of any foreign XML schemas

the local definitions

Next, we create one additional schema document that helps manageability consumers differentiate among representations of a resource.

In our example, we use a SOAP header as an aid in the differentiation of resource representations. Thus, we need to describe the SOAP header in an XML schema. By describing the resource selector element within a separate document and XML namespace we allow the same resource selector element to be used to select any resource, even if it is not a MyPdaDevice in the example.org domain. If instead, we had decribed the resource selector element within the MyPdaDeviceProperties schema, then we would find it awkward to use the same resource selector element to select resources of a type other than MyPdaDevice.

<xs:schema targetNamespace="http://example.org/services/localDefinitions.xsd" . . . .>

<xs:element name="ResourceDisambiguator" type="xs:anyURI"/>

</xs:schema>



214215

216217218

219

220221

222223

224

225226227

228229230231

232233

234235236237238239240241

242243

244

245

246

247

248

249250

251252253254255256257

258259260

261262

263264

15

16

2.2.2 The WSDL DocumentNow that we have a complete resource properties document schema we can define the WSDL document for the manageability endpoint in our simple example.

As described in the previous section for the resource properties document schema, we use a namespace within "example.org". Similar to the resource properties document schema, it is very handy to be able to dereference the namespace used in the WSDL to retrieve the actual WSDL document. Thus, we choose a target namespace we are able to derefernce.

Since we do not define any new operations for our simple manageable resource we do not need to describe any messages in our schema document. Our WSDL document simply references schemas as published with the WS-ResourceProperties specification to describe the appropriate message elements.

The entire WSDL document for our example appears as follows::

<w:definitions targetNamespace="http://example.org/services/MyPdaDevice.wsdl" . . .>

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

<w:types> <xs:schema> <xs:import namespace="http://example.org/services/MyPdaDevice.xsd" schemaLocation="http://example.org/services/MyPdaDevice.xsd"/>

<xs:import namespace="http://example.org/services/localDefinitions.xsd" schemaLocation="http://example.org/services/localDefinitions.xsd"/>

<xs:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd" schemaLocation="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"/> </xs:schema> </w:types>

<w:message name="ToHeader"> <w:part name="document" element="wsa:To"/> </w:message>

<w:portType name="MyPdaDevicePortType" wsrf-rp:ResourceProperties="pda:MyPdaDeviceProperties"> <w:operation name="GetResourceProperty"> <w:input name="GetResourcePropertyRequest" message="wsrf-rpw:GetResourcePropertyRequest" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyRequest"/> <w:output name="GetResourcePropertyResponse" message="wsrf-rpw:GetResourcePropertyResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/InvalidResourcePropertyQNameFault"/> </w:operation>



265266267

268269270271

272273274275

276

277278279

280281282283284

285286287288289

290291292

293294295296297298299

300301302303

304305306307308309310311312313314315316317318319320321322323324325326327

17

18

</w:portType>

<w:binding name="MyPdaDeviceSoapOverHttpBinding" type="pdaw:MyPdaDevicePortType"> <soapw:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>

<w:operation name="GetResourceProperty"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> </w:operation> </w:binding>

<w:service name="MyPdaDeviceService"> <w:port name="MyPdaDeviceSoapPort" binding="pdaw:MyPdaDeviceSoapOverHttpBinding"> <soapw:address location="http://example.org/services/MyPdaDeviceEndpoint"/> </w:port> </w:service>

</w:definitions>

The key points regarding our example WSDL document are as follows:

WSDL Elements Meaning of WSDL Element

Notes

targetNamespace= the target namespace

This is the URI of the namespace that is created by means of this document.

xmlns:nnnn= the definition of XML namespace prefixes

These definitions encompass all namespaces of those elements that are defined elsewhere than in this document.

<w:import ...> the import of foreign WSDL documents

The import of foreign WSDL documents is done outside of the WSDL types section, and the import of foreign XML schema documents is done inside the WSDL types section within the schema element.

This organization complies with a recommendation made by the WS-I Basic Profile 1.1.

<w:types>...

</w:types>the WSDL types section

We do not define a target namespace for the embedded schema in the WSDL types section. This is not a problem as we have not defined anything in the types section. Rather, the types section is used only to import other foreign XML schema documents.

<w:portType ... the portType The portType “MyPdaDevicePortType” includes the



328

329330331332333334

335336337338339340341342343344345346347348349350351352

353354355356357358359360

361362

363

19

20

>...

</w:portType>section attribute “wsrf-rp:ResourceProperties” to refer to the

schema definition for the resource properties of our simple resource. The only required operation on our portType is “GetResourceProperty”. This operation can be cut-and-pasted from the GetResourceProperty portType as defined in the WS-ResourceProperties specification.

For our example, the wsa:Action attribute is present for messages defined for the operation. The presence of the wsa:Action attribute allows us to avoid any ambiguity caused by aggregating this operation into a larger portType defined in a different XML namespace. As a general rule, it is a good idea to follow this practice for Web services that support the WS-Addressing specification.

<w:binding ...> ...</w:binding>

the binding section The binding in our WSDL document is for SOAP 1.1 over HTTP. Any binding may be used as appropriate for the environment in which the endpoint is deployed.

<w:service ...> ...</w:service>

the service section The service in our WSDL document includes a single port that uses the binding defined in our WSDL document. An example endpoint address is included for the port. Remember to change this address to something appropriate for your environment.

Additional port definitions may be added for services that can accept alternative message channels. For example, a second port definition could be added referencing the same binding with an SSL based endpoint URL.

2.2.3 Example SOAP MessagesWe now have a complete description for the manageability endpoint of the resource in our example. With this description, developers can write the code to support the necessary message exchanges. In order to communicate with an endpoint it is necessary for a manageability consumer to obtain a wsa:EndpointReference (EPR) to the manageability endpoint for the resource. In this step we assume that a manageability consumer receives an EPR from the manageability endpoint using some out-of-band technique. The set of information and their values in the EPR will vary between implementations. This variationis not important, as a manageability consumer needs only to follow the rules specified in the WS-Addressing specification [WS-Addressing] for formatting messages sent to the referenced manageability endpoint. An example of a message is constructed with an EPR appears as follows:

<wsa:EndpointReference> <wsa:Address>http://example.org/services/MyPdaDeviceEndpoint</wsa:Address> <wsa:ReferenceProperties> <exh:ResourceDisambiguator> urn:uuid:84decd55-7d3f-65ad-ac44-675d9fce5d22 </exh:ResourceDisambiguator> </wsa:ReferenceProperties></wsa:EndpointReference>

The presence or absence of the ReferenceProperties element in the EPR depends upon the needs and implementation of an endpoint. If a SOAP header is required by the endpoint in order



364365366367368369370371372373374

375376377378379380381382

383384

21

22

to select the target resource representation for a message, then the ReferenceProperties element is required. If an endpoint can differentiate between resource representations without a SOAP header, then the ReferenceProperties element is not required.

For our example, we assume it is necessary to send a SOAP header to differentiate between resource representations at an endpoint. This SOAP header element is defined in the namespace “http://example.org/services/localDefinitions.xsd” as created in section 2.2.1 of the MUWS Primer. Although it is permitted, it is not necessary for this element to have the same name or value as the MUWS ResourceId property. In our example we use distinct values for the WS-Addressing ReferenceProperty and the MUWS ResourceId.

An example request message to retrieve the value of the MUWS ResourceId property appears as follows:

<s:Envelope . . .> <s:Header> <wsa:To s:mustUnderstand="1"> http://example.org/services/MyPdaDeviceEndpoint </wsa:To> <wsa:Action>http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyRequest </wsa:Action> <wsa:ReplyTo> <wsa:Address> http://schemas.xmlsoap.org/ws/2005/08/addressing/role/anonymous </wsa:Address> </wsa:ReplyTo> <wsa:MessageID> urn:uuid:a5d27b2f-bb39-108a-a917-a855cb4d81d4 </wsa:MessageID> <exh:ResourceDisambiguator> urn:uuid:84decd55-7d3f-65ad-ac44-675d9fce5d22 </exh:ResourceDisambiguator> </s:Header> <s:Body> <wsrf-rp:GetResourceProperty> muws-p1-xs:ResourceId </wsrf-rp:GetResourceProperty> </s:Body></s:Envelope>

In our example SOAP message, the SOAP header elements, including the headers indicated in the ReferenceProperties element appear in order to comply with the WS-Addressing specification. If we wish to retrieve the value of the ResourceId property from any other resource, then the only parts of the message that need to be changed are derived from the correct mapping of the contents of an EPR into the associated SOAP headers of our example SOAP message. In our example SOAP message the SOAP Body contains the GetResourceProperty request.

An example response message for the above request appears as follows:

<s:Envelope . . .> <s:Header> <wsa:To s:mustUnderstand="1"> http://schemas.xmlsoap.org/ws/2005/08/addressing/role/anonymous </wsa:To> <wsa:Action>http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyResponse </wsa:Action> <wsa:MessageID> urn:uuid:3144c096-bcf2-a227-ff6f-3cb88843abfe </wsa:MessageID> <wsa:RelatesTo RelationshipType="wsa:Reply"> urn:uuid:a5d27b2f-bb39-108a-a917-a855cb4d81d4 </wsa:RelatesTo>



385386387

388389390391392393

394395

396397398399400401402403404405406407408409410411412413414415416417418419420421422

423424425426427428

429

430431432433434435436437438439440441442443444

23

24

</s:Header> <s:Body> <wsrf-rp:GetResourcePropertyResponse> <muws-p1-xs:ResourceId> urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 </muws-p1-xs:ResourceId> </wsrf-rp:GetResourcePropertyResponse> </s:Body></s:Envelope>

In our example response, the SOAP headers appear in order to comply with the WS-Addressing specification and in order to comply with the values in the header of the request message. The SOAP Body contains a GetResourceProperty response with the value of the ResourceId property for a resource representation. The particular value and form of the contents for a ResourceId property depend upon the implementation of a given manageability endpoint.

Faults can be returned from any manageability endpoint and are usually based on a misunderstanding, assumption, or error on the part of a manageability consumer. For example, a fault message would result if a manageability consumer requested the retrieval of the muws-p2-xs:Relationship property from our simple endpoint because it does not know about this property. Our example fault message appears as follows:

<s:Envelope . . .> <s:Header> <wsa:To s:mustUnderstand="1"> http://schemas.xmlsoap.org/ws/2005/08/addressing/role/anonymous </wsa:To> <wsa:Action>http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/InvalidResourcePropertyQNameFault </wsa:Action> <wsa:MessageID> urn:uuid:1ef400a9-1187-a304-7bd6-2141c8921d85 </wsa:MessageID> <wsa:RelatesTo RelationshipType="wsa:Reply"> urn:uuid:a5d27b2f-bb39-108a-a917-a855cb4d81d4 </wsa:RelatesTo> </s:Header> <s:Body> <s:Fault> <faultcode>s:Client</faultcode> <faultstring>Invalid Resource Property QName</faultstring> <detail> <wsrf-rp:InvalidResourcePropertyQNameFault> <wsrf-bf:Timestamp>2005-02-23T11:22:33.456Z</wsrf-bf:Timestamp> <wsrf-bf:Description xml:lang="en_US"> The requested resource property QName is not recognized. </wsrf-bf:Description> </wsrf-rp:InvalidResourcePropertyQNameFault> </detail> </s:Fault> </s:Body></s:Envelope>

Notice that we use a fault message that complies with the WS-BaseFaults [WS-BaseFaults] specification.

At this point in the primer we have completed our example definition of a very simple manageability endpoint that is fully compliant with the MUWS specification.



445446447448449450451452453

454455456457458

459460461462463

464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494

495496

497498

25

26

2.3 Adding a WSDM CapabilityNow that we have covered the minimum functionality required of a manageability endpoint, we wish to add another manageability capability to the enpoint in our example. For the purposes of this primer, we want our first additional capability to be easy to understand and implement. Thus we choose to add the MUWS Description capability to our resource.

The MUWS Description capability defines properties which we need to add to the resource properties document schema. Since the MUWS Description capability does not define any new operations we do not need to modify the WSDL document. See section 2.5, "Adding Property Access Operations", of this primer to see how to add an operation to a manageability endpoint.

Adding a manageability capability involves modifying the resource properties document schema in order to define the properties for the capability. Adding a manageability capability may also involve modifying the WSDL document in order to define the message exchanges for the capability. The MUWS Description capability defines three properties (Caption, Description, and Version). Of course, it is possible to support additional resource-specific description properties which are added in the same way.

In this and in subsequent sections of this primer we discuss only the modifications to the documents we created for our example in section 2.2, "Exposing Resource Identity". The final documents, containing the cumulative set of capabilities presented in our examples in this primer are located in the appendix of this primer.

2.3.1 Modifying the Resource Properties DocumentThe properties of the MUWS Description capability are defined in part 2 of the MUWS [MUWS Part 2] schema. We want to modify portions of our example MyPdaDevice schema to add support for the properties of the MUWS Description capability. In particular, we want to:

add a declaration for the XML namespace prefix to use for the MUWS part 2 schema

add an import for the MUWS part 2 schema

add a reference to the Description, Caption, and Version properties

There is a cardinality associated with the Caption, Description, and Version properties. A resource may have zero, one, or many instances of the Description and Caption properties.A resource may have zero or one instance of the Version property.

The new XML namespace prefix is added to the other prefix declarations in the root schema element as follows:

xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"

The new schema import statement is added after the import statement for the MUWS part 1 schema as follows:

<xs:import namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd" schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"/>

Finally, the new references to the Description, Caption, and Version property elements are added to the resource properties document schema for MyPdaDevice. Since the WS-ResourceProperties specification says that the order of property elements in the document schema is not relevant, we just add the Description, Caption, and Version property elements at the end of our existing list.

<xs:element name="MyPdaDeviceProperties"> <xs:complexType>



499500501502503

504505506507

508509510511512513

514515516517

518519520521

522

523

524

525526527

528529

530531

532533

534535536537

538539540541542

543544

27

28

<xs:sequence> <xs:element ref="muws-p1-xs:ResourceId"/> <xs:element ref="muws-p2-xs:Caption" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="muws-p2-xs:Description" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="muws-p2-xs:Version" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element name="MyPdaDeviceProperties">

The addition of these property references provides a good example of why this primer encourages the developer to copy-and-paste from the MUWS XML schema. Notice the presence of the minOccurs and maxOccurs attribute for each property element is very important and must have a correct value in order to comply with the MUWS specification.

With these few changes to the resource properties document schema, we have added the properties for the Description capability. Once support for these properties is implemented a manageability consumer is able to retrieve their value(s) using the GetResourceProperty message exchange. If a manageable resource has no caption, no description, or no version then the manageability consumer receives a GetResourcePropertyResponse element with no child element. If a manageable resource has many instances of captions or descriptions, then the manageability consumer receives a GetResourcePropertyResponse element with a child element for each instance of the requested property.

We have now added the MUWS Description capabilty to our example manageability endpoint.

2.3.2 Examples of Description Capability MessagesWe now take a look at some example messages for accessing the MUWS Description capability.

As discussed in section 2.2.3, the SOAP header in a MUWS message is driven by the need to comply with the WS-Addressing regarding rules on the use of EPRs, and the WS-Addressing rules for the formatting of a response message to a given request message. For this reason, we only provide examples of the contents of the SOAP Body. We do this in order to highlight where differences exist within the MUWS messages.

For this example, we assume our manageable resource has 2 instances of the Description property, no instances of the Caption property, and one instance of the Version property. These properties appear in the resource properties document for our resource as follows

<pda:MyPdaDeviceProperties . . .>

<muws-p1-xs:ResourceId> urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 <muws-p1-xs:ResourceId> <muws-p2-xs:Description xml:lang="en-US"> PDA device for Inventory/Ordering. </muws-p2-xs:Description> <muws-p2-xs:Description xml:lang="fr"> Ordinateur de poche pour inventaire et prise de commande. </muws-p2-xs:Description> <muws-p2-xs:Version>Version 1.4.2, January 2005</muws-p2-xs:Version></pda:MyPdaDeviceProperties>

Since the request is very similar for all of the properties and the request is the same as in section 2.2.3, we show only one request example as follows:

<wsrf-rp:GetResourceProperty> muws-p2-xs:Description </wsrf-rp:GetResourceProperty>



545546547548549550551552553554555

556557558559

560561562563564565566567

568

569570

571572573574575

576577578

579

580581582583584585586587588589590591

592593

594595596

29

30

The response message to this request returns a list of Description property instances. If a manageable resource does not have any instance of the Description property, the corresponding response contains a GetResourcePropertyResponse element with no child element. If there are many instances of the Description property, then the response contains many instances of the the Description property element. The Version and Caption properties follow similar rules. Notice that there is at most one instance of the Version element. Consider the example response:

<wsrf-rp:GetResourcePropertyResponse> <muws-p2-xs:Description xml:lang="en-US"> PDA device for Inventory/Ordering. </muws-p2-xs:Description> <muws-p2-xs:Description xml:lang="fr"> Ordinateur de poche pour inventaire et prise de commande. </muws-p2-xs:Description> </wsrf-rp:GetResourcePropertyResponse>

And the alternate example of a response:as follows:

<wsrf-rp:GetResourcePropertyResponse> </wsrf-rp:GetResourcePropertyResponse>

<wsrf-rp:GetResourcePropertyResponse> <muws-p2-xs:Version> Version 1.4.2, January 2005 </muws-p2-xs:Version> </wsrf-rp:GetResourcePropertyResponse>

In the XML above, the first response is the result of a request for the Caption property on a resource that has no Caption property instance.

MUWS does not specify a particular format for the Version property. Resources have widely varying versioning formats. If the Version property is not present for a manageable resource, then the response would appear the same as for the Caption property.

2.4 Manageability CharacteristicsIn this section we discuss the MUWS ManageabilityCharacteristics capability. This capability is the only one defined by MUWS describing information about the manageability support for a resource rather than describing information about the resource itself. The MUWS ManageabilityCharacteristics capability contains just one property, ManageabilityCapability. This property describes what management functionality the manageability endpoint of a resource offers a manageability consumer. The ManageabiltyCapability property describes a set of URIs. Each URI identifies a capabilitiy that is defined in a specification and supported by the manageability endpoint of a resource.

<muws-p1-xs:ManageabilityCapability> xs:anyURI </muws-p1-xs:ManageabilityCapability> *

Because a resource may expose multiple manageability capabilities, this property can occur multiple times in a resource properties document. Specification of this property in the resource property schema, therefore, is as follows:

<xs:element ref="muws-p1-xs:ManageabilityCapability" minOccurs="0" maxOccurs="unbounded"/>

Each occurrence of the <ManageabilityCapability> element in an instance of a resource properties document specifies a URI for a different capability exposed by the resource. Each URI is defined by MUWS, MOWS, or another resource manageability specification. Since a capability can be extended into a resource or a domain specific capability the ManageabilityCapability property should contain a URI for each and every manageability capability supported by the



597598599600601602

603604605606607608609610

611

612613

614615616617618619

620621

622623624

625626627628629630631632633

634635636

637638639

640641

642643644645646

31

32

resource, including any capability that was extended. Thus, we have an example ManageabilityCapability property instance as follows:

<pda:MyPdaDeviceProperties ...> 

<muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics </muws-p1-xs:ManageabilityCapability>

</pda:MyPdaDeviceProperties>

At this point in the primer the manageability endpoing for the resource in our example only supports three capabilities. As we further develop this manageable resource we will add additional manageability capability URIs to this list.

The ManageabilityCharacteristics capability is useful for enabling scaleable discovery and course grained introspection of resources. With a list of the manageability capabilities for a set of manageable resources, a manageability consumer can easily answer a questions like, ‘Which resources can be configured?’ A resource that can be configured is a possible candidate for becoming part of an autonomic loop.Given a hundred resources, a manageability consumer can use the ManageabilityCharacteristics capability to determine what high level capabilities are provided by a resource and quickly decide whether to continue detailed introspection of the Schema and WSDL interfaces, or simply to categorize the resource within a high level topology browser and defer further introspection until drill down on the resource is actually performed. By using the ManageabilityCharacteristics capability, a manageability consumer eliminates the need to perform large scale comparisons on operation and property patterns in order to identify signs and markers for certain interfaces. Section 4.1 of this primer discusses the discovery of resources. This section shows how convenient it is to register manageable resources so that a manageability consumer has the ability to search for and to discover a manageable resource based upon the ResourceIdentity and ManageabilityCharacteristics capabilities.

2.5 Adding Property Access OperationsIn the previous sections of this chapter, we added the properties of the MUWS Identity, Description, and ManageabilityCharacteristics capabilities to our resource properties document schema. Also, we presented examples of message exchanges retrieving the value of a single resource property using the GetResourceProperty operation.

In this section of the primer, we will add new property access operations. The new property access operations we define will allow a manageability consumer to retrieve the values of multiple resource properties, to modify the value of multiple resource properties, and to query the resource properties document using a query expression language such as XPath [XPATH]. In this section we will discuss how to modify the WSDL document in our example and present some example message exchanges for our new property access operations. Developers are encouraged to refer to the WS-ResourceProperties specification for more detail.

2.5.1 Modifying the WSDL DocumentIf we wish to add a new property access operation then we need to modify our WSDL document. In particular we wish to add three property access operations, as follows:

GetMultipleResourceProperties



647648

649650

651652653654655656657658659660661662

663664

665666667

668669670671672673674675676677678679680681682

683684685686687

688689690691692693694

695696697

698

33

34

SetResourceProperties

QueryResourceProperties

These three operations are already defined by the WS-ResourceProperties specification. In our example, all we need do is copy-and-paste these three property access operations from the portType definition in the WS-ResourceProperties WSDL document into our portType definition in our WSDL document and add the necessary bindings.

Since we do not define a new property access operation, there is no change to the import of foreign WSDL and schema documents. There is no change to the service element of the WSDL document in our example. The portions of the WSDL document that we need to modify are the portType and the binding. A complete WSDL document for our example is provided in appendix A of this primer.

We define a WSDL portType that includes all three property access operations in addition to the required GetResourceProperty operation as follows:

<w:portType name="MyPdaDevicePortType" wsrf-rp:ResourceProperties="pda:MyPdaDeviceProperties"> <w:operation name="GetResourceProperty"> <w:input name="GetResourcePropertyRequest" message="wsrf-rpw:GetResourcePropertyRequest" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyRequest"/> <w:output name="GetResourcePropertyResponse" message="wsrf-rpw:GetResourcePropertyResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/InvalidResourcePropertyQNameFault"/> </w:operation> <w:operation name="GetMultipleResourceProperties"> <w:input name="GetMultipleResourcePropertiesRequest" message="wsrf-rpw:GetMultipleResourcePropertiesRequest" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetMultipleResourceProperties/GetMultipleResourcePropertiesRequest"/> <w:output name="GetMultipleResourcePropertiesResponse" message="wsrf-rpw:GetMultipleResourcePropertiesResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetMultipleResourceProperties/GetMultipleResourcePropertiesResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetMultipleResourceProperties/ResourceUnknownFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetMultipleResourceProperties/InvalidResourcePropertyQNameFault"/> </w:operation> <w:operation name="SetResourceProperties"> <w:input name="SetResourcePropertiesRequest" message="wsrf-rpw:SetResourcePropertiesRequest"



699

700

701702703704

705706707708709

710711

712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759

35

36

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/SetResourcePropertiesRequest"/> <w:output name="SetResourcePropertiesResponse" message="wsrf-rpw:SetResourcePropertiesResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/SetResourcePropertiesResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/ResourceUnknownFault"/> <w:fault name="InvalidSetResourcePropertiesRequestContentFault" message="wsrf-rpw:InvalidSetResourcePropertiesRequestContentFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/InvalidSetResourcePropertiesRequestContentFault"/> <w:fault name="UnableToModifyResourcePropertyFault" message="wsrf-rpw:UnableToModifyResourcePropertyFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/UnableToModifyResourcePropertyFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/InvalidResourcePropertyQNameFault"/> <w:fault name="SetResourcePropertyRequestFailedFault" message="wsrf-rpw:SetResourcePropertyRequestFailedFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/SetResourcePropertyRequestFailedFault"/> </w:operation> <w:operation name="QueryResourceProperties"> <w:input name="QueryResourcePropertiesRequest" message="wsrf-rpw:QueryResourcePropertiesRequest" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/QueryResourcePropertiesRequest"/> <w:output name="QueryResourcePropertiesResponse" message="wsrf-rpw:QueryResourcePropertiesResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/QueryResourcePropertiesResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/ResourceUnknownFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/InvalidResourcePropertyQNameFault"/> <w:fault name="UnknownQueryExpressionDialectFault" message="wsrf-rpw:UnknownQueryExpressionDialectFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/UnknownQueryExpressionDialectFault"/> <w:fault name="InvalidQueryExpressionFault" message="wsrf-rpw:InvalidQueryExpressionFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/InvalidQueryExpressionFault"/> <w:fault name="QueryEvaluationErrorFault" message="wsrf-rpw:QueryEvaluationErrorFault"



760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827

37

38

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/QueryEvaluationErrorFault"/> </w:operation></w:portType>

As discussed in section 2.2.2 of this chapter, it is a good practice to add the wsa:Action attribute to messages we define for property access operations. This practice allows us to avoid any ambiguity caused by the aggregation of operations into a larger portType that is defined in a different XML namespace.

Now that we have the new operations in our portType definition, we need to bind these new operations to a message channel protocol in use by our manageability endpoint. For our example, we use SOAP 1.1 over HTTP, as follows:


<w:operation name="GetResourceProperty"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> </w:operation> <w:operation name="GetMultipleResourceProperties"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> </w:operation> <w:operation name="SetResourceProperties"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidSetResourcePropertiesRequestContentFault" use="literal"/> </w:fault>



828829830831832

833834835836

837838839

840841842843844

845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893

39

40

<w:fault> <soapw:fault name="UnableToModifyResourcePropertyFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="SetResourcePropertyRequestFailedFault" use="literal"/> </w:fault> </w:operation> <w:operation name="QueryResourceProperties"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="UnknownQueryExpressionDialectFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidQueryExpressionFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="QueryEvaluationErrorFault" use="literal"/> </w:fault> </w:operation> </w:binding>

2.5.2 Example of Property Access Operation MessagesNow that we have modifyied our WSDL document, developers can write code to support the message exchanges for the operations.

Consider the resource properties document, introduced in section 2.3 as follows:

<pda:MyPdaDeviceProperties ...> <muws-p1-xs:ResourceId> urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 </muws-p1-xs:ResourceId> <muws-p2-xs:Description xml:lang="en-US"> PDA device for Inventory/Ordering. </muws-p2-xs:Description> <muws-p2-xs:Description xml:lang="fr"> Ordinateur de poche pour inventaire et prise de commande. </muws-p2-xs:Description> <muws-p2-xs:Version> Version 1.4.2, January 2005 </muws-p2-xs:Version></pda:MyPdaDeviceProperties>

The GetMultipleResourceProperties operation is used to retrieve property values for all three of the Description capability properties in a single message exchange. The request message contains a list of ResourceProperty elements. Each ResourceProperty element contains an xs:QName corresponding to the QName of a resource property element defined in our resource properties document schema.

The SOAP body of a GetMultipleResourceProperties request message to retrieve the values for all three MUWS Description capability properties appears as follows:



894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929

930931932

933

934935936937938939940941942943944945946947

948949950951952

953954

41

42

<wsrf-rp:GetMultipleResourceProperties> <wsrf-rp:ResourceProperty>muws-p2-xs:Caption</wsrf-rp:ResourceProperty> <wsrf-rp:ResourceProperty>muws-p2-xs:Description</wsrf-rp:ResourceProperty> <wsrf-rp:ResourceProperty>muws-p2-xs:Version</wsrf-rp:ResourceProperty> </wsrf-rp:GetMultipleResourceProperties>

And the response apeears as follows:

<wsrf-rp:GetMultipleResourcePropertiesResponse> <muws-p2-xs:Description xml:lang="en-US"> PDA device for Inventory/Ordering. </muws-p2-xs:Description> <muws-p2-xs:Description xml:lang="fr"> Ordinateur de poche pour inventaire et prise de commande. </muws-p2-xs:Description> <muws-p2-xs:Version> Version 1.4.2, January 2005 </muws-p2-xs:Version> </wsrf-rp:GetMultipleResourcePropertiesResponse>

Notice that the muws-p2-xs:Caption property is not added as a child element of the response message. This is because the muws-p2-xs:Caption property is defined in the schema with minOccurs=”0” and there is no current instance of the property. Since there are two instances for muws-p2-xs:Description property both are added as child elements of the response message.

So far in this chapter, we have discussed how a manageability consumer uses the GetResourceProperty and GetMultipleResourceProperties operations to retrieve values of resource properties for a managed resource. In contrast to these two operations, the SetResourceProperties operation allows a manageability consumer to change values of multiple resource properties in a single request. There are three ways to change the value of a resource property as follows:

insertion, by means of an <Insert> element

updating, by means of an <Update> element

deletion, by means of a <Delete> element

Each type of change is modeled as a separate type of component within a SetResourceProperties request message.

To demonstrate the use of the SetResourceProperties operation, we choose to update both the English and the French descriptions for the resource in our example. The resource property values we wish to change need be defined as modifiable. As specified in MUWS, the Description element is modifiable.

The request message appears as follows:

<wsrf-rp:SetResourceProperties> <wsrf-rp:Update> <muws-p2-xs:Description xml:lang="en-US"> New Description. </muws-p2-xs:Description> <muws-p2-xs:Description xml:lang="fr"> Nouvelle Description. </muws-p2-xs:Description> </wsrf-rp:Update> </wsrf-rp:SetResourceProperties>

If the update is successful, then the updated resource properties document appears as follows:

<pda:MyPdaDeviceProperties ...> <muws-p1-xs:ResourceId> urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 </muws-p1-xs:ResourceId> <muws-p2-xs:Description xml:lang="en-US">



955956957958959

960

961962963964965966967968969970971

972973974975

976977978979980981

982

983

984

985986

987988989990

991

99299399499599699799899910001001

1002

10031004100510061007

43

44

New Description. </muws-p2-xs:Description> <muws-p2-xs:Description xml:lang="fr"> Nouvelle Description. </muws-p2-xs:Description> <muws-p2-xs:Version> Version 1.4.2, January 2005 </muws-p2-xs:Version></pda:MyPdaDeviceProperties>

And the response message appears simply as follows:

<wsrf-rp:SetResourcePropertiesResponse/>

If, for some reason, a manageability endpoint can not update the muws-p2-xs:Description property, then a SetResourcePropertyRequestFailedFault is raised and sent as follows:

<s:Fault> <faultcode>s:Server</faultcode> <faultstring>Receiver/server fault</faultstring> <detail> <wsrf-rp:SetResourcePropertyRequestFailedFault> <wsrf-bf:Timestamp>2005-05-02T15:22:14.889-07:00</wsrf-bf:Timestamp> <wsrf-bf:Description xml:lang="en-US"> Set component for Resource property {http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd}Description of the SetResourceProperties request failed. </wsrf-bf:Description> </wsrf-rp:SetResourcePropertyRequestFailedFault> </detail> </s:Fault>

Other faults are defined for the SetResourceProperties operation. Developers should read the WS-ResourceProperties specification and decide which fault to raise for a given situation.

In our example, the last property access operation we wish to add is called QueryResourceProperties. This operation allows a manageability consumer to query the resource properties document using a query expression language such as XPath. As a simple example, we wish to know if the MyPdaDevice resource in our example is version 1.4.2. The request message we send to the manageability endpoint to evaluate the query expression against the root element of the MyPdaDevice resource properties document appears as follows:

<wsrf-rp:QueryResourceProperties> <wsrf-rp:QueryExpression Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"> starts-with(/pda:MyPdaDeviceProperties/muws-p2-xs:Version, "Version 1.4.2") </wsrf-rp:QueryExpression> </wsrf-rp:QueryResourceProperties>

Notice that namespace prefixes may be used within query expressions. The namespace prefixes that are in context for the QueryResourceProperty element may be used in a query expression. In the example above, we assume the muws-p2-xs prefix is declared on the SOAP envelope element. The query expression in the above request conforms to the XPath 1.0 language, as specified by the URI string in the Dialect attribute. The other well-known dialect identified by the WS-ResourceProperties specification is:

http://www.w3.org/TR/2003/WD-xpath20-20031112

This dialect corresponds to the XPath 2.0 (working draft) language.

For the example resource properties document in our example, the above query expression evaluates as true. Thus the response message appears as follows:

<wsrf-rp:QueryResourcePropertiesResponse> true



100810091010101110121013101410151016

1017

1018

10191020

10211022102310241025102610271028102910301031103210331034

10351036

103710381039104010411042

104310441045104610471048

104910501051105210531054

1055

1056

10571058

10591060

45

46

</wsrf-rp:QueryResourcePropertiesResponse>

2.6 Operational StatusThe Operational Status capability provides a means to convey the health of an application in a generic manner.This manageability capability contains only one property, OperationalStatus. The OperationalStatus property is added to our resource properties document as follows:

<xs:element ref="muws-p2-xs:OperationalStatus"/>

The OperationStatus property can have one of four values as follow:

Available: the resource accepts new requests and performs as expected

Unavailable: the resource s not accepting new requests and is not performing as expected

PartiallyAvailable: the operational status of the resource requires further inspection. The resource may be degraded due to errors, or may be in the process of honoring a quiese. This is a neutral operational status with no associated ‘goodness’ or ‘badness’

Unknown: the operational status of the resource cannot be determined

While it is up to the designers and developers of a resource to choose the conditions and resource states changes (see section 2.12) causing a change in OperationalStatus, the semantics of the four possible values for this property should remain consistent.

When the OperationalStatus property changes value, a WS-RF property change event is sent to each subscriber of the ‘muws-p2-xs:OperationalStatus’ topic. Each subscriber of the ‘muws-ev:OperationalStatusCapability’ topic is also sent a notification. For more information on these event topics, see section 2.10, "Notifications". An example of an OperationalStatus change notification is presented in section 2.10.3.1 of this primer.

When the OperationalStatus property is available and the Operational Status capability is supported, the ManageabilityCapability property should expose this as follows:

<muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus </muws-p1-xs:ManageabilityCapability>

Notice the OperationalStatus property is read only since it reflects the current status of a resource. Control of the current status of a resource should be achieved indirectlly via extension of the State capability.

The resource properties document for the PDA in our example appears as follows:

<pda:MyPdaDeviceProperties . . .>. . . <muws-p2-xs:OperationalStatus>Available</muws-p2-xs:OperationalStatus>

<muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus </muws-p1-xs:ManageabilityCapability></pda:MyPdaDeviceProperties>

2.7 MetricsThis section defines how to represent metrics and the metadata necessary to correctly process and interpret a metric value. WSDM MUWS, of itself, does not define any management metrics. The metrics appropriate for a managed resource are specified by the model of that resource. Thus, as is illustrated below, the metrics of a resource are accommodated within MUWS by



1061

1062106310641065

1066

1067

1068

10691070

1071107210731074

1075

107610771078

10791080108110821083

10841085

108610871088

108910901091

1092

109310941095

10961097109810991100

11011102110311041105

47

48

extending the Metrics capability. See section 2.8 of this primer for more information on extending capabilities.

MUWS defines one property pertaining to Metrics, the current time, specified as follows:

<xs:element ref="muws-p2-xs:CurrentTime"/>

and indicates support for the metrics capability with the following ManageabilityCapability:

<pda:MyPdaDeviceProperties . . .>. . . <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p1-xs:ManageabilityCapability>


2.7.1 A Scenario for PDA MetricsManageable resource must define their own model of the metrics it wishes to expose through MUWS facilities. Therefore, to make use of the MUWS Metric capability it is necessary to define a resource specific metric capability. The following sections of this primer (sections 2.8 through 2.11) will describe the WSDM facilities that must be brought into play in order to define a resource specific metric capability.

When we define a resource-specific Metric capability we must extend the MUWS Metric capability. We extend the MUWS Metric capability in order to tie the resource-specific metric model into the MUWS architectural framework. To describe this extension, we present four metrics for our PDA device as follows:

FailedConnections. This metric tracks the number of failed attempts at establish a connection with a server.

MessagesReceived: This metric tracks the number of messages received by the PDA within the last 30 minutes relative to the last message received. Unlike the FailedConnection metric, the MessagesReceived metric is a “moving window” on the number of received messages based on when the last message was received.

AverageResponseTime: This metric provides the average response time for the PDA over the last 10 minutes. This metric is recalculated every 2 minutes. The AverageResponseTime metric also provide a moving window on average response, but unlike MessagesReceived, this metric is recalculated on a predefined periodic basis.

MemoryInUse: This metric provides the manageability consumer with the percentage of power remaining in the battery whenever the manageability consumer queries for this resource property.

Let us further assume that the manageability consumer wants to reset the count of FailedConnections after the problem has been resolved that prevented the PDA from connecting to the server. Therefore, the PDA manageability endpoint must expose a ResetServerConnectionMetric operation. Furthermore, our manageability consumer wishes to be informed—in real time—whenever an attempt to connect to a server fails. This last requirement brings into play Subscriptions and Notifications, presented in section 2.10 of this primer. In our example, the manageability consumer will subscribe to the manageability endpoint of our PDA device to receive notifications concerning failed attempts to establish a server connection for our PDA device. Finally, for reporting purposes, we would like the management consumer to group metrics related to remote devices into the same group of metrics.



11061107

1108

1109

1110

11111112111311141115

11161117

111811191120112111221123

1124112511261127

11281129

1130113111321133

1134113511361137

113811391140

1141114211431144114511461147114811491150

49

50

2.7.2 Metric Datatypes and Exposing MetricsThe preceding scenario involves three metric datatypes: FailedConnections and MessagesReceived are counters and therefore have non-negative integer values; AverageResponseTime is a duration, and MemoryInUse is a percentage. These three types are typical metric datatypes, but we need to define them before we can use the metrics in the schema of the our resource properties document.

To define metric datatypes, however, requires understanding more about how metric data has to be exposed. Notice that the preceding metrics involve special considerations. For example, FailedConnections are counted from the time that the counter is reset by the manageability consumer, but that MessagesReceived and AverageResponseTime are calculated within a specified window (i.e., duration of 30 minutes and 10 minutes respectively). For metric values to carry proper semantics, it is necessary to qualify metric data with attributes regarding the conditions under which the data was collected or calculated. In WSDM, metric data can be qualified with the following attributes:

ResetAt, which indicates the time at which the value of the metric property was reinitialized

LastUpdated, which indicates the most recent time at which the value of the metric property was updated

Duration, which indicates the time over which the value of a metric property was collected, counted, or measured previous to the LastUpdated time.

These attributes are defined in the MOWS Schema in an attributeGroup named MetricAttributes. Definition of metric datatypes MUST include an attribute reference to this group. Thus we can define the three datatypes used in the PDA Metric Scenario as follows:

<xs:complexType name="NonNegativeMetric"> <xs:simpleContent> <xs:extension base="xs:nonNegativeInteger"> <xs:attributeGroup ref="muws-p2-xs:MetricAttributes"/> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:extension> </xs:simpleContent></xs:complexType>

<xs:complexType name="DurationMetric"> <xs:simpleContent> <xs:extension base="xs:duration"> <xs:attributeGroup ref="muws-p2-xs:MetricAttributes"/> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:extension> </xs:simpleContent> </xs:complexType>

<xs:complexType name="PercentageMetric"> <xs:simpleContent> <xs:restriction base="exh:NonNegativeMetric"> <xs:minInclusive value="0"/> <xs:maxInclusive value="100"/> <xs:attributeGroup ref="muws-p2-xs:MetricAttributes"/> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:restriction> </xs:simpleContent> </xs:complexType>

Thus, data on FailedConnections may be reported as follows, which reports 5 connection failures since July 1, 2005 12:01:16 (PM, GMT), with the last connection failure occurring at 12:25:53 on August 11, 2005):

<pda:FailedServerConnections LastUpdated="2005-08-11T12:25:53Z"



115111521153115411551156

11571158115911601161116211631164

11651166

11671168

11691170

117111721173

11741175117611771178117911801181

118211831184118511861187118811891190

11911192119311941195119611971198119912001201

120212031204

12051206

51

52

ResetAt="2005-06-01T12:01:16Z"> 5 </pda:FailedServerConnections>

Notice that not all three metric attributes are relevant to each metric property. In this case, the collection interval is not predefined as a duration. Thus, the durration attribute is not reported. The collection interval must be calculated from the currentTime less the ResetAt time. Note that all times are relative to the resource. In order to rationalize the time stamps, the CurrentTime property must be retrieved with the metrics. This is why CurrentTime underlies all metric capabilities and is specified in the MUWS Metrics capability.

The appropriate attributes for a metric are defined by the metadata on the metric, specifically metadata defining the metrics relationship to the time in which is collected. Metric metadata is explained in section 2.11.2. Metadata for the PDA metrics, and thus the relevant attributes that qualify our four metics, is presented in section 2.11.2.1. Exposing metadata (section 2.11) is the final step in developing PDA Metrics. In following section (section 2.8) we begin by defining the steps involved in extending a WSDM capability.

2.8 Extending a CapabilityWe can extend a manageability capability by adding semantics, resource-specific properties, operations, or events. If a capability is extended to create a new capability, then the extended capability supports the same semantics, behaviors, properties, operations, and events as the base capability and adds some behaviors, properties, operations and events. The specification for an extended capability must clearly identify what capabilities it extends or requires. We need to clearly identify the base capabilities extended by a new capability since this information is not available on a resource or in metadata at this time.

To extend a capability or to define any new capability we perform a series of steps as follow:

Define a URI for our extended capability using a namespace we control. Like any capability, an extended capability is identified by a URI.

Add a new instance of the ManageabilityCapability property. When a resource supports our extended capability, the ManageabilityCapabilities property of the resource must include a URI for the base capability and a URI for the extended capability.

Define all properties supporting our extended capability in a schema document. Notice this schema document does not need to be resource-specific since some properties of our extended capability may already be defined within other schema documents. Thus we can simply import properties as defined elsewhere.

Define each message exchange for accessing our extended capability in a WSDL document. Some message exchanges may be defined within other WSDL documents. We can simply import message exchanges as defined elsewhere.

Define a new TopicSpace document that includes a Topic for our extended capability. If new events can be generated by our capability then we add the requisite topics to the TopicSpace document. For a discussion on creating a TopicSpace, see section 2.10.4 in this primer.

Document our extended capability in a specification, making sure we indicate which capabilities this new capability extends and any other capabilities required in support of our extended capability. At this time MUWS does not define a template for extending a capability. We want to be sure to document the semantics of all new properties, operations, and notifications. For additional information, see section 2.11, "Building and Exposing a Metadata Docment".

An extended capability allows any manageability consumer lacking support for a particular extended capability to manage the resource from a perspective of the base capability. Thus a



120712081209

121012111212121312141215

121612171218121912201221

12221223122412251226122712281229

1230

12311232

123312341235

1236123712381239

124012411242

1243124412451246

124712481249125012511252

12531254

53

54

manageability consumer that is limited in this way can still manage a resource using all features of the base capability. However, such a manageability consumer is not able to access advanced features of the extended capability. A manageability consumer supporting a particular extended capability is able to use enhanced features offered by the extended capability for enhanced manageability of a resource.

To begin extending the MUWS Metric capability we define a URI for the new capability within our example domain, http://example.org/capabilities/PDAMetrics. When this capability is included in an instance of the resource properties document for a resource, this URI and the URI identifying the MUWS Metric capability should be reported. In our example, this appears as follows:

<pda:MyPdaDeviceProperties . . .>. . . <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://example.org/capabilities/PDAMetrics </muws-p1-xs:ManageabilityCapability></pda:MyPdaDeviceProperties>

2.9 Adding Resource-specific Operations and PropertiesThe MUWS specification defines many properties and operations that are common to all types of resources. Thus, for many resources we do not need to define additional resource-specific properties and operations. However, in some cases it is desirable to define operations specific to the monitoring or controlling of some unique aspect of a resource. Likewise, in some cases it is desirable to define properties that represent some unique characteristic of the state of a resource.

A resource-specific operation is exposed by adding its definition to the operations of a WSDL document. An operation that is unique to a particular device is defined directly in the WSDL document for that device. We would add the definition of an operation that is unique to the MyPdaDevice to the WSDL document in our example. In cases where an operation also applies in general to a set of devices we may wish to define the operation in a WSDL file that is shared by the set of devices, and then cut-and-paste the definition of the operation into the device-specific WSDL file.

In this section we add two properties and an operation that are somewhat arbitrary. However, in the next section we will extend a previously defined capability and include these two properties and operation within the extended capability. Since we add only properties and message exchanges that are resource-specific, these changes do not result in a new capability.

2.9.1 Adding Resource-specific PropertiesIn section 2.3.1 we modified our resource properties document by adding resource properties defined in the MUWS schema. In this section we add the new properties to the resource properties document as described in our scenario in section 2.7.1.

Include the following resource property declarations in the schema of the resource properties document.

<xs:element name="FailedServerConnections" type="exh:NonNegativeMetric"/> <xs:element name="MessagesReceived" type="exh:NonNegativeMetric"/> <xs:element name="AverageResponseTime" type="exh:DurationMetric"/> <xs:element name="MemoryInUse" type="exh:PercentageMetric"/>

Notice that to support reusability of these metric datatypes, we should include the metric datatype definitions (see section 2.7.2) in our schema for localDefinitions (exh:).



12551256125712581259

1260126112621263

126412651266126712681269127012711272

127312741275127612771278

1279128012811282128312841285

1286128712881289

1290129112921293

12941295

1296129712981299

13001301

55

56

http://example.org/capabilities/ServerConnectionMetrics

2.9.2 Adding Resource-specific operationsWe must also add an operation to reset the values of our two PDA metrics. Operations are specified in the WSDL. A property access operation that is not specific to a resource references the definition of the reset operation in other WSDL and schema documents. Operations specific to a resource must have a type created to represent the message, and the WSDL message elements must be created. The message on the wire contains the operation name as specified within the element in the schema document. For our example, we start with the schema in the resource properties document and create the request and response message types as follow:

<xs:element name="ResetServerConnectionMetric"> <xs:complexType/> </xs:element>

<xs:element name="ResetServerConnectionMetricResponse"> <xs:complexType/> </xs:element>

We can now define the message structures in the WSDL document for our PDA resource. Since we already import the schema for our PDA there is no reason to add a new import statement. We add the message and operation structures as follows:

<w:message name="ResetServerConnectionMetricRequestMessage"> <w:part name="document" element="pda:ResetServerConnectionMetric"/></w:message>

<w:message name="ResetServerConnectionMetricResponseMessage"> <w:part name="document" element="pda:ResetServerConnectionMetricResponse"/></w:message>

. . .

<w:operation name="ResetServerConnectionMetricOperation"> <w:input name="ResetServerConnectionMetricInput" message="pdaw:ResetServerConnectionMetricRequestMessage" wsa:Action="http://example.org/services/MyPdaDevice.wsdl/MyPdaDevicePortType/ResetServerConnectionMetricRequest"/> <w:output name="ResetServerConnectionMetricOutput" message="pdaw:ResetServerConnectionMetricResponseMessage" wsa:Action="http://example.org/services/MyPdaDevice.wsdl/MyPdaDevicePortType/ResetServerConnectionMetricResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> </w:operation>

In the above WSDL, notice the inclusion of the ResourceUnknownFault. This fault should be added to all operations. If there is a resource-specific fault, then it should be defined as a message and included within the WSDL as well.

Add the new operation to the binding in the same way as we added the operations in section 2.5.1. See Appendix A of this primer for the complete WSDL document.

2.10 NotificationsIn addition to allowing manageability consumers to retrieve information from manageability endpoints, MUWS allows a manageability consumer to register to receive notifications of events pertaining to a manageable resource. For example, a manageability consumer can be notified when a threshold is reached in a particular metric or when a new relationship is created for a



13021303130413051306130713081309

131013111312

1313131413151316

131713181319

132013211322

132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346

134713481349

13501351

13521353135413551356

57

58

resource. For additional information about relationships see chapter Error: Reference source not found, "Building Relationships".

The notification used by MUWS is defined by the WS-Notification family of specifications, which consists of three specifications. The WS-BaseNotification [WS-BaseNotification] specification describes messages for creating subscriptions and for managing those subscriptions. The common structure for notifications is defined within this specification.

The WS-Topics [WS-Topics] specification describes a means for exposing a hierarchical model of potential events. MUWS defines specific event topics corresponding to a management domain. Examples of a notification topic and its corresponding event are as follow:

Creation or destruction of a new relationship.

Creation or destruction of a manageable resource and/or a manageability endpoint.

Changes to properties exposed by a manageability capability.

WS-Topics is intended for use with other topics as defined within other specifications as well as with domain-specific topics. For more information on Topics, see section 2.10.4.

The WS-BrokeredNotification [WS-BrokeredNotification] specification describes a means to relieve an event producer from the burden of propagating event notification messages and from the overhead of handling subscription messages. Thus, WS-BrokeredNotification facilitates scalable systems architecture for managed resources that produce notifications through the delegation of these tasks to a broker. While MUWS allows use of the brokered notification mechanism as appropriate to a manageable resource it does not require support of brokered notification. For details on the WS-Notification family of specifications, we suggest a reading of the specifications and documentation as published by the OASIS WS-Notification technical committee.

2.10.1 Changes to the Resource Properties DocumentA common use case of notifications for systems management is the monitoring of changes to the state of a resource as exposed by its resource properties document. The monitoring of changes to the state of a resource is achieved through the ResourcePropertyValueChangeNotification mechanism as defined in the WS-ResourceProperties specification. For each property in a resource properties document, a topic is created. Each topic name is based upon its associated property name. A manageability endpoint indicates its ability to provide a notification on change of a property by including the corresponding topic name in its list of supported topics.

WS-BaseNotifications defines three properties that must appear in the resource properties document of a managed resource supporting notifications. Thus, we add these XML elements to the resource properties document for our PDA device as follow:

<xs:element ref="wsnt:Topic" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="wsnt:FixedTopicSet" minOccurs="1" maxOccurs="1"/> <xs:element ref="wsnt:TopicExpressionDialects" minOccurs="1" maxOccurs="unbounded"/>

Notice the namespace of these elements is the same as defined for WS-BaseNotification. It is necessary to declare and import the "wsnt" namespace as in previous examples, incorporating a foreign namespaces. See Appendix A of this primer for a complete Schema for our PDA example that declares and imports the "wsnt" namespace form the WS-BaseNotification specification. All topics supported by a resource should be included in the Topics resource property. See section 2.10.4.1 for an example.

Since the Notification capability is not a MUWS capability, we do not add a new instance of the ManageabilityCapability property.



13571358

1359136013611362

136313641365

1366

1367

1368

13691370

137113721373137413751376137713781379

13801381138213831384138513861387

138813891390

139113921393139413951396

139713981399140014011402

14031404

59

60

2.10.2 Changes to the WSDL DocumentWhen supporting notifications, we must add the Subscribe message exchange pattern to our WSDL document. The necessary operations are defined in the WSDL document for the WS-BaseNotification specification. We just copy-and-paste these operations and add the necessary XML namespace declarations and imports. In our example, the “wsntw” XML namespace is imported from the WSDL document for the WS-BaseNotification specification and appears as follows:

<w:operation name="Subscribe"> <w:input message="wsntw:SubscribeRequest" wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/SubscribeRequest"/> <w:output message="wsntw:SubscribeResponse" wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/SubscribeResponse"/> <w:fault name="ResourceUnknownFault" message="wsntw:ResourceUnknownFault" /> <w:fault name="SubscribeCreationFailedFault" message="wsntw:SubscribeCreationFailedFault"/> <w:fault name="TopicPathDialectUnknownFault" message="wsntw:TopicPathDialectUnknownFault"/> </w:operation>

<w:operation name="GetCurrentMessage"> <w:input message="wsntw:GetCurrentMessageRequest" wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/GetCurrentMessageRequest"/> <w:output message="wsntw:GetCurrentMessageResponse" wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/GetCurrentMessageResponse"/> <w:fault name="ResourceUnknownFault" message="wsntw:ResourceUnknownFault" /> <w:fault name="InvalidTopicExpressionFault" message="wsntw:InvalidTopicExpressionFault" /> <w:fault name="TopicNotSupportedFault" message="wsntw:TopicNotSupportedFault" /> <w:fault name="NoCurrentMessageOnTopicFault" message="wsntw:NoCurrentMessageOnTopicFault" /> </w:operation>

Notice that wsa_Actions was also imported for our WSDL example. We also need to add the Subscribe and GetCurrentMessage operations to the binding section of our WSDL document. Notice that these operations are added in the same way as other operations. A complete WSDL specification, including the bindings, for our example is located in Appendix A of this primer.

2.10.3 ManagementEvent FormatMUWS Part 1 defines the base ManagementEventType. This type is used for all events emitted by a MUWS compliant resource. The muws-p1-xs:ManagementEventType defines three elements and one attribute. The relevant fragment of the MUWS Part 1 schema appears as follows:

<xs:complexType name="ManagementEventType"> <xs:sequence> <xs:element name="EventId" type="xs:anyURI"/> 1001 <xs:element name="SourceComponent" type="muws-p1-xs:ComponentType"/> <xs:element name="ReporterComponent" type="muws-p1-xs:ComponentType" minOccurs="0"/> 1004 <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other" processContents="lax"/> </xs:sequence> <xs:attribute name="ReportTime" type="xs:dateTime" use="optional"/> <xs:anyAttribute namespace="##other"/> </xs:complexType>



1405140614071408140914101411

14121413141414151416141714181419142014211422142314241425

14261427142814291430143114321433143414351436143714381439144014411442

1443144414451446

14471448144914501451

145214531454145514561457145814591460146114621463

61

62

http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/SubscribeRequest


http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/SubscribeResponse




Notice that the structure of the ManagementEventType provides extensibility for both elements and attributes from other namespaces. MUWS Part 2 makes use of this extensibility by adding an additional element to the three elements defined in the structure above.

Of the three elements defined in the ManagementEventType, the two required elements are muws-p1-xs:ManagementEvent/EventId and muws-p1-xs:ManagementEvent/SourceComponent.

The EventId uniquely identifies an event to distinguish it from similar events that may have occurred involving the same resource.

The SourceComponent provides a reference to the manageable resource involved in the event. Notice the SourceComponent may contain a different reference than the resource reporting the event. For example, router "A" may observe that an adjacent router "B" is not responding. Router "A" may report the problem it observes involving router "B". In this case, router "A" is the reporter and router "B" is the source. Since most events are generated by the resource involved in the event, the ReporterComponent element is not necessary if it refers to the same resource as the SourceComponent element.

The attribute, muws-p1-xs:ManagementEvent@ReportTime is optional yet recommended. This attribute provides the UTC report time of an event. The report time may be different from the time at which an event actually occurred. For example, a router that restarts due to an internal failure may not report the failure until self-restart is complete. In this case, the ReportTime is different from than the actual time of the internal failure event.

MUWS Part 2 adds the Situation element, This element is a container for the specifics of an event. The Situation element contains a number of elements. However, the most critical and only REQUIRED element is SituationCategory. This element provides a canonical categorization of an event into one of twelve general categories. These twelve categories are defined in the muws-p2-xs:Situation/muws-p2-xs:SituationCategory element. These categories are further clarified in Appendix F of MUWS Part 2.

The SituationCategory element provides a means for a manageability consumer to quickly categorize an event and facilitates the correlation of multiple events involving multiple resources. Industry experience has shown that an effective root-cause analysis of complex operational problems in a multi-tier environment can be reduced from hours or more to just minutes through simple correlation heuristics using the SituationCategory element.

Keep in mind that the value provided by the SituationCategory element, is only as good as the implementation of a manageable resource. If an implementation takes a lazy approach and categorizes every event as an OtherSituation, then the value provided by the SituationCategory element is rendered useless. Thus, an accurate categorization of an event is important when implementing MUWS Events. The categories defined in the MUWS specification are ordered so that more critical categories are listed ahead of less critical categories. For example, an event categorized as an AvailabilitySituation is considered more critical than an event categorized as a StartSituation. The primary reason for this ordering of categories is to provide some guidance for categorizing events. When ambiguity exists in regard to the categorization of an event for a manageable resource, it is generally recommended to use the more critical category.

Finally, muws-p2-xs:Situation includes a number of optional elements as follow:

SituationTime – the time an event actually occurred – this is RECOMMENDED.

SuccessDisposition – a qualification of the SituationCategory. For example, a StartSituation that failed has a SuccessDisposition of UNSUCCESSFUL.

Priority – the relative importance of an event. Priority is distinct from Severity. See Severity below for a description of this distinction.

Severity – the relative effect an event has on the operational status of a resource. Severity values are based upon Perceived Severity as defined within the Distributed Management Task Force (DMTF) CIM Alert Indication. A more critical severity identifies an event causing an



146414651466

14671468

14691470

1471147214731474147514761477

14781479148014811482

148314841485148614871488

14891490149114921493

1494149514961497149814991500150115021503

1504

1505

15061507

15081509

151015111512

63

64

involved resource to become severely constrained. A less critical severity identifies an event allowing an involved resource to remain fairly functional. The distinction between Severity and Priority we illustrate by example. Consider a disk drive that crashes within a RAID storage system. The severity for this event may be less critical because the RAID storage system contains spares and is fully capable of compensating for a crashed disk. Also, the performance of the RAID storage system is not affected. By contrast, the priority of this event is more critical since a disk has completely failed, reducing the pool of available spares by one. If the failed disk is not replaced to replenish the pool of spares, then the ability of the RAID storage system to self heal is further jeopardized if more disks crash . In this example, a manageability consumer could recognize the overall business impact of an event and take appropriate action to order and replace the crashed disk drive.

Message – In general, this element is a human readable text message providing the details of an event. A message may simply be displayed on a management console or may be further parsed by a manageability consumer as needed by its management applications.

SubstitutableMsg – This element along with its associated attributes and elements appears when a message contains data and formatting controls cataloged elsewhere. The MsgId attribute provides a reference to the message in a catalog. The MsgIdType attribute identifies the type of catalog to use. Note that in general, the manufacturer of a resource supplies message catalogs. For example, a message of the form: “Disk drive %s, LUN:%d, Head:%d, Track: %d has failed.” The Value for an event instance might be: “Hitachi IC25N080ATMR04-0”, 2, 4, 217; producing the final message: Disk drive Hitachi IC25N080ATMR04-0, LUN:2, Head:4, Track: 217 has failed.” The SubstitutableMsg element is especially useful if a message needs rendering in different languages. A manageability consumer can configure a language specific catalog and the same message can be meaningfully represented in any supported language.

2.10.3.1 ExampleConsider a situation in which a manageability consumer wishes to be informed whenever a PDA device goes off line and is no longer available. The PDA device may be temporarily unavailable due to the downloading of software or due to a management query. In order to inform the manageability consumer, a resource must emit a notification when the OperationalStatus property, as described in section 2.6 transitions from the Available state to the Unavailable state. Changes to the resource properties of a resource are reported by means of the <ResourcePropertyValueChangeNotification> element, which is defined in the [WSRF-RP] specification. This element provides both the old value (Available) and new value (Unavailable).

A notification with a SituationCategory of AvailabilitySituation as emitted by the manageability endpoint of our PDA device appears as follows:

<muws-p1-xs:ManagementEvent ReportTime="2005-08-31T19:08:59-04:00"> <muws-p1-xs:EventId>urn:uuid:b4694831-a328-9775-973b-66ce2bfd99e0</muws-p1-xs:EventId>

<muws-p1-xs:SourceComponent/><muws-p2-xs:Situation>

<muws-p2-xs:SituationCategory><muws-p2-xs:AvailabilitySituation/>

</muws-p2-xs:SituationCategory><muws-p2-xs:SituationTime>"2005-08-31T19:05:27-04:00"</muws-p2-xs:SituationTime><muws-p2-xs:Message>

“PDA has gone off-line.”</muws-p2-xs:Message><muws-p2-xs:Severity>4</muws-p2-xs:Severity>

</muws-p2-xs:Situation><wsrf-rp:ResourcePropertyValueChangeNotification>

<wsrf-rp:OldValue><muws-p2-xs:OperationalStatus> Available</muws-p2-xs:OperationalStatus>



15131514151515161517151815191520152115221523

152415251526

1527152815291530153115321533153415351536

153715381539154015411542154315441545

15461547

15481549155015511552155315541555155615571558155915601561156215631564156515661567

65

66

</wsrf-rp:OldValue><wsrf-rp:NewValue>

<muws-p2-xs:OperationalStatus> Unavailable</muws-p2-xs:OperationalStatus>

</wsrf-rp:NewValue></wsrf-rp:ResourcePropertyValueChangeNotification>

</muws-p1-xs:ManagementEvent>

A MUWS ManagementEvent serves as the payload of a WS-Notification message.

2.10.4 Creating a TopicSpaceMUWS defines a topic for each capability that produces an event. An implementer of a manageable resource, wants to create one or more additional topics covering any event unique to a resource..The biggest choice for an implementer is deciding upon the granularity of the additional resource-specific topics. If we make our topics too fine-grained then a manageability consumer may need to specify several topics in an event subscription list. If we make our topic definitions too coarse-grained then a manageability consumer may receive notification of unwanted events.

Fortunately, we are able to specify subtopics and use the power of XPATH expressions to provide fine-grain topics while also supporting a means for a manageability consumer to generalize on a few, broadly defined topics.

Our first step is to create a TopicSpace to define a namespace for our topics. A TopicSpace can be defined in either a WSDL or another configuration file in XML document format. Next, we define our resource-specific topics within the TopicSpace wrapper,.

For example, when creating notification topics for our PDA device, we provide a notification on a change to the battery charged condition. The battery charged condition can be grouped into five states: Fully Charged, Half Charged, Critical Level, Discharged, and Removed. To support both general as well as fine-grained notifications, our Topics definition appears as follows:

<wstop:TopicSpace name="MyPdaNotificationTopics" . . . .>

<wstop:Topic name="BatteryCondition" messageTypes="muws-p1-xs:ManagementEvent">

<wstop:Topic name="BatteryFullyCharged"messageTypes="muws-p1-xs:ManagementEvent"/>

<wstop:Topic name="BatteryHalfCharged"messageTypes="muws-p1-xs:ManagementEvent"/>

<wstop:Topic name="BatteryCriticalLevel"messageTypes="muws-p1-xs:ManagementEvent"/>

<wstop:Topic name="BatteryDischarged"messageTypes="muws-p1-xs:ManagementEvent"/>

<wstop:Topic name="BatteryRemoved"messageTypes="muws-p1-xs:ManagementEvent"/>

</wstop:Topic></wstop:TopicSpace>

In this example, a manageability consumer can subscribe on BatteryCondition and receive notification of every event related to a change in battery condition. As an alternative, a manageability consumer can subscribe on an individual subtopic, such as BatteryCriticalLevel and/or BatteryDischarged. A manageability consumer can subscribe on the select set of subtopics that are of interest.



15681569157015711572157315741575

1576

15771578157915801581158215831584

158515861587

158815891590

1591159215931594

15951596

159715981599

16001601160216031604160516061607160816091610161116121613161416151616

16171618161916201621

67

68

2.10.4.1 Topics for Resource-Specific MetricsIn this section we return to our PDA device and its resource-specific metrics example. When we add a capability with a new event to a manageability endpoint, we add a corresponding Topic to the set of Topics for our resource. By doing so, we describe the event for the added capability.

For our PDA metrics, we want an event specifically for notification of server connection failures as described in section 2.7.1). It is good practice to define a topic for each event associated with a capability that is available to a subscriber. When an event is indicated on a subtopic, the event should also be indicated on the base topic. The Topic structure may be defined as follows.

<wstop:TopicSpace name="MyPdaNotificationTopics" . . . >. . . <wstop:Topic name="PDAMetricsCapability" messageTypes="muws-p1-xs:ManagementEvent"/> <wstop:Topic name="ServerConnectionFailure" messageTypes="muws-p1-xs:ManagementEvent"> <wstop:MessagePattern Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"> //muws-p1-xs:ManagementEvent[count(pda:ServerConnectionFailureNotification)=1] </wstop:MessagePattern> </wstop:Topic></wstop:TopicSpace>

Notice that the wstop:MessagePattern prevents multiple notifications from being emitted on the same event.

The portion of the resource properties document for our PDA device exposing support for the PDAMetrics properties as well the ServerConnectionFailure topic follows:

<pda:MyPdaDeviceProperties . . .>. . . <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> muws-ev:MetricsCapability </wsnt:Topic> <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> pdae:PDAMetricsCapability </wsnt:Topic> <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> pdae:ServerConnectionFailure </wsnt:Topic> <wsnt:FixedTopicSet>true</wsnt:FixedTopicSet> <wsnt:TopicExpressionDialects> http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple </wsnt:TopicExpressionDialects> <wsnt:TopicExpressionDialects> http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Concrete </wsnt:TopicExpressionDialects></pda:MyPdaDeviceProperties>

2.11 Building and Exposing a Metadata DocumentIn this section we use the WS-Resource Metadata Descriptor specification [WS-RMD], as submitted to the OASIS WS-Resource Framework Working Group, to describe the metadata for the manageability endpoint for our PDA example.

The MUWS specification defines metadata elements for its capabilities, properties, operations, and events. This metadata provides static information associated with a manageability endpoint for a resource and provides a manageability consumer with an improved understanding of the semantics for exposed capabilities. Metadata describes the behavior of the manageability endpoint for a manageable resource. Since it is static, even if metadata is changed there is no



1622162316241625

1626162716281629

1630163116321633163416351636163716381639164016411642

16431644

16451646

1647164816491650165116521653165416551656165716581659166016611662166316641665166616671668

1669167016711672

16731674167516761677

69

70

change in the behavior of the manageability endpoint for a resource. Thus, metadata cannot be used to control a resource. The MUWS specification states that metadata elements should be maintained in a separate Metadata document that can be queried with XPath, but MUWS does not prescribe a schema for metadata documents.

WS-RMD has a simple, extensible structure defining some basic metadata elements for properties and allowing additional metadata elements. The WS-RMD document is associated with the Resource PortType with two attributes, rmd:metataDescirptor and metadataDescriptorLocation as follows:

<w.definitions . . >

<w.portType name="MyPdaDevicePortType" wsrf-rp:ResourceProperties="pda:MyPdaDeviceProperties" rmd:metadataDescriptor="pda-rmd:MyPdaDeviceMetadataDescriptor"rmd:metadataDescriptorLocation="http://example.com/services/MyPdaDevice.rmd http://example.com/services/metadata/MyPdaDevice.rmd"> . . . </w.portType>. . .</w.definitions>

Notice the “pda-rmd” prefix refers to the metadata namespace. We declare this namespace in a metadata document as described in section 2.11.1, Constructing PDA Device Metadata. This metadata document contains a GED, MyPdaDeviceMetadataDescriptor, providing the metadata for the resource properties of our PDA device. Notice the metadataDescriptorLocation attribute provides both the full pda-md namespace name as well as the physical location of this metadata document.

WS-RMD provides the general purpose metadata indicated by the MUWS specification as follow:

Mutability indicates a property value may change over time.

rmd:Property attribute mutability=”[constant|appendable|mutable]”

Modifiability indicates a property value can be set directly or as a side-effect of some other action

rmd:Property attribute modifiability=”[read-only|read-write]”

Valid Values provide the set of valid property values

<rmd:ValidValues> {any}* </rmd:ValidValues>

Valid Range provides a range of valid property values

<rmd:ValidValueRange lowerBound=”xs:anySimpleType”? upperBound=”xs:anySimpleType” />

Static Values provide a set of permanent property values

rmd:StaticValues> {any}* </rmd:StaticValues>

Notifiability indicates a notification is sent on a change to the property value

rmd:Property attribute subscribeability=”xs:boolean”

MUWS defines two additional metadata elements that apply to all properties and operations as follow:

Capability provides a list of the properties and operations supported by a particular capability. This MUWS metadata element allows a manageability consumer to inspect the details of a manageability capability.



1678167916801681

1682168316841685

1686

1687168816891690169116921693169416951696

169716981699170017011702

1703

1704

1705

17061707

1708

1709

1710

1711

17121713

1714

1715

1716

1717

17181719

172017211722

71

72

<muws-p2-xs:Capability>xs:anyURI</muws-p2-xs:Capability> *

ValidWhile indicates when a property or operation is valid for query or execution. This MUWS metadata element allows a manageability consumer to understand the expected behavior of a manageability capability.

<muws-p2-xs:ValidWhile Dialect=”xs:anyURI”> {any} * </muws-p2-xs:ValidWhile>

A manageability consumer can use XPath dialect to describe the assertions on a resource that must evaluate to true. An example of an assertion is the value of some related properties. State and Status are especially useful properties in this regard. Notice it does not make sense to make an assertion based upon the values of many properties, like metrics, since these values are not valid when a resource is not in the running state.

MUWS defines one additional metadata element that applies to all operations as follows:

PostCondition indicates how a manageability consumer can double check that a particular operation has completed successfully.

<muws-p2-xs:PostCondition Dialect=”xs:anyURI”>{any} *

</muws-p2-xs:PostCondition>

Notice that the MUWS PostCondition metadata element follows the same format as ValidWhile.

2.11.1 Constructing PDA Device MetadataConsider the resource properties, other than metrics, of our PDA device as developed so far. We create a WS-RMD compliant document for MyPdaDevice as follows:

<rmd:Definitions . . . targetNamespace="http://example.com/services/MyPdaDevice.rmd">

<rmd:MetadataDescriptor name="PdaDeviceMetadataDescriptor" interface="pdaw:MyPdsDevicePortType" wsdlLocation="http://example.com/services/MyPdaDevice.wsdl http://example.com/wsdl/Identification.wsdl">

<rmd:Property path="muws-p1-xs:ResourceId" mutability="constant" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity </muws-p2-xs:Capability> </rmd:Property>

<rmd:Property path="muws-p1-xs:Description" mutability="mutable" modifiability="read-write"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p2-xs:Capability> </rmd:Property>

<rmd:Property path="muws-p1-xs:Caption" mutability="mutable" modifiability="read-write"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p2-xs:Capability> </rmd:Property>



1723

172417251726

172717281729

17301731173217331734

1735

17361737

173817391740

1741

174217431744

174517461747

174817491750175117521753

17541755175617571758175917601761

17621763176417651766176717681769

17701771177217731774177517761777

73

74

<rmd:Property path="muws-p1-xs:Version" mutability="mutable" modifiability="read-write"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p2-xs:Capability> <rmd:StaticValues> <muws-p1-xs:Version>Version 1.4.2, January 2005</muws-p1-xs:Version> </rmd:StaticValues> </rmd:Property>

<rmd:Property path="muws-p1-xs:ManageabilityCapability" mutability="constant" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics </muws-p2-xs:Capability> <rmd:StaticValues> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://example.org/capabilities/TranslateableDescription </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Relationships </muws-p1-xs:ManageabilityCapability> </rmd:StaticValues> </rmd:Property>

<rmd:Property path="muws-p2-xs:OperationalStatus" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus </muws-p2-xs:Capability> <rmd:ValidValues> <muws-p2-xs:OperationalStatus>Available</muws-p2-xs:OperationalStatus> <muws-p2-xs:OperationalStatus>PartiallyAvailable</muws-p2-xs:OperationalStatus> <muws-p2-xs:OperationalStatus>Unavailable</muws-p2-xs:OperationalStatus> <muws-p2-xs:OperationalStatus>Unknown</muws-p2-xs:OperationalStatus> </rmd:ValidValues> </rmd:Property>

<rmd:Property path="muws-p2-xs:CurrentTime" mutability="mutable" modifiability="read-only">



17781779178017811782178317841785178617871788

178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827

1828182918301831183218331834183518361837183818391840184118421843

1844184518461847

75

76

<muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> </rmd:Property>

</rmd:MetadataDescriptor></rmd:Definitions>

Notice our MetadataDescriptor, PdaDeviceMetadataDescriptor is highlighted above. This fragment is directly drawn from the MUWS specification. Also notice that both WS-RMD and MUWS metadata attributes are defined within the <rmd:Property> element.

Finally, notice that the Version and ManageabilityCapability metadata elements are populated with a list of static values. These values allow a manageability consumer to inspect static manageability information about a resource when the resource is not instantiated. These values also allow a manageability consumer to find a resource supporting a given capability and to see a detailed list of all supporting properties and operations for a capability. In the above example, the list of ManageabilityCapability properties do not change at runtime for the resource.

2.11.2 Metric MetadataMetadata provides a useful means to describe the behavior and characteristics of metric properties defined for a resource. Metric metadata is specified via six elements. These elements are extensions specified in MUWS Part 2. These elements are as follow:

Element Use

Capability identifies the property as a metric

GatheringTime indicates the circumstance under which the value of a metric is updated

CalculationInterval when the associated GatheringTime is 'periodic', provides the frequency with which the value of a metric is collected

MetricGroup identifies a metric as included within one or more groupings of metrics

ChangeType indicates how the value of a metric is interpreted

TimeScope indicates if the value of a metric is collected over some elapsed period of time

ChangeType and Timescope are required metadata elements for a metric property and are described in detail as follow:

ChangeType indicates how the value of a metric is interpreted. A metric property conforms to a behavior as indicated by its ChangeType. The possible behaviors are as follow:

Counter The value only increases across successive inspections.

Gauge The value may increase or decrease across successive inspections.

Unknown The change behavior for the value is not known or cannot be described



1848184918501851

185218531854

185518561857

185818591860186118621863

1864186518661867

18681869

18701871

1872

18731874

18751876

77

78

TimeScope indicates if the value of a metric is collected over some elapsed period of time. This metadata element indicates which metric attributes qualify its value. The TimeScope of a metric property must be characterized in one of three ways as follow:

Interval The value was collected over some time interval prior to its last update. The Duration attribute provides the elapsed time of the interval and the LastUpdated attribute provides the time at which the interval ended..

PointInTime The value was collected at a single point in time. The LastUpdated attribute provides the time at which the collection occurred.

SinceReset The value was collected since the last reset of a resource, or since the manageable resource first started collecting data on this metric, whichever is most recent. The ResetAt and CurrentTime values are used to calculate the elapsed time of the collection interval and the time at which the interval ended. It is recommended the LastUpdated attribute be used to provide the time at which the most recent event occurred.

The following table summarizes when to use the attributes of a metric as indicated by its TimeScope. A represented a required attribute and a represents an impermissible use of an attribute):

TimeScope ResetAt LastUpdated Duration Notes

Interval permitted Metric collection interval (value of the Duration attribute) is up to the time of the last update (LastUpdated value)

PointInTime Other attributes must not be used

SinceReset recommended Use ResetAt time and CurrentTime to calculate the collection interval

The LastUpdated attribute specifies the time during the collection interval at which the most recent event occurred

The metadata for a metric property must also specify a GatheringTime for the value of a metric. GatheringTime is an enumeration indicating the circumstance under which the value of a metric is updated. GatheringTime may be one of four values as follow:

OnChange The value is updated whenever a change occurs.

Periodic The value is updated on a regularly scheduled basis.

OnDemand The value is updated whenever a request for the metric is processed.

Unknown It is unknown when the value is updated.

If the GatheringTime=”Periodic”, then the muws-p2-xs:CalculationInterval must also be specified to indicate the interval at which the metric is updated.



1877187818791880

1881188218831884

188518861887

18881889189018911892189318941895

189618971898

189919001901

1902

1903

1904

1905

19061907

79

80

2.11.2.1 PDA Resource-specific MetricsThe resource-specific metric properties of our PDA device are identified in section 2.7.1 of this primer. Our metrics must be defined in terms of the appropriate metric metadata elements, as discussed above. A summary of our PDA metric and associated metadata elements is as follows:

PDA Metric ChangeType TimeScope GatheringTime

FailedConnections Counter SinceReset OnChange

MessagesReceived Gauge Interval

Duration=30 mins

OnChange

AverageResponseTime Gauge Interval

Duration=10 mins

Periodic

CalcInterval=2 mins

MemoryInUse Gauge PointInTime OnDemand

In addition to the specification of resource-specific metric metadata, our PDA metrics must be tagged with the capabilities they support. In this primer, our PDA metrics are tagged as supporting the Metrics and PDAMetrics capabilities. We also define a MetricGroup to group together all metrics related to a remote device. The metadata for our PDA resource-specific metric properties follows:

<rmd:Definitions . . .>. . . <rmd:Property path="pda:FailedServerConnections" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> <muws-p2-xs:ChangeType>Counter</muws-p2-xs:ChangeType> <muws-p2-xs:TimeScope>SinceReset</muws-p2-xs:TimeScope> <muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime> <muws-p2-xs:MetricGroup> http://example.org/services/RemoteMetrics </muws-p2-xs:MetricGroup> </rmd:Property> <rmd:Property path="pda:MessagesReceived" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> <muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType> <muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope> <muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime> <muws-p2-xs:MetricGroup> http://example.org/services/RemoteMetrics </muws-p2-xs:MetricGroup> </rmd:Property> <rmd:Property path="pda:AverageResponseTime" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability>



1908190919101911

19121913191419151916

19171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954

81

82

http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> <muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType> <muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope> <muws-p2-xs:GatheringTime>Periodic</muws-p2-xs:GatheringTime> <muws-p2-xs:CalculationInterval>PT2M</muws-p2-xs:CalculationInterval> <muws-p2-xs:MetricGroup> http://example.org/services/RemoteMetrics </muws-p2-xs:MetricGroup> </rmd:Property> <rmd:Property path="pda:MemoryInUse" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> <muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType> <muws-p2-xs:TimeScope>PointInTime</muws-p2-xs:TimeScope> <muws-p2-xs:GatheringTime>OnDemand</muws-p2-xs:GatheringTime> <muws-p2-xs:MetricGroup> http://example.org/services/RemoteMetrics </muws-p2-xs:MetricGroup> </rmd:Property>

<rmd:Operation path="pda:ResetServerConnectionMetric" idempotent="false"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> </rmd:Operation>

</rmd:Definitions>

2.11.2.2 Example PDA Resource Properties Document with MetricsThe resource properties document, as provided by the manageability endpoint of a PDA, might expose run-time metric values as follow:

<pda:MyPdaDeviceProperties . . .>. . .

<muws-p2-xs:CurrentTime>2005-08-11T12:30:56Z</muws-p2-xs:CurrentTime> <pda:FailedServerConnections LastUpdated="2005-07-25T08:25:53Z" ResetAt="2005-06-01T12:01:16Z">5</pda:FailedServerConnections> <pda:MessagesReceived LastUpdated="2005-08-11T12:26:43Z" Duration="PT30M">14</pda:MessagesReceived> <pda:AverageResponseTime LastUpdated="2005-08-11T12:30:00Z" Duration="PT10M">PT0.0107S</pda:AverageResponseTime> <pda:MemoryInUse LastUpdated="2005-08-11T12:30:56Z">66</pda:MemoryInUse></pda:MyPdaDeviceProperties>

Given an understanding of our metric metadata, the interpretation of this information by a manageability consumer is straightforward.



19551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983

1984198519861987198819891990199119921993

19941995

199619971998

19992000

20012002200320042005200620072008200920102011201220132014

20152016

83

84

A manageability consumer can draw several conclusions based upon a comparison of this metric information with the currentTime including the following:

Within the past 2 months 11 day and approximately 30 seconds, this PDA experienced 5 connection failures, with the last one occurring July 25.

This PDA has received no messages in the last 4 seconds

In the half hour before that last message, this PDA received 14 messages.

The average response time experienced by this PDA between 12:20 and 12:30 was .0107 seconds

The average response time was calculated approximately 1 minute (56 seconds) before the manageability consumer made its request

When the request was made, the manageability endpoint for this PDA calculated the MemoryInUse metric as well as determined that memory in use is 66% of total capacity

Notice that the semantics of MessagesReceived and AverageResponseTime metrics permit a ResetAt attribute. Consider the ResetAt attribute information as follows:

<pda:MessagesReceived LastUpdated="2005-08-11T12:26:43Z" Duration="PT30M" ResetAt="2005-08-11T12:15:36Z"> 5 </pda:MessagesReceived>

Notice the ResetAt time occurred during the 30 minute duration in which the MessagesReceived metric was collected. This means the count of 5 messages occurred during the 11 minutes 7 seconds between the ResetAt time and the LastUpdated time. Since the occurrence of a reset is a real possibility during the collection interval of a metric, a manageability consumer must accommodate any reset when interpreting or presenting metrics. For example, the manageability consumer may report the metric information as partial or reject the metric information as invalid.

2.12 StateThe MUWS State capability provides an extensible means of exposing the current state and state model of a resource. The state model of a resource is identified by a URI and there is no XML representation for a state model itself. Note that a state model may be standardized and that a standard state model can be extended into a resource-specific state model. Also note that a state model may be entirely resource-specific.

MUWS capabilities like Configuration and Metrics follow a pattern that we use and extend as we create appropriate XML that exposes the state of a resource. As with the MUWS Configuration and Metric capabilities, the MUWS State capability defines some standard schema types for common elements of a State capability. These common elements include the State property types, transition descriptions, and events. A complete example of a well-defined State capability is presented in the OperationalState example in section 3.2.4.1 of MUWS Part 2.

To extend the MUWS State capability we must define a name for each state property, transition, state, and state model. A state property has a type of ‘muws:CategoryType’. A state property can be sub-typed to expose a more specific state when the MUWS State capability is extended.

This primer recommends that designers define both a property exposing the current state of a resource as well as a property exposing the state immediately prior to the last state transition. This practice allows a manageability consumer to determine how long a resource has been in the current state as well as its prior state. A manageable resource should emit a notification in the event a state transition occurs.



20172018

20192020

2021

2022

20232024

20252026

202720282029

20302031

20322033203420352036

203720382039204020412042

204320442045204620472048

204920502051205220532054

205520562057

20582059206020612062

85

86

It is a usual practice for the value of a resource-specific State property to be restricted to a relatively limited and static set of possible values. In section 2.12.1, State Model Metadata, we describe how to predefine the set of possible values in the metadata document for our PDA device.

Typically, a resource-specific State property is a read-only value and some resource-specific operations are used to effect a change to the state of a resource.

In our example, we describe the DeviceState model for our PDA device. We want to expose the Off, Initializing, and Connected states of our PDA resource. We also want to expose the ServerConnected, NetworkConnected, Synchronizing, and Idle substates of the Connected state.

These potential values are described for our PDA device as follow:

<pda:DeviceState> <pda:Off/></pda:DeviceState>

<pda:DeviceState> <pda:Initializing/></pda:DeviceState>

<pda:DeviceState> <pda:NetworkConnected> <pda:Connected/> </pda:NetworkConnected> </pda:DeviceState>

<pda:DeviceState> <pda:ServerConnected> <pda:Connected/> </pda:ServerConnected> </pda:DeviceState>

<pda:DeviceState> <pda:Synchronizing/></pda:DeviceState>

<pda:DeviceState> <pda:Idle/></pda:DeviceState>

We can also restrict the valid values of DeviceState using schema. This allows a manageability consumer to validate exposed DeviceState information for our PDA device. An example of validating schema for DeviceState follows:

<!—PDA::DeviceState -->

<xs:complexType name="DeviceStateType"> <xs:complexContent> <xs:extension base="muws-xs2:StateType"/> </xs:complexContent></xs:complexType>

<xs:element name="DevceState" type="pda:DeviceStateType"/>

<xs:element name="Off"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"/> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="Idle"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"/> </xs:complexContent>



2063206420652066

20672068

206920702071

2072

207320742075

2076207720782079

208020812082208320842085

208620872088208920902091

2092209320942095

2096209720982099

210021012102

2103

2104210521062107210821092110

21112112211321142115211621172118

211921202121212221232124

87

88

</xs:complexType></xs:element>

<xs:element name="Initializing"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"/> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="Synchronizing"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"/> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="Connected"> <xs:complexType> <xs:complexContent>

<xs:restriction base="pda:DeviceStateType"/> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="NetworkConnected"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"> <xs:sequence> <xs:element ref="pda:Connected"/> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="SystemConnected"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"> <xs:sequence> <xs:element ref="pda:Connected"/> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType></xs:element>

Transitions are also named and have a transition type which provides context for the transition being recorded in the event or property. We define a transition in the resource properties document schema as follows:<xs:element name="LastStateTransition" type="muws-p2-xs:StateTransitionType"/>

Thus, a state transition might appear as follows:

<muws-p2-xs:StateTransition Time="xs:dateTime" TransitionIdentifier="xs:anyURI"? > <muws-p2-xs:EnteredState>muws-p2-xs:StateType</muws-p2-xs:EnteredState> <muws-p2-xs:PreviousState>muws-p2-xs:StateType</muws-p2-xs:PreviousState> ? {any} *</muws-p2-xs:StateTransition>

See section 5.1, Defining a Taxonomy in WSDM, for more information on defining the taxonomy in the schema above.

If the valid transitions for our PDA device are as follow:



21252126

21272128212921302131213221332134

21352136213721382139214021412142

21432144214521462147214821492150

215121522153215421552156215721582159216021612162

21632164216521662167216821692170217121722173217421752176217721782179

2180

218121822183218421852186

21872188

2189

89

90

Previous State Current StateOff Initializing

Initializing ConnectedConnected Synchronizing

Synchronizing IdleIdle SynchronizingIdle Off

Synchronizing OffConnected Idle

Then the state diagram describing these transitions is as follows:

Thus, the XML for a transition from Off to Initializing is as follows:

<pda:LastStateTransition Time="2004-03-11T11:30:56Z" TransitionIdentifier="http://example.com/transitions/Off/Inializing"> <muws-p2-xs:EnteredState><Initializing/></muws-p2-xs:EnteredState> <muws-p2-xs:PreviousState><Off/></muws-p2-xs:PreviousState></pda:LastStateTransition>

This information is sent as part of a notification of the state change event. A state event occurs whenever a transition is made and is published on the StateCapability topic. A manageability consumer can use the topic name to filter the content of a state event. We recommend a topic be defined per capability. Since we have just defined a new capability, DeviceState, that extends the State capability, we should also define a DeviceState topic. We can publish events on the DeviceState topic as well.

So the resource properties document for our PDA device now exposes two new properties, DeviceState and LastDeviceStateTransition. We also update the ManageabilityCapabilities property to expose the capability URI for muws:State and pda:DeviceState. Based upon the definitions of state provided above, an instance of the resource properties document for our PDA device might appear as follows:

<pda:MyPdaDeviceProperties . . .>. . . <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://example.com/capabilities/DeviceState </muws-p1-xs:ManageabilityCapability>

. . .

<pda:DeviceState > <pda:Initializing/> </pda:DeviceState>

<pda:LastStateTransition Time="2004-03-11T11:30:56Z"



Off

Initializing Connected Synchronizing Idle

21902191

2192

21932194219521962197

219821992200220122022203

22042205220622072208

22092210221122122213221422152216

22172218

2219222022212222

22232224

91

92

TransitionIdentifier="http://example.com/transitions/Off/Inializing"> <muws-p2-xs:EnteredState><pda:Initializing/></muws-p2-xs:EnteredState> <muws-p2-xs:PreviousState><pda:Off/></muws-p2-xs:PreviousState> </pda:LastStateTransition>


Usually, the state of a resource is changed by invoking an appropriate operation rather than by directly manipulating the state property of a manageable resource. This approach helps ensure there is only one appropriate way to change the state of a manageable resource. For example, we can define a 'Shutdown' operation that changes the state of our PDA device. The Shutdown operation is defined in the WSDL document for our PDA device. In the schema of the resource properties document for our PDA device, we define the elements involved in the Shutdown operation as follow:

<xs:element name="Shutdown"> <xs:complexType/> </xs:element>

<xs:element name="ShutdownResponse"> <xs:complexType/> </xs:element>

The WSDL for the Shutdown operation follows:

<w:message name="ShutdownRequest"> <w:part name="document" element="pda:Shutdown"/> </w:message>

<w:message name="ShutdownResponse"> <w:part name="document" element="pda:ShutdownResponse"/> </w:message>

<w:operation name="Shutdown"> <w:input name="ShutdownRequest" message="pdaw:ShutdownRequest" wsa:Action= "http://example.org/services/MyPdaDevice.wsdl/DeviceState/ShutdownRequest"/> <w:output name="ShutdownResponse" message="pdaw:ShutdownResponse" wsa:Action= "http://example.org/services/MyPdaDevice.wsdl/DeviceState/ShutdownResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> <w:fault name="InvalidStatusFault" message="pda:InvalidStatusFault" wsa:Action="http://example.org/services/MyPdaDevice.wsdl/MyPdaDevicePortType/InvalidStatusFault"/> </w:operation>

See Appendix A of this primer for the complete WSDL definition of this operation, including bindings.

2.12.1 State Model MetadataThe state model of our PDA device is exposed in its metadata document. Valid values for the DeviceState property are listed to provide a manageability consumer with an understanding of the state model of our PDA device. This state model in our metadata follows:

<rmd:Definitions>. . . <rmd:Property path="pda:DeviceState" mutability="mutable"



2225222622272228

22292230

2231223222332234223522362237

223822392240

2241224222432244

2245

224622472248

2249225022512252

22532254225522562257225822592260226122622263226422652266226722682269227022712272

22732274

2275227622772278

2279228022812282

93

94

modifiability="read-only" <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/DeviceState </muws-p2-xs:Capability> <rmd:ValidValues> <pda:DeviceState><pda:Off/></pda:DeviceState> <pda:DeviceState><pda:Initializing/></pda:DeviceState> <pda:DeviceState> <pda:NetworkConnected><pda:Connected/></pda:NetworkConnected> </pda:DeviceState> <pda:DeviceState> <pda:ServerConnected><pda:Connected/></pda:ServerConnected> </pda:DeviceState> <pda:DeviceState><pda:Synchronizing/></pda:DeviceState> <pda:DeviceState><pda:Idle/></pda:DeviceState> </rmd:ValidValues> </rmd:Property>

<rmd:Property path="pda:LastStateTransition" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/DeviceState </muws-p2-xs:Capability> </rmd:Property>

<rmd:Operation path="pda:shutdown" idempotent="false"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p2-xs:Capability> <rmd:ValidWhile Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"> count(/pda:MyPdaDeviceProperties/pda:DeviceState/pda:Off) = 0 </rmd:ValidWhile> <rmd:PostCondition Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"> /pda:MyPdaDeviceProperties/pda:DeviceState/pda:Off </rmd:PostCondition> </rmd:Operation>. . .</rmd:Definitions>

Notice the metadata for the Shutdown operation in the XML above. This metadata associates the Shutdown operation with the State capability. The Shutdown operation is not idempotent as its invocation affects the behavior of our PDA device. The Shutdown operation has a ValidWhile element and a PostCondition element as described in section 2.11, "Building and Exposing a Metadata Document". The ValidWhile element indicates that the Shutdown operation is valid only if the current state of our PDA device is not ‘Off’. The PostCondition element indicates that when the Shutdown operation is complete, the current state of our PDA device is ‘Off’.

2.13 Advertising a ResourceBy advertising the existence of a resource we facilitate the discovery of the resource by a manageability consumer. The existence of a resource is made known in several ways. In this section we discuss the Advertisement capability as defined in part 2 of the MUWS specification. Section 3.2 of this primer, "The Relationship Capability", presents other useful methods a manageability consumer can use to discover the existence of a resource.



22832284228522862287228822892290229122922293229422952296229722982299230023012302

23032304230523062307230823092310231123122313

23142315231623172318231923202321232223232324232523262327232823292330

2331233223332334233523362337

233823392340234123422343

95

96

While the MUWS Advertisement capability does not define any properties or operations, it does define four notification topics. There is a topic for resource creation and a topic for resource discovery. There is also a topic for resource destruction and a topic for loss of a resource connection. While events published on the ManageableResourceCreation topic indicate that a resource was created, events published on the ManageabilityEndpointCreation topic indicate that a manageability endpoint for an existing resource was created. Events published on the two destruction topics have a similar meaning.

The Advertisement capability can be exposed by any resource having knowledge of the creation or destruction of some other resource. Examples of resources that should expose the Advertisement capability include ServiceGroups, Registries, and the UDDI. If we consider a subscription as a resource, then any resource that supports the WS-BaseNotification Subscribe operation could also support the Advertisement capability. This is because a resource is created every time a manageability consumer invokes the Subscribe operation.

2.14 Operable CollectionsWhen a manageability consumer is responsible for a large number of resources, it is often desirable to group the resources into an operable collection. An operable collection is useful when organizing a resource map, aggregating a status for an administrative domain, an enterprise business application, or an autonomous system consisting of a complex set of inter-related processes.

An operable collection is also useful when a manageability consumer wishes to invoke an operation on all of or a subset of the resources in an operable collection. With WSDM, we suggest an operable collection of resources should be represented as, and accessible as a WS-ServiceGroup [WS-ServiceGroup]. A WS-ServiceGroup may be extended to support additional operations having collection-specific semantics. An operation may apply to the collection itself, as when a collection is cloned, or an operation may apply to each member of an operable collection, as when a "start" operation is invoked.

When we develop an operation that applies to each member of an operable collection, the operation may be invoked directly on each member as a pass through, or a start operation that is supported by the manageability endpoint of each member of an operable collection. For example, a start operation is supported by the manageability endpoint of the operable collection itself as well as by each member of the operable collection. This approach is represented as follows:

AppStartUpGroup

Wssg:QueryApp:Start

NetworkChannel

NW:Start

BusinessProcess

BP:Start

Container

Container:Start

Alternatively, we can develop an operation that is translated from a generic form into a resource-specific form for a member of the operable collection. Thus, the 'start' operation on an operable collection could invoke an 'initialize' operation on one member and an 'instantiate' operation on another member.



2344234523462347234823492350

235123522353235423552356

235723582359236023612362

2363236423652366236723682369

23702371237223732374

23752376237723782379

97

98

AppStartUpGroup

Wssg:QueryApp:Start

NetworkChannel

NW:Connect

BusinessProcess

BP:StartProcess

Container

Container:Initialize

Since it may be difficult to design a general purpose distributed operation with consistent semantics for each member of an operable collection, we must consider and accommodate any resource-specific behavior of a member.

Thus, the targeted members of an operation dictate various handling methods in the processing of the distributed operation such as dealing with failures, and differing transactional semantics. Some considerations we need to address when implementing a distributed operation for an operable collection are as follow:

Targets – It is often useful to distribute an operation to a subset of members in an operable collection. Selecting the subset of members targeted by an operation can be achieved by adding a rule or a list identifying each target of an operation in its input message. Alternatively, a manageability consumer could first query the operable collection and populate a new collection with just the targeted members. The manageability consumer could then simply invoke an operation on the new operable collection containing just the targeted members. Targeting approaches such as this allow a 'pass through' type operation signature on an operable collection to continue to match the operation signature on its targeted members.

Responses – A distributed operation can return its response(s) to a manageability consumer in different ways. A distributed operation can be implemented to form a synchronous response as when all responses from all targets are collected and then returned to a manageability consumer boxcarred or summarized in a single response message to a manageability consumer. Alternatively, a distributed operation can be implemented to form an asynchronous response as when each response from each target is individually returned to a manageability consumer. If a distributed operation implements an asynchronous response, then the manageability consumer is responsible for correlating each response with its target as well as for handling any missing response(s) from a target.

Transactional semantics A distributed operation may be implemented such that no association exists between operations on its target members. For example, an operation on a target can fail without affecting other operations on this or other targets. Alternatively, a distributed operation may be implemented such that each operation on its target members is part of a single transaction. For example, if one operation on a target fails, then the entire distributed operation is rolled back for any successfully completed or outstanding operation on its targets.

Serialized operations – Some operations can be sent to every target member of an operable collection at the same time. If the targeted members of an operable collection are few, then it may be appropriate to execute the distributed operation on the targets one at a time, waiting for each operation on a target to complete before initiating another operation on a target.

An operable collection is exposed as a WS-ServiceGroup interface. For our ‘Start’ operation we want to return a response that summarizes the responses from the operation(s) on each target and that provides an overall indication for the distributed operation. Our example 'Start' operation may not complete successfully unless all members start. Our example 'Start" operation is exposed as follows:



2380238123822383

2384238523862387

23882389239023912392239323942395

239623972398239924002401240224032404

240524062407240824092410

2411241224132414

24152416241724182419

99

100

<w:portType name="AppStartUpGroup" wsrf-rp:ResourceProperties="wsrf-sg:AppStartUpGroupRP">

<w:operation name="GetResourceProperty"> <w:input name="GetResourcePropertyRequest" message="wsrf-rpw:GetResourcePropertyRequest" /> <w:output name="GetResourcePropertyResponse" message="wsrf-rpw:GetResourcePropertyResponse" /> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" /> <w:fault name="ResourceUnknownFault" message="wsrf-rw:ResourceUnknownFault" /> </w:operation>

<w:operation name="Add"> <w:input name="AddRequest" message="wsrf-sgw:AddRequest"/> <w:output name="AddResponse" message="wsrf-sgw:AddResponse"/> <w:fault name="ContentCreationFailedFault" message="wsrf-sgw:ContentCreationFailedFault"/> <w:fault name="UnsupportedMemberInterfaceFault" message="wsrf-sgw:UnsupportedMemberInterfaceFault"/> <w:fault name="AddRefusedFault" message="wsrf-sgw:AddRefusedFault"/> <w:fault name="ResourceUnknownFault" message="wsrf-rw:ResourceUnknownFault" /> </w:operation>

<w:operation name="Destroy"> <w:input message="wsrl:DestroyRequest" /> <w:output message="wsrl:DestroyResponse" /> <w:fault name="UnknownResource" message="wsrl:ErrorMessage" /> <w:fault name="UnableToDestroyResource" message="wsrl:ErrorMessage" /> </w:operation>

<w:operation name="Start"> <w:input message="app:StartRequest" /> <w:output message="app:StartResponse" /> <w:fault name="UnknownResource" message="app:ErrorMessage" /> <w:fault name="UnableToCompleteOperation" message="app:ErrorMessage" /> </w:operation> </w:portType>

Notice that the interface above simply uses the WS-RF ResourceProperties interfaces, the WS-RF Add and Destroy operations, plus our new ‘Start’ operation for the application startup group. If a ‘Start’ operation is expected to be supported on all members of an operable collection, then we suggest creating a content rule for this portType as follows:

<wsrf-sg:MembershipContentRule MemberInterface="app:AppStart"? ContentElements="wsdm:OperationalStatus"/>

Notice that if we create an operable collection as a WS-ServiceGroup, then we do not also need a normative specification. This is true since we simply rely upon a common Web services application development practice by extending WS-ServiceGroup.



24202421

24222423242424252426242724282429243024312432

2433243424352436243724382439244024412442244324442445

244624472448244924502451245224532454

2455245624572458245924602461246224632464

2465246624672468

2469247024712472

247324742475

101

102

3 Building RelationshipsThe existence of a relationship between resources is considered important information for any manageability consumer. This chapter illustrates how to build relationships into the resource properties document of a manageable resource. This chapter also illustrates how a manageability consumer queries a manageable resource for its relationships and how a manageability consumer accesses information about a relationship that is itself represented by a WS-Resource.

The Relationship capability may be exposed by a WS-Resource that is not also a WSDM manageable resource. In other words, a WS-Resource exposing the Relationship capability may not also expose the MUWS Identity capability. In WSDM, a MUWS relationship is a management related concept that is important when managing a resource rather than when using the functional or business aspects of a resource. Notice that a WS-Resource exposing the Relationship capability is not also required to support the WSDM management model. Nevertheless, if a WS-Resource reporting a relationship is also a WSDM manageable resource, then the WS-Resource should include the relevant manageability capability URI among its ManageabilityCharacteristics.

The two capabilities related to relationships as defined in MUWS Part 2 are the MUWS Relationship capability discussed in section 3.2 below and the RelationshipResource capability discussed in section 3.3.2 below.

3.1 WSDM Relationships and UML AssociationsThe Unified Modeling Language (UML) [UML] specifies several types of relationships between model elements, including association, dependency, generalization and realization. A UML association is represented as a line connecting model elements. While the UML allows an association to connect three or more elements, the typical representation of a UML association connects just two class elements.

In MUWS, a relationship is modeled as a UML association and connects an instance of class elements as follow:

An instance of Class1 is designated as playing role1 in AnAssociation and similarly for an instance of Class2. A multiplicity is assigned to each class in AnAssociation. The multiplicity designates how many instances of a class may participate in an instance of AnAssociation. For example, if Class1 is Company Class2 is Person and AnAssociation is Employment, then the role of the Company is employer, and the role of the Person is employee. In our hypothetical domain, a Person can be either unemployed or employed by one company and a Company must have at least one employee up to any number. The Employment association may be represented in UML as follows:



247624772478247924802481

248224832484248524862487248824892490

249124922493

249424952496249724982499

25002501

250225032504250525062507250825092510

2511

103

104

The example above is typical of a relationship modeled in the UML. A specific instance of a UML association is called a link and a UML link consists of an ordered set of participants. For example, if Widgets Inc employs Mary, Joe, and Jane, then an Employment association link exists for Widgets Inc. and Mary, for Widgets Inc and Joe, and, for Widgets Inc and Jane. A link does not accommodate participant multiplicity greater than one. In other words, in a link there exists only one participant for each role.

Notice that a MUWS relationship corresponds to an association link in the UML. A MUWS relationship consists of an ordered set of participants for an association link. A UML association corresponds to a MUWS relationship type. Thus, a WS-Resource is similar to the UML classifier, and can participant in any number of MUWS relationships or MUWS relationship types.

A MUWS relationship is similar to a UML association link, since neither accommodates participant cardinality greater than one. Thus, for the above example, a MUWS relationship type, Employment, would represent the association, and a separate MUWS relationship would exist for each of the three Employment association links.

On the other hand, a difference exists in that MUWS does not recognize the distinction UML makes between an association relationship and a dependency relationship. In MUWS, a relationship between resources that might be modeled as an instance of a dependency relationship in UML would still be treated as a MUWS relationship. In this regard, WSDM closely follows the CIM in treating a dependency as an association, via the CIM_Dependency class. See section 3.3, Error: Reference source not found, for additional discussion of UML Association Classes.

3.1.1 Defining a Relationship TypeAs discussed above, the UML association is represented as a MUWS relationship type. In this section we define a MUWS relationship type in which our PDA or similar device can participate. For our example, we define a relationship type for expressing the association our PDA device has with a server and infrastructure necessary for an application communications gateway. We call this association the "Gateway" relationship type. We define the necessary XML element at the end of our LocalDefinitions schema document, as described in section Error: Reference source not found of this primer, so that we share this relationship type with server resources instead of limiting the use of this relationship type to just MyPdaDevice resources. The XML defining our Gateway relationship type appears as follows:

<xs:element name="Gateway"> <xs:annotation> <xs:documentation> The Gateway association is intended to be used as a relationship type between devices such as PDAs and servers. This type has 2 associated roles, one for the device, the other for the Server. Each role must appear in exactly one Participant element in the relationship. The roles are specified using the following URIs: http://example.org/services/MyPdaDevice.xsd/role/device http://example.org/services/MyPdaDevice.xsd/role/server </xs:documentation> </xs:annotation> <xs:complexType> <xs:complexContent> <xs:extension base="muws-p2-xs:RelationshipTypeType"/> </xs:complexContent> </xs:complexType> </xs:element>

Note that the xs:annotation/xs:description element is not required by MUWS. However, we consider its use a good way to express the semantics associated with the Gateway relationship type.



251225132514251525162517

2518251925202521

2522252325242525

2526252725282529253025312532

2533253425352536253725382539254025412542

254325442545254625472548254925502551255225532554255525562557255825592560

256125622563

105

106

In many management models, a relationship type is derived from a more general relationship type. For example, we could derive the Gateway relationship type from a more general relationship type, "ConnectionTypes", as follows:

<xs:element name="Gateway"> <xs:complexType> <xs:complexContent> <xs:extension base="exh:ConnectionTypes"/> </xs:complexContent> </xs:complexType> </xs:element>

Notice that the exh:ConnectionTypes element is a relationship type defined in the exh schema document. See Appendix A for a complete definitions of these relationship types.

3.2 The Relationship CapabilityThe MUWS Relationship capability defines one property, Relationship, and one message exchange, QueryRelationshipsByType. Nevertheless, incorporating relationships into our resource properties document introduces several highly complex structures into our object model and schema. This section shows how to revise our example schema and WSDL documents to handle these structures. A resource that does not support the MUWS Relationships capability does not include the Relationship property in its schema document and does not include the QueryRelationshipsByType message exchange in its WSDL document.

The MUWS Relationship capability is optional. A resource is not required to expose this capability in order to be WSDM compliant. Moreover, a resource exposing information on relationships need not be a participant in any exposed relationship. This behavior may be seen in a resource acting as a registry and exposing relationships among registered resources.

We need to add a reference to the MUWS Relationship property in order to support the Relationship capability. We add this reference to the schema of our resource properties document for MyPdaDevice. Since the WS-ResourceProperties specification says the order of properties in a document schema is not relevant, we simply add our new property at the end of the list of properties already present as follows:

<xs:element ref="muws-p2-xs:Relationship" minOccurs="0" maxOccurs="unbounded"/>

Once support for the Relationship property is implemented, we use existing resource properties access message exchanges to retrieve values for instances of the MUWS Relationship property. In the next section, we discuss what relationship information is contained in these values.

3.2.1 Relationships in the Resource Properties DocumentA resource needs to include one Relationship property in its resource properties document for each MUWS relationship in which it participates. Each relationship property is a complex element containing a name, the relationship type and a child element for each participant in the relationship. For example, for our PDA device to report its relationship with a server, the myPdaDeviceServer resource properties document would include a Relationship property instance as follows:

<pda:MyPdaDeviceProperties . . .>. . . <muws-p2-xs:Relationship> <muws-p2-xs:Name>MyPdaDevice to MyPdaDeviceServer</muws-p2-xs:Name> <muws-p2-xs:Type> <exh:Gateway> <exh:ConnectionTypes/> </exh:Gateway> </muws-p2-xs:Type>



256425652566

2567256825692570257125722573

25742575

25762577257825792580258125822583

2584258525862587

25882589259025912592

25932594

259525962597

2598259926002601260226032604

260526062607260826092610261126122613

107

108

<muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> wsa:MyPdaDeviceManageabilityEndpointAddress </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>  urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 </muws-p1-xs:ResourceId> <muws-p2-xs:Role> http://example.org/services/MyPdaDevice.xsd/role/device </muws-p2-xs:Role> </muws-p2-xs:Participant> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> wsa:MyPdaDeviceServerManageabilityEndpointAddress </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>  urn:uuid:adf9926c-19df-440a-528e-f4813b3b715f </muws-p1-xs:ResourceId> <muws-p2-xs:Role> http://example.org/services/MyPdaDevice.xsd/role/server </muws-p2-xs:Role> </muws-p2-xs:Participant> ...  </muws-p2-xs:Relationship></pda:MyPdaDeviceProperties>

Notice the “exh” namespace refers to the LocalDefinitions schema as described in section Error: Reference source not found and the Gateway relationship type is a subtype of exh:ConnectionTypes, as defined in the LocalDefinitions schema in Appendix A.

Notice the Type element is required. However, the muws-p2-xs:Name element is optional. The Name is a human-readable designation assigned to a particular MUWS relationship type by a resource. Information about each Participant in a MUWS relationship must be provided. In MUWS, a relationship must have at least two Participant elements. If a resource is a WSDM manageable resource, then the muws-p1-xs:ManageabilityEndpointReference and muws-p1-xs:ResourceId elements must be present within the Participant element. We highly recommend that WSDM manageable resource information, especially the ResourceId element, be exposed for WSDM manageable participants, as illustrated in the above example XML. On the other hand, if a participant in a MUWS relationship is not a WSDM manageable resource, then a wsa:EndPointReference or a URL referencing the resource, should be provided within the Participant element. The Participant element facilitates the use of open content by means of an xs:any element within its schema. For further information about the use of the xs:any element in MUWS, see section Error: Reference source not found., "Error: Reference source not found".

A manageability provider or WS-resource reporting MUWS relationship information must include the Role each participant plays in the MUWS relationship. A role is described by a URI. A manageability consumer uses of the value of a Role element to determine how each participant behaves in the MUWS relationship.

A MUWS relationship contains a muws-p2-xs:Participant child element for each participant in a relationship. In the example above, there are two participants.

3.2.2 Querying Relationships by Type: WSDL ModificationsThe MUWS Relationship capability also defines the QueryRelationshipsByType message exchange. This operation is not necessary when a manageability consumer wants to obtain all MUWS relationships for a resource. However, the QueryRelationshipsByType operation is more efficient when a manageability consumer wants to obtain all the relationships of a particular MUWS relationship type and interacts with a resource participating in many relationships of differing types. In fact, MUWS recommends a manageability consumer use the QueryRelationshipsByType operation instead of the GetResourceProperty operation for this



261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640

264126422643

2644264526462647264826492650265126522653265426552656

2657265826592660

26612662

26632664266526662667266826692670

109

110

reason. The ability for a manageability consumer to request only relationships of a given type facilitates a more efficient processing of the relationships by a manageability consumer and saves the network bandwidth and processor burden incurred when transmitting unwanted relationship information for a resource.

When we add this new operation to the WSDL description of our manageability endpoint we need to use the prefix of an XML namespace in the MUWS part 2 WSDL. Thus, we add the appropriate prefix and import statements. See section 2.2.2, "The WSDL Document" for further detail within this step.

Since the MUWS WSDL already includes a WSDL message element for our operation, we just refer to the existing message from our portType. So, in the next step we add the new operation to our portType as follows:

<w:operation name="QueryRelationshipsByType"> <w:input name="QueryRelationshipsByTypeRequest" message="muws-p2-w:QueryRelationshipsByTypeRequest" wsa:Action="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.wsdl/Relationships/QueryRelationshipsByTypeRequest"/> <w:output name="QueryRelationshipsByTypeResponse" message="muws-p2-w:QueryRelationshipsByTypeResponse" wsa:Action="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.wsdl/Relationships/QueryRelationshipsByTypeResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> </w:operation>

Finally, we add our new operation to the binding as follows:.

<w:operation name="QueryRelationshipsByType"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> </w:operation>

3.2.2.1 An Example using QueryingRelationshipsByTypeA manageability consumer constructs a QueryRelationshipsByType request message containing the MUWS relationship type of interest. In our example, we want to obtain all of the relationships in which a resource participates that have a relationship type of "Gateway", as defined in section 3.1.1 above. Our request is as follows:

<muws-p2-xs:QueryRelationshipsByType> <muws-p2-xs:RequestedType>exh:Gateway</muws-p2-xs:RequestedType> </muws-p2-xs:QueryRelationshipsByType>

The response message contains a list of relationships of the specified type. If a resource does not have any relationships of the specified type, then the QueryRelationshipsByTypeResponse element contains no child element. If a resource has many relationships of the specified type, then the QueryRelationshipsByTypeResponse element contains many instances of the Relationship element. For our example, we assume a resource has only a single relationship of the specified type. Our response is as follows:

<muws-p2-xs:QueryRelationshipsByTypeResponse>



2671267226732674

2675267626772678

267926802681

26822683268426852686268726882689269026912692269326942695

2696

2697269826992700270127022703270427052706270727082709

27102711271227132714

271527162717

271827192720272127222723

2724

111

112

<muws-p2-xs:Relationship> <muws-p2-xs:Name>MyPdaDevice to MyPdaDeviceServer</muws-p2-xs:Name> <muws-p2-xs:Type> <exh:Gateway> <exh:ConnectionTypes/> </exh:Gateway> </muws-p2-xs:Type> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> wsa:MyPdaDeviceManageabilityEndpointAddress </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>  urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 </muws-p1-xs:ResourceId> <muws-p2-xs:Role> http://example.org/services/MyPdaDevice.xsd/role/device </muws-p2-xs:Role> </muws-p2-xs:Participant> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> wsa:MyPdaDeviceServerManageabilityEndpointAddress </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>  urn:uuid:adf9926c-19df-440a-528e-f4813b3b715f </muws-p1-xs:ResourceId> <muws-p2-xs:Role> http://example.org/services/MyPdaDevice.xsd/role/server </muws-p2-xs:Role> </muws-p2-xs:Participant> </muws-p2-xs:Relationship> </muws-p2-xs:QueryRelationshipsByTypeResponse>

Notice the content of the response message is familiar and simply exposes the relevant Relationship property of the requested relationship type.

3.2.3 Relationship EventsA MUWS relationship can only be created or destroyed. A MUWS relationship can not be changed or modified. For example, if MyPdaDevice enters into a Gateway relationship with a new server, then our resource destroys the old Gateway relationship and creates a new one. A manageability consumer may subscribe to receive a notification on either the create event or destroy event for a MUWS relationship. For more information on Subscriptions and Notifications, see section 2.10 of this primer.

A manageability consumer subscribes to receive a notification in the event a MUWS relationship is created or deleted by using the TopicExpression/Concrete dialect as described in section 7.2, "ConcreteTopicPath Expressions", in the Web Services Topics [WS-Topics] specification. This dialect is required as these WS-Topics are subtopics of the RelationshipsCapability topic. For example, our subscription message to receive notification of a RelationshipCreated event is as follows:

<wsnt:Subscribe . . .> <wsnt:ConsumerReference> ... </wsnt:ConsumerReference> <wsnt:TopicExpression Dialect="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd/TopicExpression/Concrete"> muws-ev:RelationshipsCapability/RelationshipCreated </wsnt:TopicExpression> </wsnt:Subscribe>



272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757

27582759

2760276127622763276427652766

276727682769277027712772

2773277427752776277727782779278027812782

113

114

When a resource issues a notification of a MUWS relationship event, the MUWS ManagementEvent structure is a required part of the Notification message. In addition, a notification of a MUWS relationship event must include the definition of the relationship instance. We simply define a MUWS relationship using the <Relationship> element present in our resource properties document as described by section 3.2.1, "Error: Reference source not found".

As an example, we consider a scenario in which a PDA device is assigned to a new server. Let us assume a manageability consumer has a subscription with a PDA manageability endpoint to receive notifications related to any new relationships in which the PDA participates. A notification message can appear as the child of the soap:Body element. Alternatively, a notification message can appear as a child of the wsn:Notify/wsn:NotificationMessage/wsn:Message element. The form and appearance of the notification message depends upon how a manageability consumer subscribed to receive the notification. Our example notification message is as follows:

<ManagementEvent xmlns="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd" ReportTime="2005-06-16T12:05:30.6589722-04:00"> <EventId>eid:27e18b35-aeb7-45a8-9685-e5e4d8af9c6f</EventId>



<Situation xmlns="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"> <SituationCategory> <ReportSituation/> <SituationCategory> <SituationTime>2005-06-16T12:05:30.6589722-04:00</SituationTime> <Severity>1</Severity> <Message> <muws-pp2-xs:RelationshipCreatedNotification> <muws-pp2-xs:Relationship> <muws-pp2-xs:Type> <exh:Gateway> <exh:ConnectionTypes/> </exh:Gateway> </muws-pp2-xs:Type> <muws-pp2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> wsa:MyPdaDeviceManageabilityEndpointAddress </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>  urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 </muws-p1-xs:ResourceId> <muws-pp2-xs:Role> http://example.org/services/MyPdaDevice.xsd/role/device </muws-pp2-xs:Role> </muws-pp2-xs:Participant> <muws-pp2-xs:Participant>  <muws-p1-xs:ManageabilityEndpointReference> wsa:MyPdaDeviceServerManageabilityEndpointAddress </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>  urn:uuid:adf9926c-19df-440a-528e-f4813b3b715f </muws-p1-xs:ResourceId> <muws-pp2-xs:Role> http://example.org/services/MyPdaDevice.xsd/role/server </muws-pp2-xs:Role> </muws-pp2-xs:Participant> </Relationship> </muws-pp2-xs:RelationshipCreatedNotification> </Message> </Situation></ManagementEvent>



27832784278527862787

27882789279027912792279327942795

2796279727982799

28002801

2802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847

115

116

3.2.4 Relationship MetadataThe metadata for MUWS relationships should appear in the metadata document of any manageability endpoint supporting the MUWS Relationships capability and the MUWS QueryRelationshipByType message. This metadata is as follows:

<rmd:Definitons . . .>. . . <rmd:Property path="muws-p2-xs:Relationships" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Relationships </muws-p2-xs:Capability> </rmd:Property>

<rmd:Operation path="muws-p2-xs:QueryRelationshipByType" idempotent="true"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Relationship </muws-p2-xs:Capability> </rmd:Operation>. . .</rmd:Definitions>

See Appendix A for the complete metadata document for our example PDA manageability endpoint.

3.2.5 Guidelines for Supporting the Relationships CapabilityThis section of the MUWS primer offers some guidelines for supporting the MUWS Relationship Capability as discussed above. The MUWS Relationship capability is a powerful manageability tool for resource discovery, for root cause analysis and for determining the set of resources orchestrating a higher level service. The guidelines offered in this section facilitate greater manageability of resources participating in a MUWS relationship.

There is no required ordering of Participant elements contained in a MUWS relationship. A manageability consumer must not assume the first Participant element identifies the resource providing the information. Consider that a resource may report information about a MUWS relationship in which it is not a participant. For example, a distributed processing environment implements a relationship service exposing all of the MUWS relationships within the distributed processing environment. In this case, the resource providing information about MUWS relationship in the extended environment likely is not a participant in the reported relationship. Another reason is that

Some systems implement relationships such that any or all participants return the same relationship information. Also, the order of Participant elements may be identical no matter which participant provided the information on the relationship. The manageability consumer needs to examine the Role element associated with a participant, and possibly needs to examine the ResourceId element or ManageabilityEndpointReference element in determining how a resource behaves in a relationship.

The MUWS specification recommends support for the QueryResourceProperties message exchange by a manageability endpoint supporting the MUWS Relationship capability. Support for the QueryResourceProperties message is not necessary if a resource is a participant in, or knows of only a small number of relationships. However, as a distributed processing environment scales the number of relationships in which a resource participates is likely to increase. The QueryResourceProperties request allows a manageability consumer a fine-grained selection for the relationship information of interest.



2848284928502851

285228532854285528562857285828592860

286128622863286428652866286728682869

28702871

287228732874287528762877

28782879288028812882288328842885

288628872888288928902891

2892289328942895289628972898

117

118

Finally, a good idea for a resource participating in a MUWS relationship is to expose its ManageabilityEndpoint and ResourceId information. This helps a manageability consumer determine which participant is the resource providing information on a relationship.

3.3 Accessing Relationships as WS-ResourcesAs we model resources and relationships, it is often helpful to think of an association as a classifier with its own properties and operations. For example, a marriage of two persons has properties, such as the date and place of the marriage. It is awkward to consider these properties as part of either person. To address this type of situation, the UML provides an association class that represents an association as a classifier. An association class has a special connection to the line representing an association between classes as follows:

Now, the properties and operations pertaining to the UML association between Class1 and Class2 are modeled as part of the AnAssocation classifier.

Recall that a MUWS relationship is comparable to a link, an instance of a UML association, or relationship type. MUWS supports the modeling of a MUWS relationship as a WS-Resource. In other words, a WS-Resource may represent a MUWS relationship exposing the properties of a relationship type. For example, a WS-Resource representing the marriage relationship type may expose instance information on the date and place of a marriage ceremony and the two participants, and support operations and events relevant to this MUWS relationship type.

3.3.1 Accessing a MUWS Relationships as a WS-ResourceA manageability consumer must be able to discover the wsa:EndPointReference (EPR) for a WS-Resource representing a MUWS relationship. A manageability consumer may discover the EPR of a MUWS relationship by asking a WS-Resource participating in the MUWS relationship or by asking another resource, such as a registry providing information about MUWS relationships. If a relationship is accessible, then the WS-Resource providing information about the relationship should include an EPR for the relationship itself within the Relationship property. The schema of the MUWS Relationship property includes the <AccessEndpointReference> element for this purpose as follows:

<muws-p2-xs:Relationship> ...  ... <muws-p2-xs:AccessEndpointReference> wsa:EndpointReferenceType </muws-p2-xs:AccessEndpointReference> </muws-p2-xs:Relationship>



289929002901

2902290329042905290629072908

290929102911

291229132914291529162917

291829192920292129222923292429252926

29272928292929302931293229332934

119

120

Recall, the WS-Resource representing the relationship is not required to be a WSDM manageable resource. For more information on relationship as WS-Resource, see section 3.3.2, "Error: Reference source not found".

3.3.2 Treating Relationships as Standalone ResourcesIf a relationship is exposed as a WS-Resource, then the resource is normatively required to support the MUWS RelationshipResource capability. In most cases, this is the only capability exposed by such a resource. The MUWS RelationshipResource capability requires support for three properties in its resource properties document. These properties are Name, Type, and Participants. These properties are the same as the corresponding properties exposed by the Relationship property in the resource properties document of each participant. We see a difference in the relationship as resource since these three properties are not contained within a Relationship element as the resource knows only about the relationship it represents. Likewise, the Participants property is not contained within a Relationship element.

Suppose a management model wants the UML association between PdaDevice and PdaServer represented by an association class. Then, we would represent a MUWS relationship between MyPdaDevice and MyPdaDeviceServer as a WS-Resource. Notice we want to include the AccessEndpointReference element in the Relationship property in the resource properties document of MyPdaDevice and MyPdaDeviceServer in order to reference this MUWS relationship as a WS-Resource.

If a relationship exposed as a resource has only the standard MUWS-defined relationship properties, then the resource does not need to define a schema document since the MUWS part 2 schema contains everything necessary. So, we just define a WSDL document with the appropriate attribute on the portType as follows:

<w:portType name="MyRelationshipResourcePortType" wsrf-rp:ResourceProperties="muws-p2-xs:RelationshipResourceProperties">

We add the operations we want to use for accessing properties of our relationship resource. At a minimum we want to use the GetResourceProperty operation.

If there are additional properties we want to expose for our relationship resource, then we must construct a resource properties document schema as well as a WSDL document. We define a WS-Resource for our GatewayRelationship example by first creating a resource properties document schema as follows:

<xs:schema targetNamespace="http://example.org/services/GatewayRelationship.xsd" . . .>


<xs:element name="Date" type="xs:dateTime"/> <xs:element name="Location" type="xs:string"/>

<xs:element name="GatewayRelationshipProperties"> <xs:complexType> <xs:sequence> <xs:element ref="muws-p2-xs:Name" minOccurs="0"/> <xs:element ref="muws-p2-xs:Type"/> <xs:element ref="muws-p2-xs:Participant" minOccurs="2" maxOccurs="unbounded"/> <xs:element ref="relext:Date" minOccurs="0"/> <xs:element ref="relext:Location" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element>



293529362937

2938293929402941294229432944294529462947

294829492950295129522953

2954295529562957

29582959

29602961

2962296329642965

296629672968

29692970297129722973

297429752976

2977297829792980298129822983298429852986298729882989

121

122

</xs:schema>

Notice we also added two additional optional properties to our relationship resource.

The WSDL for our relationship resource follows the pattern as presented in section 2.2.2, "The WSDL Document", and should expose the GetResourceProperty operation as specified by WS-ResourceProperties. Now, a manageability consumer can request the ‘Type’ property for our relationship resource as follows:

<wsrf-rp:GetResourceProperty> muws-p2-xs:Type </wsrf-rp:GetResourceProperty>

A response from our relationship resource appears as follows::

<wsrf-rp:GetResourcePropertyResponse> <muws-p2-xs:Type> <exh:Gateway> <exh:ConnectionTypes/> </exh:Gateway> </muws-p2-xs:Type> </wsrf-rp:GetResourcePropertyResponse>

Notice that all MUWS relationship properties are accessible via GetResourceProperty, including extra optional properties ‘Date’ and ‘Location’, as defined above. Recall that all standard access routines as defined by WS-ResourceProperties may be used by a manageability consumer to access the XML representation of a MUWS relationship as a WS-resource. If a relationship resource allows a manageability consumer to change some property, then the corresponding set operation may also be exposed. If set operations are allowed, then the corresponding relationship properties of the respective participants must be kept in synch with any changes made to the WS-Resource.



2990

2991

2992299329942995

299629972998

2999

3000300130023003300430053006

30073008300930103011301230133014

123

124

4 Managing MUWS ResourcesWe have now built a manageable resource. In this chapter of the MUWS primer we explore how our manageable resource interacts with a manageability consumer. In particular, we will discuss how a manageability consumer:

Discovers an EndpointReference (EPR) for a manageable resource

Discovers and uses the capabilities of the resource

4.1 Discovering ResourcesMUWS does not specify any specific mechanism for the discovery of a resource. However, we can offer some useful hints for a manageability consumer interested in discovering a resource.

One of the more critical and complex aspects of resource management is the discovery of resources to manage. Discovery of a resource is complex because different resources may be discovered in different ways and different management domains may use different methods of discovery. As a result, if a manageability consumer needs to support many different types of resources then it may need to support a broad variety of discovery mechanisms.

Discovery capabilities are briefly described in MUWS part 2, chapter 5, "Discovery". In this section of the MUWS primer we expand on the MUWS description and explore three general methods for the discovery of a resource as follow:

Using explicit resource EPRs in the configuration of a manageability consumer

Using a registry to expose the existence of a resource

Using the MUWS Relationship capability

Notice that other discovery mechanisms may be used in some management domains. However, other discovery mechanisms are not discussed in the MUWS primer.

4.1.1 Explicit ConfigurationAs mentioned above, one method a manageability consumer can find a resource is through configuration of the manageability consumer. This can be accomplished by providing the discovery information for a resource as an argument at application startup, through a user interface, or through a configuration file or database read at application startup. Using explicit configuration as a method of resource discovery is most useful when a small number of resources and other key components are involved. An example of another key component is a registry of resources or a root resource in a resource hierarchy, from which additional resources are discovered by a manageability consumer. However, a database of current discovery information could easily be maintained for resources with which a manageability consumer interacts.

Using explicit configuration as a resource discovery method is best as an initial bootstrap towards further resource discovery, such as accessing the relationship property of a known resource as described Error: Reference source not found in section Error: Reference source not found, "Error:Reference source not found".

4.1.2 Resource Advertisement and RegistriesAdvertisement is discussed above in section 2.13, "Advertising a Resource". A manageability consumer may subscribe to the creation messages of a resource factory. If the Advertising capability is supported in a Web services environment that also supports a registry of resources,



3015301630173018

3019

3020

302130223023

30243025302630273028

302930303031

3032

3033

3034

30353036

30373038303930403041304230433044304530463047

3048304930503051

3052305330543055

125

126

then the registry can subscribe on ManagebleResourceCreation/Deletion topics to keep itself up to date. Alternatively, a registry could propagate notifications of observed events on these topics to keep other entities up to date.

A registry provides an excellent central location from which other resources may be discovered. As such, the location of a registry as a “known entity” within a system is a good initial bootstrap towards resource discovery. Registries come in many varieties. Often, a registry is designed for a specific environment or a particular management domain. While the MUWS specification does not define a registry structure, MUWS does recommend using a ServiceGroup as defined by WS-ServiceGroup to act as a registry of manageable resources within a Web services environment. The following sections discuss several forms of registry.

4.1.2.1 UDDIA UDDI compliant registry contains information as usually exposed by a provider to a partner or a client about services offered and how to contact the provider. Information is available from a UDDI registry in a data structure called a tModel. While the tModel exposes the WSDL document and endpoint for a service, it can not expose an Endpoint Reference (EPR) for a resource. Developers using UDDI can use the existing tModel structure to identify top-level services useful towards further resource discovery. Alternatively, developers using UDDI can extend the tModel structure to contain an EPR and identity for a resource.

UDDI can be particularly useful as an initial bootstrap towards resource discovery. A UDDI registry can serve as the one configured resource for a manageability consumer. A UDDI registry can serve as a place where additional discovery mechanisms and manageable resources are exposed. However, in certain use cases a UDDI registry may be an inappropriate discovery mechanism, especially in any use case where resources are created and deleted rapidly or in any use case involving a large number of resources.

4.1.2.2 ServiceGroupAs described in MUWS part 2, section 5.2, "Discovery Using Registries", a ServiceGroup implements a Web service registry. A ServiceGroup is a resource supporting the usual WS-ResourceProperties message exchange patterns. Also, the resource properties document of a member resource may be contained within the ServiceGroup. As a result, a QueryResourceProperties message exchange may be used to find a subset of member resources in a ServiceGroup. Once a subset of members is known, it is possible for a manageability consumer to interact directly with a member as the EPR for each member resource is contained within the ServiceGroup.

4.1.2.3 Relationship RegistriesA resource can be discovered by a manageability consumer inspecting the relationship property of a known resource. For more information on resource discovery using MUWS relationships, see the next section of this primer. We can create a simple registry by using a resource that supports the MUWS Relationship capability. See chapter Error: Reference source not found, "Error: Reference source not found", for more information about the MUWS Relationship capability. A resource acting as a registry using the MUWS Relationship capability would expose exactly one relationship for each known resource within a distributed processing environment or system. When a resource acts as a registry in this way it should also support the QueryResourceProperties operation.

4.1.3 Using The MUWS Relationship CapabilityThe MUWS Relationship capability was designed to expose the associations between the various resources in a distributed processing environment or system. Analyzing the information about the resources participating in a MUWS relationship is an excellent way for a manageability consumer



305630573058

3059306030613062306330643065

30663067306830693070307130723073307430753076307730783079

308030813082308330843085308630873088

3089309030913092309330943095309630973098

3099310031013102

127

128

to discover new resources. Notice that a manageability consumer using the MUWS Relationship capability in this way still needs a starting point, a first resource. Rather, this approach provides a basis for a recursive resource discovery mechanism and a means to reflect the state of resources and relationships. When using relationships as a discovery mechanism, a manageability consumer must already know an EPR for one or more initial bootstrap resources as discussed in section Error: Reference source not found, "Error: Reference source not found".

4.1.3.1 Discovering Resources from RelationshipsThere are several operations available to a manageability consumer interested in inspecting the MUWS relationships of a resource. These operations are as follow:

GetResourceProperty

GetMultipleResourceProperties

QueryResourceProperties

QueryRelationshipsByType

In order for a resource to provide the manageability consumer with a mechanism for discovering any resources with which it associates, a resource must support at least one of the above operations.

We can describe an algorithm a manageability consumer can use to discover all resources associated with all known resources with pseudo-code as follows:

For each known resource {

Request the relationship property

For each returned MUWS relationship {

Obtain an EPR of the other participant in the relationship

If the EPR references a resource not already in our list {

Add this resource to our list of known resources

Recursively invoke this algorithm for this resource

}

}

}

For more information and examples of Message Exchange Patterns useful for traversing relationships, see section 4.2.2.4, "Querying and Traversing Relationships".

MUWS defines the Participant element to allow for open content. In particular, we recommend exposing a ResourceId in the Participant element of a Relationship. We consider it much easier for a manageability consumer to compare ResourceIds than it is for a manageability consumer to send a message to an EPR and then determine whether the referenced resource is a newly discovered resource or the same as a resource previously encountered.

The above discovery algorithm may find large numbers of resources. In fact, this discovery algorithm may discover resources considered outside the management domain of an application. Thus, it may be necessary to add some heuristics to prune or otherwise limit our list of known resources. Some of these heuristics are of a general nature and may apply to any application. For example, a manageability consumer might examine the Participant information to make sure a resource is of interest. Other domain or application specific heuristics may also apply. For example, a manageability consumer might check if a relationship is a certain type or may check if a resource supports a certain property or has a particular value for a certain property.



310331043105310631073108

310931103111

3112

3113

3114

3115

311631173118

31193120

3121

3122

3123

3124

3125

3126

3127

3128

3129

3130

31313132

31333134313531363137

31383139314031413142314331443145

129

130

Since a MUWS relationship can reference a resource that does not implement the MUWS Identity capability, the above discovery algorithm may discover resources that are not MUWS manageable resources.

4.1.3.2 Monitoring RelationshipsA manageability consumer interested in the current list of all known resources in an environment may want to subscribe to the RelationshipCreated and RelationshipDeleted Topics for each manageable resource discovered. This subscription will cause a manageability consumer to receive notifications containing either a RelationshipCreatedNotification or a RelationshipDeletedNotification element, as defined in MUWS Part 2, section 4.1.5, "Events". By taking the associated relationship and checking whether the relationship is already known, a manageability consumer can dynamically keep current its list of known resources. A notification message can appear as the child of the soap:Body element or as a child of the wsn:Notify/wsn:NotificationMessage/wsn:Message element, depending upon how a manageability consumer subscribed to receive notifications on an event topic. An example follows:

<muws-p1-xs:ManagementEvent ReportTime="..."> <muws-p1-xs:EventId>...</muws-p1-xs:EventId> <muws-p1-xs:SourceComponent> <muws-p1-xs:ResourceId>...</muws-p1-xs:ResourceId> <muws-p1-xs:ComponentAddress>...</muws-p1-xs:ComponentAddress> </muws-p1-xs:SourceComponent <muws-p2-xs:RelationshipCreatedNotification> <muws-p2-xs:Type>...</muws-p2-xs:Type> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> ... </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>...</muws-p1-xs:ResourceId> <muws-p2-xs:Role>...</muws-p2-xs:Role> </muws-p2-xs:Participant> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> ... </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>...</muws-p1-xs:ResourceId> <muws-p2-xs:Role>...</muws-p2-xs:Role> </muws-p2-xs:Participant> ... </muws-p2-xs:RelationshipCreatedNotification></muws-p1-xs:ManagementEvent>

4.1.4 SummaryA manageability consumer in a scoped or constrained environment may be able to use a single approach towards resource discovery. However, most manageability consumers likely interact with different types of manageable resources within heterogeneous environments and likely use several approaches towards resource discovery.

Typically, an initial bootstrap mechanism configures a manageability consumer to know about one or more top-level resources. Next, by interacting with a top-level resource, the manageability consumer can use the relationship property as a resource discovery mechanism and locate other resources in the environment.

A more sophisticated resource discovery mechanism, like a registry based upon ServiceGroups [WS-ServiceGroup], can be implemented as the need arises.



314631473148

314931503151315231533154315531563157315831593160

3161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185

31863187318831893190

3191319231933194

31953196

131

132

4.2 Managing and MonitoringThis section of the MUWS primer discusses how a manageability consumer discovers the manageability capabilities of a resource. Also, this section illustrates how a manageability consumer uses manageability capabilities when interacting with a resource.

4.2.1 Discovering Manageability CapabilitiesOnce a resource is known to a manageability consumer, the next step is determining which manageability capabilities are supported by the resource. MUWS part 1 recommends each supported manageability capability be included as the value of an instance of the ManageabilityCapability property. A manageability consumer obtains these values by sending a GetResourceProperty message to the resource and requesting the values of the ManageabilityCapability property. An example of a SOAP request to retrieve the manageability capabilities of a resource follows:

<wsrf-rp:GetResourceProperty> muws-p1-xs:ManageabilityCapability </wsrf-rp:GetResourceProperty>

The response to above request shows the resource supports five manageability capabilities: Identity, ManageabilityCharacteristics, CorrelatableProperties, Description, and Operational Status. Our example response follows:

<wsrf-rp:GetResourcPropertyResponse> <muw1:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity </muws-p1-xs:ManageabilityCapability> <muw1:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics </muw1:ManageabilityCapability> <muw1:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/CorrelatableProperties </muws-p1-xs:ManageabilityCapability> <muw1:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p1-xs:ManageabilityCapability> </muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus </muws-p1-xs:ManageabilityCapability> </wsrf-rp:GetResourcePropertyResponse> </s:Body></s:Envelope>

If a manageability consumer knows the manageability capabilities supported by a resource, then the manageability consumer knows the features available to manage the resource. The capabilities as described in the MUWS, MOWS, and dependent specifications indicate a minimum set of properties, message exchanges, and notifications exposed by a compliant manageable resource.

4.2.2 Using Manageability CapabilitiesThis section discusses the possible roles played by manageability capabilities in management tasks.



3197319831993200

32013202320332043205320632073208

320932103211

321232133214

32153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237

32383239324032413242

324332443245

133

134

4.2.2.1 Determining Resource IdentityBecause manageability capabilities for a resource may be provided in part by different manageability endpoints or discovered through various and overlapping means, it is often necessary for a manageability consumer to determine if different references refer to the same resource or to different resources. In a case where the manageability for a resource is provided by multiple endpoints, simply comparing EPRs to determine if a resource is already discovered can yield an incorrect result.

The simplest approach towards determining the identity of a resource is by comparing the ResourceId of each referenced resource. The ResourceId is specified by MUWS part 1 as a mandatory property. When determining if two values of the MUWS ResourceId property are equal, a manageability consumer compares the URIs on a character by character basis. Equal values of the MUWS ResourceId property indicate the same resource. However, it is not guaranteed that two different manageability endpoints for the same managed resource will return the same ResourceId. This situation may occur if a manageability endpoint is unaware of others and does not obtain a ResourceId from the resource itself.

In a use case where different values of the MUWS ResourceId property may refer to the same resource, each manageability endpoint should also support the MUWS CorrelatableProperties capability. If the MUWS CorrelatableProperties capability is supported, then a manageability consumer should use this capability when determining the identity of a resource if the values of the ResourceId property are not equal. The MUWS CorrelatableProperties capability exposes access to a set of values for a resource that a manageability consumer can use in determining the identity of a resource. If the same resource is referenced, then the values of the correlatable properties should be equal even if the ResourceId properties are not equal. If the CorrelateableProperties capability is not supported, then a manageability consumer should treat different values of the ResourceID property as different resources.

For our example, we assume a manageability consumer determines that the values of the ResourceId property are not equal, and we assume our manageability endpoints support the MUWS CorrelatableProperties capability. Now, a manageability consumer decides to use this capability and determine if the different resource references actually reference the same resource. Next, a manageability consumer obtains the correlatable properties of a resource by sending a message to a manageability endpoint as follows:

<wsrf-rp:GetResourceProperty> muws-p1-xs:CorrelatableProperties </wsrf-rp:GetResourceProperty>

In our example, we assume the target resource exposes two correlatable properties, MyID and MyUnitNumber. Further, we assume that the values of both MyID and MyUnityNumber are required to be equal in order to establish the identity of a resource. Also, we assume their conjunction is both necessary and sufficient to guarantee the identity of a resource. The response to our GetResourceProperty request might use the “foo” namespace prefix as defined in the resource properties document of the target resource as follows:

<wsrf-rp:GetResourcePropertyResponse> <muws-p1-xs:CorrelatableProperties Dialect="http://docs.oasis-open.org/wsdm/2004/12/pbm" NegativeAssertionPossible="true"> <pbm:MatchAll> <pbm:Match>foo:MyKey</pbm:Match> <pbm:Match>foo:MyUnitNumber</pbm:Match> </pbm:MatchAll> </muws-p1-xs:CorrelatableProperties> </wsrf-rp:GetResourcePropertyResponse>

A manageability consumer parses this response to obtain an understanding of how to test the identity of a resource. Notice the Dialect attribute specifies how content in the <muws-p1-xs:CorrelatableProperties> element is formulated. In our case, the Property Boolean Match (pbm)



3246324732483249325032513252

32533254325532563257325832593260

3261326232633264326532663267326832693270

327132723273327432753276

327732783279

328032813282328332843285

3286328732883289329032913292329332943295

329632973298

135

136

dialect is sufficient, allowing a manageability consumer to perform an equality match on the values of the provided properties. Notice the <MatchAll> element tells a manageability consumer that the value from each resource for both <Match> elements foo:MyKey and foo:MyUnitNumber must compare as equal in order for a successful identity test on a resource. Notice the NegativeAssertionPossible attribute indicates that if a comparison provides a false result, then a manageability consumer is guaranteed that the tested resources are not identical.

Now that a manageability consumer knows how to proceed with a test on the identity of a resource, the next step is to send request messages to the target resources and retrieve the values for the MyKey and MyUnitNumber properties for each resource. Once responses are received, a manageability consumer tests the identity of the target resources by performing the comparison as specified above by the CorrelatableProperties property.

4.2.2.2 Obtaining Description and State InformationUpon discovering a resource, a manageability consumer may wish to obtain a description of the resource and maintain it in a log for future reference. Or, a manageability consumer may wish to display parts of a description of the discovered resource on an application console. Perhaps the application console displays a list of resources comprising a system or produces a topological display of a system and displays the caption property of a resource on its corresponding icon. The description of a resource consists of three elements: a caption, perhaps multiple descriptive statements about the resource, and a version. In our example, we assume that a manageability consumer wants to display the caption and version number on a topological display of a managed system. So, we send a message to the manageability endpoint of the target resource as follows:

<wsrf-rp:GetMultipleResourceProperties> <wsrf-rp:ResourceProperty>muws-p2-xs:Caption</wsrf-rp:ResourceProperty> <wsrf-rp:ResourceProperty>muws-p2-xs:Version</wsrf-rp:ResourceProperty> </wsrf-rp:GetMultipleResourceProperties>

We receive a response from the target resource as follows:

<wsrf-rp:GetMultipleResourcePropertiesResponse> <muws-p2-xs:Caption xml:lang="en-US"> Application ABC </muws-p2-xs:Caption> <muws-p2-xs:Version> Version 1.2 </muws-p2-xs:Version> </wsrf-rp:GetMultipleResourcePropertiesResponse>

Now, a manageability consumer can use the value of the muws-p2-xs:Caption property, adding "Application ABC Version 1.2" with the discovered resource icon to its console display.

Once a resource is discovered, a manageability consumer may wish to obtain additional information about the resource. For on-going, real-time information, a manageability consumer can subscribe to receive notification of events on topics of interest. A manageability consumer can use subscriptions as a basis for a logging or an alerting mechanism. In any case, a manageability consumer may wish to poll for information from a resource. For example, a manageability consumer might poll resources every fifteen minutes with an explicit request for status and current state to update the moment-in-time display of the system.

If the manageability endpoint of a resource supports the MUWS OperationalStatus capability, then a manageability consumer can retrieve the current operational status of a resource. In our example, the status of each resource, its availability in particular, is maintained on a topological display of a system. This way, a console user can quickly see the current availability of a system and which of its resources are currently up or down. We retrieve the MUWS Operational status property via a GetResourceProperty message as follows:

<wsrf-rp:GetResourceProperty> muws-p2-xs:OperationalStatus



329933003301330233033304

33053306330733083309

3310331133123313331433153316331733183319

3320332133223323

3324

33253326332733283329333033313332

333333343335333633373338333933403341

334233433344334533463347

33483349

137

138

</wsrf-rp:GetResourceProperty>

We receive a response showing the target resource is currently Available as follows:

<wsrf-rp:GetResourcePropertyResponse> <muws-p2-xs:OperationStatus> Available </muws-p2-xs:OperationStatus> </wsrf-rp:GetResourcePropertyResponse>

A manageability consumer requests the current state of a resource in a similar way. MUWS part 2 does not predefine a state model for a resource. The definition of a state model for a resource is located in the XML schema of the resource properties document for a resource. In our example, a manageability consumer sends a request for the state of the target resource, one of our PDA devices, as follows:

<wsrf-rp:GetResourceProperty> pda:DeviceState </wsrf-rp:GetResourceProperty>

We receive a response showing the target resource is currently in the ServerConnected state, a sub-state of the Connected state as follows:

<wsrf-rp:GetResourcePropertyResponse> <pda:DeviceState> <pda:ServerConnected> <pda:Connected/> </pda:ServerConnected> </pda:DeviceState> </wsrf-rp:GetResourcePropertyResponse>

4.2.2.3 Configuring the Manageable ResourceA principal concern of a manageability consumer is configuring the resources it manages. MUWS part 2 defines a Configuration capability yet allows a manageable resource to specify which properties are configurable by a manageability consumer. The configurable properties of a resource are specified as modifiable in the schema of its resource properties document.

A mutable configuration property may be set by a manageability consumer via the SetResourceProperties message. In our example, we assume the target resource exposes a configurable property, TriesBeforeFailure. We set this property by sending a request as follows:

<s:Body> <wsrf-rp:SetResourceProperties> <wsrf-rp:Update> <foo:TriesBeforeFailure> 100 </foo:TriesBeforeFailure> </wsrf-rp:Update> </wsrf-rp:SetResourceProperties></s:Body>

4.2.2.4 Querying and Traversing RelationshipsAn important aspect of managing a resource is querying and traversing the relationships in which it participates. We have already seen one example of traversing relationships for discovering new resources, see section 3.1.3.1. In this section we use as an example a manageability consumer wishing to determine the free space available on the hard-drive of a laptop. If the available space on hard-drive fails below a specified threshold then the laptop user is warned that the hard-drive is dangerously close to running out of free space.



3350

3351

33523353335433553356

33573358335933603361

336233633364

33653366

3367336833693370337133723373

33743375337633773378

337933803381

338233833384338533863387338833893390

3391339233933394339533963397

139

140

In our example, a relationship between a laptop and its hard-drive is described by the LaptopHardDrive relationship type, a subcategory of the EquipmentConnectedService relationship type. Notice that the EquipmentConnectedService relationship type is a subcategory of the ConnectedTo relationship type.

<foo:LapTopHardDrive> <foo:EquipmentConnectedService> <foo:ConnectedTo/> </foo:EquipmentConnectedService></foo:LapTopHardDrive>

We request the LaptopHardDrive relationship type from a laptop resource as follows:

<muws-p2-xs:QueryRelationshipsByType> <muws-p2-xs:RequestedType>foo:LapTopHardDrive</muws-p2-xs:RequestedType> </muws-p2-xs:QueryRelationshipsByType>

The resource properties document for a laptop resource contains the hierarchical structure of the relationship type within the MUWS relationship <Type> child element. We receive a response to the query as follows:

<muws-p2-xs:QueryRelationshipsByTypeResponse> <muws-p2-xs:Relationship> <muws-p2-xs:Name>Harddrive connected to laptop</muws-p2-xs:Name> <muws-p2-xs:Type> <foo:LapTopHardDrive> <foo:EquipmentConnectedService> <foo:ConnectedTo/> </foo:EquipmentConnectedService> </foo:LapTopHardDrive> </muws-p2-xs:Type> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> ...EPR1 </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceID>urn:uuid:123</muws-p1-xs:ResourceID> <muws-p2-xs:Role>urn:role:connectedTO:equipment</muws-p2-xs:Role> <foo:HostName>myhost.myorg.org</foo:NostName> </muws-p2-xs:Participant> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> ...EPR2 </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceID>urn:uuid:456</muws-p1-xs:ResourceID> <muws-p2-xs:Role>urn:role:connectedTo:service</muws-p2-xs:Role> </muws-p2-xs:Participant> </muws-p2-xs:Relationship> </muws-p2-xs:QueryRelationshipsByTypeResponse>

Notice a manageability consumer parses the above response and finds the EndPointReference (EPR) of the resource participating in the connectedTo:service role. A manageability consumer uses this EPR and requests the Capacity and UsedSpace properties from the target resource and then determines if the hard-drive is running out of free-space. If the manageability consumer determines the free-space on the hard-drive has fallen below a threshold then a notification is issued to subscribers.



3398339934003401

34023403340434053406

3407

340834093410

341134123413

341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440

344134423443344434453446

141

142

5 Further Considerations5.1 Defining a Taxonomy in WSDM

A taxonomy is frequently required for the manageability of a resource. The structure of a taxonomy is defined in the schema of a resource properties document, though parts of a taxonomy may be defined in some other document and imported into the schema.

Section 2.6, "Representation of Categorization Taxonomies in XML", in MUWS Part 2 defines the MUWS schema complex type CategoryType. MUWS extends the CategoryType to derive three general types of taxonomy as follow:

SituationCategoryType

StateType

RelationshipTypeType

Within the schema of MUWS Part 2, each general type of taxonomy extends from of CategoryType using a pattern as follows:

<xs:complexType name=”XXXXXXType”> <xs:complexContent> <xs:extension base=”muws-p2-xs:CategoryType”/> </xs:complexContent> </xs:complexType>

Notice CategoryType is itself a complexType and specifies a sequence of any XML element and "lax" processing. For example, the definition of StateType is as follows:

<xs:complexType name="StateType"> <xs:complexContent> <xs:extension base="muws-p2-xs:CategoryType"/> </xs:complexContent></xs:complexType>

We can use a predefined category type or we can define our own taxonomy category either as an extension of the MUWS CategoryType or as an extension of a type derived from CategoryType. Our schema may define a further subtype of StateType, for example, a particular State hierarchy such as PrinterStateType, by using this same pattern as follows:

<xs:complexType name="PrinterStateType"> <xs:complexContent> <xs:extension base="muws-p2-xs:StateType"/> </xs:complexContent></xs:complexType>

We also need to define an element of the type for taxonomy as follows:

<xs:element name="PrinterState" type="tns:PrinterStateType">

Notice the PrinterState element carries the semantics of the PrinterStateType taxonomy. Also notice, this element may be defined as a Global Element Declaration (GED). If the element is defined as a GED, then an instance of our taxonomy can be retrieved through the GetResourceProperty operation as a query for the QName of this element. In some cases, it is desirable to define an element taking on the semantics of a taxonomy as part of a larger context. For example, the SituationCategoryType taxonomy, with a corresponding element, SituationCategory, may be defined as part of the larger context of SituationType.



3447

3448344934503451

345234533454

3455

3456

3457

34583459

34603461346234633464

34653466

34673468346934703471

3472347334743475

34763477347834793480

3481

3482

3483348434853486348734883489

143

144

When defining elements in a taxonomy we first consider how we want the taxonomy expressed in an instance of a resource properties document. Thus, we want an element defined with the semantics of our taxonomy for the parent element of our taxonomy, exposed as follows:

<PrinterState> <PrinterStateLevel3> <PrinterStateLevel2> <PrinterStateLevel1/> </PrinterStateLevel2> </PrinterStateLevel3></PrinterState>

Notice the highest and most general element of the PrinterState hierarchy appears as the inner most element. In other words, when a manageability consumer parses the PrinterState hierarchy, the most specialized elements are seen first. This structure and organization allows a manageability consumer to stop processing a taxonomy as soon as it sees an element having known semantics.

How do we represent this hierarchy in the XML schema of our resource properties document? Notice that a taxonomy consists of a series of elements. We define each element separately and then connect the elements using the XML restriction of a taxonomy type. So, we begin with the highest level element and its restriction of taxonomy type. Recall, a taxonomy type may either be a MUWS predefined taxonomy type or be our defined taxonomy type. PrinterStateLevel1 is the inner most element of our taxonomy and appears as follows:

<xs:element name="PrinterStateLevel1"> <xs:complexType> <xs:complexContent> <xs:restriction base="tns:PrinterStateType" /> </xs:complexContent> </xs:complexType> </xs:element>

Since PrinterStateLevel1 is the most general element of our taxonomy, it has no children. PrinterStateLevel2 is a more specific level and has one child, the PrinterStateLevel1 element. The PrinterStateLevel2 element appears as follows:

<xs:element name="PrinterStateLevel2"> <xs:complexType> <xs:complexContent> <xs:restriction base="tns:PrinterStateType"> <xs:sequence> <xs:element ref="tns:PrinterStateLevel1" /> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType> </xs:element>

A lower level of our taxonomy is defined with an element referencing the next higher level. In our example, the PrinterStateLevel3 element is the most specific and appears as follows:

<xs:element name="PrinterStateLevel3"> <xs:complexType> <xs:complexContent> <xs:restriction base="tns:PrinterStateType"> <xs:sequence> <xs:element ref="tns:PrinterStateLevel2 " /> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType> </xs:element>



349034913492

3493349434953496349734983499

35003501350235033504

350535063507350835093510

3511351235133514351535163517

351835193520

35213522352335243525352635273528352935303531

35323533

35343535353635373538353935403541354235433544

145

146

Given an understanding of this simple pattern we can define a taxonomy of any complexity in our resource properties document.

5.1.1 Steps for Constructing a TaxonomyA taxonomy is a category for information and we declare a taxonomy as follows:

Step 1: Declare an XML element with a QName identifying the semantics for our category:

<xs:element name="PrinterState" type="tns:PrinterStateType">

Step 2: Declare an XML element with an XML Schema type restriction based upon the MUWS CategoryType:

<xs:element name="PrinterStateLevel1"> <xs:complexType> <xs:complexContent> <xs:restriction base="tns:PrinterStateType" /> </xs:complexContent> </xs:complexType> </xs:element>

Step 3: Declare the contents of the XML element. This content is either the one child element corresponding to the most general element of the category or an empty sequence, as in step 2 above. An example of an element declared with one child element appears as follows:

<xs:element name="PrinterStateLevel2"> <xs:complexType> <xs:complexContent> <xs:restriction base="tns:PrinterStateType"> <xs:sequence> <xs:element ref="tns:PrinterStateLevel1" /> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType> </xs:element>

Notice a declared element with an empty sequence is the most general element and is the top level of a taxonomy.

5.2 Alternate Means of Accessing ManageabilityThe MUWS architecture provides mechanisms for accessing resource properties by exchanging messages with the manageability endpoint of a directly-addressable resource. However, a manageability endpoint may provide access to the properties of more than one resource. Thus, a manageability consumer is able to interact with one manageability endpoint and access the resource properties for a system composed of manageable resources using MUWS defined mechanisms.

One example of this approach is found in the WS-ServiceGroup specification. WS-ServiceGroup describes how to create a collection of resources. If some of the resources in a service group are manageable resources, then the manageability endpoint for the service group can also be used to access the properties of a system composed of several resources. A composed system exposes the properties of its resources, like MUWS identity, and supports the mechanisms defined by the MUWS specification. The exposed properties of a manageable resource that is part of a system may be accessed by directly addressing the resource. However, in some cases properties of a resource can also be accessed via the manageability endpoint of the service group as well.

Similarly, a manageability consumer can subscribe for notifications on a management topic supported by a service group. Subscribing on a topic supported by a service group is equivalent



35453546

35473548

3549

3550

35513552

3553355435553556355735583559

356035613562

35633564356535663567356835693570357135723573

35743575

3576357735783579358035813582

358335843585358635873588358935903591

35923593

147

148

to subscribing on the same topic for each resource of the system as represented by the service group. Thus, MUWS facilitates the management of an individual resource or service as well as an entire system of resources.

A service group is just one of several ways to represent a system composed of individual resources. A system can expose more than the state of its resources and can provide additional metadata and information about the relationships among its resources. A resource information model such as the DMTF Common Information Model (CIM) can be used to define the representation of a system and render it as an XML document, thus making the information model of a system available through mechanisms as defined in the WS-ResourceProperties specification. The W3C Resource Description Framework (RDF) is another example of a mechanism for representing a system.

In a sense, we can think of a manageability endpoint providing access to one manageable resource as a special case of a manageability endpoint providing access to a system of resources. The special case would occur when a system is composed of only one resource.

5.3 FCAPS DiscussionFCAPS is an acronym for Faults, Configuration, Accounting, Performance, Security and is the ISO model for network management. These five categories organize a management model by various management tasks. Wihtin the context of this primer, FCAPS can be used to identify and categorize various aspects of distributed management. Fault management tasks recognize, isolate, correct and log faults occuring within a management domain. Often, a fault will cause a notification to be sent to a manageability consumer. Configuration management tasks include gathering and storing the configuration of resources and services, tracking changes made to a configuration and the configuration or provisioning of circuits. Accounting tasks gather usage statistics on users for the accounting and billing of resource usage and for resource quota enforcement. Performance management tasks collect and analyze performance data used in monitoring the health of management domain and for deriving any trends in resource usage indicating the potential for a capacity or reliability issue before it affects the performance of availability of a service or resource. Security management tasks identify and secure risks associated with the important issues of identification, authentication, authorization, message Integrity, data integrity, data confidentiality and trust.

These categories are easily mapped onto the WSDM Manageability Capabilities used to achieve the same purpose. The MUWS Metrics Manageability Capabilities can be used to support the five FCAPS management categories. Likewise, the MUWS Relationship capability is essential for gaining an understanding of the relationships among resources. The MUWS Relationship capability ensures that configuration, fault, and performance tasks can be accomplished for resources within the context of a distributed processing environment. The WSDM Event Format (WEF) provides the key mechanism supporting the correlation of events with resources for the purposes of performance, fault, and accounting management. The MUWS Configuration Manageability capability supports configuration management tasks and also supports fault and performance management for the automated correction of faults.

5.4 The Web Services PlatformThis section briefly describes the features of the Web services platform required for managing resources using Web services. This section also provides some recommendations on how to support each required feature. Recommendations in this section either reference another specification used to provide the feature, identify the feature as provided by the industry in the future, or identify the feature as defined by an interim specification produced by the WSDM Technical Committee (TC) for use until such feature is available within the Web services platform. Simply, this section provides some insight on the architectural choices and rationale behind the requirements placed onto the Web services platform by the WSDM TC.



359435953596

35973598359936003601360236033604

360536063607

3608360936103611361236133614361536163617361836193620362136223623

3624362536263627362836293630363136323633

363436353636363736383639364036413642

149

150

http://en.wikipedia.org/wiki/Security_management

http://en.wikipedia.org/wiki/Performance_management

http://en.wikipedia.org/wiki/Configuration_management

http://en.wikipedia.org/wiki/Fault_management

http://en.wikipedia.org/wiki/Network_management

http://en.wikipedia.org/wiki/International_Organization_for_Standardization

5.4.1 Initial Focus The features discussed in the following subsections must be supported by the Web services platform to support the initial version of the MUWS specification.

5.4.1.1 PropertiesA property is information we can describe and retrieve. Sometimes we can set the value of a property. A property may be exposed through a Web services interface. A schema is used to define a property and the message exchanges for retreiving and setting a value for the property.. A property declaration and its description should be introspectable at design time and at runtime. For our purpose of manageability, a property is part of an advertised manageability endpoint for a resource. A property can represent any aspect of a resource, like the configuration values of a resource, or its performance metrics.

Motivation: Many of the manageability capabilities supported by a manageable resource expose information about a resource a manageability consumer is able to retrieve and set. Such information about a resource should be modeled as a set of properties and the associated access methods allow access to its properties in ways that meet the scalability requirements of the management domain.

Recommendation: We recommend using the WS-Resource Properties specification [WS-ResouceProperties] to describe the properties of a manageable resource.

5.4.1.2 Meta Data Meta-data is generally defined as data about data. In our context of management, meta-data is additional descriptive information about the components comprising a manageability endpoint, including its properties, operations, events, and capabilities. Meta-data can also provide descriptive information about the context, quality and condition, or other characteristics of management data. Meta-data can be introspected at design time and runtime.

Motivation: In IT management, meta-data is important for describing data in greater detail in support of the purpose of a resource providing management data. For example, meta-data may describe the limitations, purpose, context, quality, or characteristics of management data as an associated piece of that data and helps describe how the management data is related to the objectives of an IT environment. Additionally, meta-data facilitates the interoperability of manageability capabilities as provided across different manageability providers.

Recommendation: For WSDM 1.0, we recommend expressing the descriptive information about a manageability endpoint as XML elements bound to a PortType in a resource properties document. This approach satisfies the requirements of runtime and design time introspection but does not form a basis for a well understood and interoperable meta-data format.

Beyond WSDM 1.0, the desired solution involves supporting a standard metadata document format for runtime and design time introspection. We recommend the use of Qualifiers, as defined by the DMTF Common Information Model (CIM), to expose meta-data concerning a class, a property, a method, a notification or a method parameter. Then, a manageability consumer can inspect a qualifier for useful manageability meta-data in a well understood and interoperable format.

5.4.1.3 Addressing An address or reference is a data structure used as a reference to a unique instance of a resource or service. An address is used to refer to a service acting as a manageability provider or acting as a manageable resource. The data structure for an address must contain sufficient information for a manageability consumer to locate the referenced service and to send messages to the referenced service. If a service acts as a manageability provider for several resources, then there is also a need for an address to uniquely identify a target resource as an endpoint reference



364336443645

36463647364836493650365136523653

36543655365636573658

36593660

366136623663366436653666

366736683669367036713672

3673367436753676

367736783679368036813682

3683368436853686368736883689

151

152

(EPR) within its data structure. The data structure of an address must include a means to locate the description of a service. This allows a manageability consumer to identify messages understood by a service. Notice in this context, the terms address and reference as used have synonymous meaning.

Motivation: The management of different types of resources can be simplified by using interoperable addresses for referencing common manageability services and manageable resources in relationships, in notifications and in message exchanges.

Recommendation: We recommend using the WS-Addressing specification [WS-Addressing] as produced by the Web Services Addressing group of the W3C.

5.4.1.4 Notification A notification provides a means to convey information from a resource to a recipient on a topic of expressed interest. In terms of Web services a notification delivers an XML message from a source to an addressable recipient. An interest in receiving notification messages on a topic must be established by the recipient, or by a third party on behalf of the recipient. When registering an interest on a topic, the address(es) of a recipient must be provided as discussed in section Error: Reference source not found, "Error: Reference source not found".

Motivation: A manageable resource needs to convey its management data to a manageability consumer. In certain cases, it is unreasonable for a manageability consumer to explicitly poll by periodic request for the management data of interest. In such a case, the manageability provider for a resource can convey the management data of interest to a manageability consumer as a notification of an event on a topic of interest A manageability provider needs to know which manageability consumer wants to receive notification of events for a topic and needs to know the deliverable address(es) of a manageability consumer in order to send a notification message as events occur.

Recommendation: We recommend the use of the WS-Notifications specification [WS-Notification].

5.4.1.5 Versioning A version attribute identifies a set of supported capabilities and exposes a sequence of modifications on a component. There are two kinds of versioning, a resource version and a Web services version. The format of the former is outside the scope of this primer. Version information is useful in determining if a Web Service interface has changed since a manageability consumer last cached meta-data and schema describing the interface.

Motivation: A manageability consumer must be able to retrieve and inspect the versions available for an endpoint and the corresponding change description for each version. In this way a manageability consumer can determine which interface as offered by a manageability provider is best suited for a particular management application.

Recommendation: WSDM addresses the issue of versioning as part of the Management of Web Services (MOWS) specification. MOWS complies with W3C recommendations on the issue of versioning and supports W3C TAG finding on Versioning. Management Using Web Services (MUWS) provides access to version information as part of the Description Capability.

5.4.1.6 SecurityThere are many ways to categorize information security. However, the categories in common use today are confidentiality, integrity and authentication. Additional concepts could arguably be categorized as access control, non-repudiation, availability and privacy. The security requirements placed on management data are similar to security requirements placed on any sensitive data. All manageability endpoints and many business endpoints have the same security



3690369136923693

369436953696

36973698

3699370037013702370337043705

37063707370837093710371137123713

37143715

371637173718371937203721

3722372337243725

3726372737283729

373037313732373337343735

153

154

requirements for confidentiality, integrity, and authentication, as well as access control, availability, and privacy.

Motivation: A resource must be manageable in a secure manner. The mechanisms comprising a security infrastructure should be composed and layered on top of manageability as exposed via Web services. This approach is similar to securing any other capability of a resource as exposed via Web services. For example, access to a manageability operation can be granted only to a manageability consumer presenting suitable credentials in a request message.

Recommendation: We recommend complying with the recommendations made by the OASIS WS-Security TC [WSS]. WSDM 1.0 provides a risk analysis ensuring that WS-Security composes with MUWS and identifies security risks of concern to implementers and deployers.

5.4.1.7 Registration, Discovery and LocationRegistration is a method of advertising the existence of an resource. Discovery is a method of finding an existing resource. Discovery can be based on selection criteria or can be based on a name or identity of a resource. Location is a method of obtaining an address of a resource. In the Web services sense, registration, discovery and location can be represented by a set of operations and schema and implemented as a registry.

Motivation: Manageable resources must be discoverable by a manageability consumer. A manageable resource exposed via Web services can be registered, discovered and located via a Registry.

Recommendation:. We recommend using the existing Web services discovery practices as sufficient. This includes use of WS-ResourceFramework ServiceGroups along with the use of the UDDI specification for location of service groups, resource registries, and critical resources.

5.4.2 Future FocusThe section of the MUWS primer discusses what support from the Web services platform may be required in future versions of WSDM.

5.4.2.1 Policy A Policy is a course of action, guiding principle, or procedure considered expedient, prudent, or advantageous for a given condition or event. It describes a broad range of service requirements, preferences, and capabilities. There are two kinds of policy that govern management of a manageable resource. A policy set can describe how a manageability consumer and a manageable resource interact using the functional interfaces of a resource, for example a policy describing the privacy of functional data. Alternatively, a policy set can describe how a manageability consumer places operational requirements on a manageable resource, for example a service level agreement.

Motivation: There are various policies that can be placed on a manageable resource including authentication, access control, privacy, non-repudiation, service level agreement, quality of service, routing, content inspection, and auditing. MUWS must leverage existing Web services specifications and technologies when applying policies to a manageable resource. MUWS should endorse a list of applicable specifications and technologies, and should specify compatibility and interoperability requirements.

Recommendation: None at this time.

5.4.2.2 Name ResolutionFor the purposes of manageability, a name resolution service is required that accepts a name identifier (URI) of a resource and returns an address or reference for a manageability endpoint of the resource. A name resolution service should provide sufficient information for a manageability



37363737

37383739374037413742

374337443745

374637473748374937503751

375237533754

375537563757

375837593760

376137623763376437653766376737683769

377037713772377337743775

3776

3777377837793780

155

156

consumer to interact with a manageability endpoint. Notice that a name resolution service may be used to resolve a name to an endpoint reference in application domains unrelated to management as well, for example in support of Web services discovery.

Motivation: A name resolution service is necessary for management using web services because resources and manageability providers have identifiers as defined with existing instrumentation and technologies. Thus, it is necessary to derive an endpoint reference from a resource identifier so that a manageability consumer can interact with a resource through its manageability interface(s).


5.4.2.3 Transaction A transaction is a “unit of work”, a serailizable set of actions invoked against a resource. The same unit of work can be applied to multiple resources. As a transaction, a unit of work must be executed once and only once, even if network transmission failures occur and a request is received multiple times. One of three outcomes will result from the execution of a transaction as follow:

All actions against all resources succeed

One or more actions fail. All actions against all resources are rolled back. If roll back is not possible or not supported, then affected resources should be reconfigured to a known operational, compensatory state

One or more actions may fail and the resources are left as affected by the actions.

Motivation: The grouping of actions as a transaction having a consistent behavior when executed against resources is highly valuable for the management of distributed processing environments. A transaction allows a manageability consumer to execute a series of actions or operations as a single “unit of work”, while preserving the integrity of resource(s) affected.


5.4.2.4 Flow Flow, more often called workflow or workflow management, is a term used to describe the management of business processes with information technology. By defining, analyzing, and categorizing the resources and operations or an organization, workflow management systems ensure the right information reaches the right person or computer application at the right time. Business process management (BPM) workflow or execution languages support the composition of services into more complex systems that may in turn be exposed as a Web service. Description of workflow coordination includes constructs for identify business partners, for message correlation, for fault detection and compensating activities, and for parallel and serial execution of services.

Motivation: Web services orchestration languages may be useful tools allowing a manageability consumer to take more complex and meaningful action as a result of observations. A manageability endpoint may need to be defined for a business process engine to monitor and control flows and composite Web services that might expose certain information including the sessions and state of a process and subordinate resources,.




378137823783

37843785378637873788

3789

379037913792379337943795

3796

379737983799

38003801

3802380338043805

3806

3807380838093810381138123813381438153816

38173818381938203821

3822

157

158

5.4.2.5 NegotiationNegotiation is the process by which two services dynamically negotiate the terms of a contract. A contract is a document that represents a set of objectives and resources initiating or participating in the contract.

Motivation: Resources in a distributed processing environment interact with each other and interact with management services and manageability consumers. It is important for a resource to understand what it can expect from other resources in such interactions and to understand the various interactions enabling a resource to better describe its own level of performance, as well as how information is exchanged between the components of a distributed service in a federated deployment.




3823382438253826

382738283829383038313832

3833

159

160

6 References[MUWS Part 1] William Vambenepe, Web Services Distributed

Management:Management using Web Services (MUWS 1.0) Part 1, OASIS Committee Draft, December 2004, http://docs.oasis-open.org/wsdm/2004/12/wsdm-muws-part1-1.0.pdf

[MUWS Part 2] William Vambenepe, Web Services Distributed Management:Management using Web Services (MUWS 1.0) Part 2, OASIS Committee Draft, December 2004, http://docs.oasis-open.org/wsdm/2004/12/wsdm-muws-part2-1.0.pdf

[SOAP] Don Box, et al., Simple Object Access Protocol (SOAP) 1.1, W3C Note, May 2000, http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

[UML] http://www.omg.org/technology/documents/formal/uml.htm

[WS-Addressing] Don Box, et al., Web services Addressing (WS-Addressing), W3CMember Submission, August 2004, http://www.w3.org/Submission/2004/SUBM-ws-addressing-20040810/

[WS-BaseFaults] Steve Tuecke, et. al., Web Services Base Faults 1.2 (WS-BaseFaults), Oasis Working Draft, November, 2004, http://docs.oasis-open.org/wsrf/2004/11/wsrf-WS-BaseFaults-1.2-draft-03.pdf

[WS-BaseNotification] Steve Graham, et al., Web Services Base Notification 1.2 (WS-BaseNotification), OASIS Working Draft, June

2004, http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-03.pdf

[WS-BrokeredNotification]Dave Chappell, et al., Web Services Brokered Notification 1.2 (WS-BrokeredNotification). OASIS Working Draft, July 2004l http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BrokeredNotification-1.2-draft-01.pdf

[WS-Notification] Steve Graham, et al., Web Services Base Notification 1.2 (WS-BaseNotification), OASIS Working Draft, June

2004, http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-03.pdfDave Chappell, et al., Web Services Brokered Notification 1.2 (WS-BrokeredNotification). OASIS Working Draft, July 2004l http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BrokeredNotification-1.2-draft-01.pdf



383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881

161

162

[WS-ResourceProperties] Steve Graham, et al., Web Services Resource Properties 1.2 (WS-ResourceProperties), OASIS Working Draft, June 2004, http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-04.pdf

[WS-RMD] Steve Graham, et al., Web Services Resource Metadata 1.0 (WS-ResourceMetadataDescriptor), OASIS Working Draft, October 2004, http://www.oasis-open.org/committees/download.php/9758/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.PDF

[WS-ServiceGroup] Tom Maguire, et al., Web Services Service Group 1.2 (WS-ServiceGroup), OASIS Working Draft, June 2004, http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ServiceGroup-1.2-draft-02.pdf

[WS-Topics] William Vambenepe, Web Services Topics 1.2 (WS-Topics), OASIS Working Draft, Jully 2004, http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.pdf

[WSDL] Erik Christensen, et al., Web services Description Language (WSDL) 1.1, W3C Note, March 2001, http://www.w3.org/TR/wsdl

[WSS] Anthony Nadalin, et al., Web Services Security: SOAP Message Security 1.0 (WS-Security 2004), March 2004, OASIS Standard, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

[XML] Tim Bray, et al., Extensible Markup Language (XML) 1.0 (Third Edition), W3C Recommendation, February 2004, http://www.w3.org/TR/REC-xml

[XML Schema] Henry S. Thompson, et al. XML Schema Part 1: Structures, W3C Recommendation, May 2001, http://www.w3.org/TR/xmlschema-1/Paul V. Biron, et al. XML Schema Part 2: Datatypes, W3C Recommendation, May 2001, http://www.w3.org/TR/xmlschema-2/

[XPath] James Clark, et al., XML Path Language (XPath) Version 1.0, W3C Recommendation, November 1999, http://www.w3.org/TR/1999/REC-xpath-19991116



38823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925

163

164

Appendix A. Complete XML DocumentsXML schema for the MyPdaDevice manageability endpoint exposing all MUWS capabilities.

<?xml version="1.0" encoding="utf-8"?><xs:schema targetNamespace="http://example.org/services/MyPdaDevice.xsd" xmlns:pda="http://example.org/services/MyPdaDevice.xsd" xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd" xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd" xmlns:wsnt="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd" xmlns:exh=http://example.org/services/localDefinitions.xsd xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">



<xs:import namespace="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd" schemaLocation="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd"/>


<xs:element name="ResetServerConnectionMetric"> <xs:complexType/> </xs:element>

<xs:element name="ResetServerConnectionMetricResponse"> <xs:complexType/> </xs:element>

<xs:element name="FailedServerConnections" type="exh:NonNegativeMetric"/> <xs:element name="MessagesReceived" type="exh:NonNegativeMetric"/> <xs:element name="AverageResponseTime" type="exh:DurationMetric"/> <xs:element name="MemoryInUse" type="exh:PercentageMetric"/>

<xs:element name="Shutdown"> <xs:complexType/> </xs:element>

<xs:element name="ShutdownResponse"> <xs:complexType/> </xs:element>

<xs:complexType name="DeviceStateType"> <xs:complexContent> <xs:extension base="muws-p2-xs:CategoryType"/> </xs:complexContent></xs:complexType>

<xs:element name="DeviceState" type="pda:DeviceStateType"/>



3926

3927

3928392939303931393239333934393539363937393839393940

39413942394339443945

39463947394839493950

395139523953395439553956

3957395839593960

3961396239633964

3965396639673968

39693970397139723973

3974397539763977

3978397939803981

398239833984398539863987

39883989

165

166

http://example.org/services/localDefinitions.xsd

<xs:element name="LastStateTransition" type="muws-p2-xs:StateTransitionType"/>

<xs:element name="Off"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"/> </xs:complexContent>

</xs:complexType> </xs:element>

<xs:element name="Idle"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"/> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="Initializing"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"/> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="Synchronizing"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"/> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="Connected"> <xs:complexType> <xs:complexContent>

<xs:restriction base="pda:DeviceStateType"/> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="NetworkConnected"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"> <xs:sequence> <xs:element ref="pda:Connected"/> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="SystemConnected"> <xs:complexType> <xs:complexContent> <xs:restriction base="pda:DeviceStateType"> <xs:sequence> <xs:element ref="pda:Connected"/> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType></xs:element>

<xs:element name="MyPdaDeviceProperties"> <xs:complexType> <xs:sequence>



39903991

39923993399439953996399739983999

40004001400240034004400540064007

40084009401040114012401340144015

40164017401840194020402140224023

40244025402640274028402940304031

403240334034403540364037403840394040404140424043

404440454046404740484049405040514052405340544055

4056405740584059

167

168

<xs:element ref="muws-p1-xs:ResourceId"/> <xs:element ref="muws-p2-xs:Description" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="muws-p2-xs:Caption" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="muws-p2-xs:Version" minOccurs="0"/> <xs:element ref="muws-p1-xs:ManageabilityCapability" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="wsnt:Topic" minOccurs="0" maxOccurs="unbounded"/> <xs:element ref="wsnt:FixedTopicSet" minOccurs="1" maxOccurs="1"/> <xs:element ref="wsnt:TopicExpressionDialects" minOccurs="1" maxOccurs="unbounded"/> <xs:element ref="muws-p2-xs:CurrentTime"/> <xs:element ref="pda:FailedServerConnections"/> <xs:element ref="pda:MessagesReceived"/> <xs:element ref="pda:AverageResponseTime"/> <xs:element ref="pda:MemoryInUse"/> <xs:element ref="muws-p2-xs:OperationalStatus"/> <xs:element ref="pda:DeviceState"/> <xs:element ref="pda:LastStateTransition"/> <xs:element ref="muws-p2-xs:Relationship" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>

</xs:schema>

The special definitions required by the PDA example are defined in the following schema:.

<?xml version="1.0" encoding="utf-8"?><xs:schema targetNamespace="http://example.org/services/localDefinitions.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd" xmlns:exh="http://example.org/services/localDefinitions.xsd" elementFormDefault="qualified" attributeFormDefault="unqualified">


<xs:element name="ResourceDisambiguator" type="xs:anyURI"/>

 <xs:complexType name="NonNegativeMetric"> <xs:simpleContent> <xs:extension base="xs:nonNegativeInteger"> <xs:attributeGroup ref="muws-p2-xs:MetricAttributes"/> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:extension> </xs:simpleContent></xs:complexType>

<xs:complexType name="DurationMetric"> <xs:simpleContent> <xs:extension base="xs:duration"> <xs:attributeGroup ref="muws-p2-xs:MetricAttributes"/> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:extension> </xs:simpleContent> </xs:complexType>



4060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087

40884089

4090

40914092409340944095409640974098

40994100410141024103

41044105

41064107410841094110411141124113411441154116

411741184119412041214122412341244125

4126

169

170

http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd

<xs:complexType name="PercentageMetric"> <xs:simpleContent> <xs:restriction base="exh:NonNegativeMetric"> <xs:minInclusive value="0"/> <xs:maxInclusive value="100"/> <xs:attributeGroup ref="muws-p2-xs:MetricAttributes"/> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:restriction> </xs:simpleContent> </xs:complexType>

 <xs:element name="ConnectionType"> <xs:annotation> <xs:documentation> The ConnectionType association is intended to be used as a relationship Type between things that can be connected by some means. Subtypes of this association can be defined by the types of things that are connected. This type has 2 associated roles, which should be defined specifically in the subtype. Each role must appear in exactly one Participant element in the relationship. The roles are specified using the following URIs: http://example.org/services/MyPdaDevice.xsd/role/thing http://example.org/services/MyPdaDevice.xsd/role/connectedthing </xs:documentation> </xs:annotation> <xs:complexType> <xs:complexContent> <xs:restriction base="muws-p2-xs:RelationshipTypeType"/> </xs:complexContent> </xs:complexType> </xs:element>

<xs:element name="Gateway"> <xs:annotation> <xs:documentation> The Gateway association is intended to be used as a relationship type between devices such as PDAs and servers. This type has 2 associated roles, one for the device, the other for the Server. Each role must appear in exactly one Participant element in the relationship. The roles are specified using the following URIs: http://example.org/services/MyPdaDevice.xsd/role/device http://example.org/services/MyPdaDevice.xsd/role/server </xs:documentation> </xs:annotation> <xs:complexType> <xs:complexContent> <xs:extension base="exh:ConnectionType"/> </xs:complexContent> </xs:complexType> </xs:element>

</xs:schema>

An example of a PDA resource properties document, as developed in this primer, is:

<?xml version="1.0" encoding="utf-8"?><pda:MyPdaDeviceProperties xmlns:pda="http://example.org/services/MyPdaDevice.xsd" xmlns:exh="http://example.org/services/localDefinitions.xsd" xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd" xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd" xmlns:muws-ev="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2-events.xml" xmlns:pdae="http://example.org/MyPdaTopics.xml"



4127412841294130413141324133413441354136

41374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159

4160416141624163416441654166416741684169417041714172417341744175417641774178

41794180

4181

41824183418441854186418741884189419041914192

171

172

xmlns:wsnt="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.xsd">

<muws-p1-xs:ResourceId> urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 </muws-p1-xs:ResourceId> <muws-p2-xs:Description xml:lang="en-US"> PDA device for Inventory/Ordering. </muws-p2-xs:Description> <muws-p2-xs:Description xml:lang="fr"> Ordinateur de poche pour inventaire et prise de commande. </muws-p2-xs:Description> <muws-p2-xs:Version> Version 1.4.2, January 2005 </muws-p2-xs:Version>

<muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://example.org/capabilities/PDAMetrics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-openorg/wsdm/2004/12/muws/capabilities/State </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://example.com/capabilities/DeviceState </muws-p1-xs:ManageabilityCapability>

<wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> muws-ev:OperationalStateCapability </wsnt:Topic> <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> muws-p2-xs:OperationalState </wsnt:Topic> <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> muws-ev:MetricsCapability </wsnt:Topic> <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> pdae:PDAMetricsCapability </wsnt:Topic> <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> pdae:ServerConnectionFailure </wsnt:Topic> <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple"> pdae:StateCapability </wsnt:Topic> <wsnt:FixedTopicSet>true</wsnt:FixedTopicSet> <wsnt:TopicExpressionDialects> http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Simple



41934194

4195419641974198419942004201420242034204420542064207

420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234

4235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262

173

174

</wsnt:TopicExpressionDialects> <wsnt:TopicExpressionDialects> http://docs.oasis-open.org/wsn/2004/06/TopicExpression/Concrete </wsnt:TopicExpressionDialects>

<muws-p2-xs:CurrentTime>2005-08-11T12:30:56Z</muws-p2-xs:CurrentTime> <pda:FailedServerConnections LastUpdated="2005-08-11T12:25:53Z" ResetAt="2005-08-11T12:01:16Z">5</pda:FailedServerConnections> <pda:FailedReplications LastUpdated="2005-08-11T12:26:43Z" ResetAt="2005-08-11T12:01:16Z">1</pda:FailedReplications> <muws-p2-xs:OperationalStatus>Available</muws-p2-xs:OperationalStatus>

<pda:DeviceState > <pda:Initializing/> </pda:DeviceState> <muws-p2-xs:LastStateTransition Time="2004-03-11T11:30:56Z" TransitionIdentifier="http://example.com/transitions/Inializing/On"> <muws-p2-xs:EnteredState><pda:On/></muws-p2-xs:EnteredState> <muws-p2-xs:PreviousState><pda:Initializing/></muws-p2-xs:PreviousState> </muws-p2-xs:LastStateTransition>

<muws-p2-xs:Relationship> <muws-p2-xs:Name>MyPdaDevice to MyPdaDeviceServer</muws-p2-xs:Name> <muws-p2-xs:Type> <exh:Gateway> <exh:ConnectionTypes/> </exh:Gateway> </muws-p2-xs:Type> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> wsa:MyPdaDeviceManageabilityEndpointAddress </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>  urn:uuid:923abb9c-a0f1-32a9-dd1b-ae33fa7c31a5 </muws-p1-xs:ResourceId> <muws-p2-xs:Role> http://example.org/services/MyPdaDevice.xsd/role/device </muws-p2-xs:Role> </muws-p2-xs:Participant> <muws-p2-xs:Participant> <muws-p1-xs:ManageabilityEndpointReference> wsa:MyPdaDeviceServerManageabilityEndpointAddress </muws-p1-xs:ManageabilityEndpointReference> <muws-p1-xs:ResourceId>  urn:uuid:adf9926c-19df-440a-528e-f4813b3b715f </muws-p1-xs:ResourceId> <muws-p2-xs:Role> http://example.org/services/MyPdaDevice.xsd/role/server </muws-p2-xs:Role> </muws-p2-xs:Participant> <muws-p2-xs:AccessEndpointReference> <wsa:EndpointReference xmlns:wsa="http://www.w3.org/TR/ws-addr-core"> <wsa:Address> http://example.org/service/GatewayRelationshipEndpoint </wsa:Address> </wsa:EndpointReference> </muws-p2-xs:AccessEndpointReference> </muws-p2-xs:Relationship>


WSDL document for MyPdaDevice manageability endpoint.

<?xml version="1.0" encoding="utf-8"?>



4263426442654266

426742684269427042714272427342744275

427642774278427942804281428242834284

42854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325

43264327

4328

4329

175

176

http://example.org/service/GatewayRelationshipEndpoint

<w:definitions targetNamespace="http://example.org/services/MyPdaDevice.wsdl" xmlns:pdaw="http://example.org/services/MyPdaDevice.wsdl" xmlns:pda="http://example.org/services/MyPdaDevice.xsd" xmlns:exh="http://example.org/services/localDefinitions.xsd" xmlns:muws-p2-w="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.wsdl" xmlns:rmd="http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd" xmlns:pda-md="http://example.com/services/MyPdaDevice.rmd" xmlns:wsrf-rp="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd" xmlns:wsrf-rpw="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl" xmlns:wsntw="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.wsdl" xmlns:wsa="http://schemas.xmlsoap.org/ws/2005/08/addressing" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soapw="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:w="http://schemas.xmlsoap.org/wsdl/">

<w:import namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.wsdl" location="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.wsdl"/>


<w:import namespace="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.wsdl" location="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-BaseNotification-1.2-draft-01.wsdl"/>

<w:import namespace="http://schemas.xmlsoap.org/ws/2005/08/addressing" location="http://schemas.xmlsoap.org/ws/2005/08/addressing/ws-addr.xsd"/>

<w:types> <xs:schema>

<xs:import namespace="http://example.org/services/MyPdaDevice.xsd" schemaLocation="http://example.org/services/MyPdaDevice.xsd"/>


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

<xs:import namespace="http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd" schemaLocation="http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd"/>

<xs:import namespace="http://example.com/services/MyPdaDevice.rmd" schemaLocation="http://example.com/services/MyPdaDevice.rmd"/>

</xs:schema> </w:types>


<w:message name="ResetServerConnectionMetricRequestMessage">



43304331433243334334433543364337433843394340434143424343434443454346434743484349

43504351435243534354

43554356435743584359

436043614362436343644365

436643674368

436943704371437243734374

437543764377

43784379438043814382

43834384438543864387

438843894390

439143924393

4394439543964397

43984399

177

178

<w:part name="document" element="pda:ResetServerConnectionMetric"/></w:message>

<w:message name="ResetServerConnectionMetricResponseMessage"> <w:part name="document" element="pda:ResetServerConnectionMetricResponse"/></w:message>


<w:message name="ShutdownRequest"> <w:part name="document" element="pda:Shutdown"/> </w:message>

<w:message name="ShutdownResponse"> <w:part name="document" element="pda:ShutdownResponse"/> </w:message>

<w:portType name="MyPdaDevicePortType" wsrf-rp:ResourceProperties="pda:MyPdaDeviceProperties" rmd:metadataDescriptor="pda-md:MyPdaDeviceMetadata"rmd:metadataDescriptorLocation="http://example.com/services/MyPdaDevice.rmd http://example.com/services/metadata/MyPdaDevice.rmd"> <w:operation name="GetResourceProperty"> <w:input name="GetResourcePropertyRequest" message="wsrf-rpw:GetResourcePropertyRequest" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyRequest"/> <w:output name="GetResourcePropertyResponse" message="wsrf-rpw:GetResourcePropertyResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/InvalidResourcePropertyQNameFault"/> </w:operation> <w:operation name="GetMultipleResourceProperties"> <w:input name="GetMultipleResourcePropertiesRequest" message="wsrf-rpw:GetMultipleResourcePropertiesRequest" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetMultipleResourceProperties/GetMultipleResourcePropertiesRequest"/> <w:output name="GetMultipleResourcePropertiesResponse" message="wsrf-rpw:GetMultipleResourcePropertiesResponse"



44004401

4402440344044405

440644074408440944104411441244134414441544164417441844194420442144224423

4424442544264427

4428442944304431

443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467

179

180

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetMultipleResourceProperties/GetMultipleResourcePropertiesResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetMultipleResourceProperties/ResourceUnknownFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetMultipleResourceProperties/InvalidResourcePropertyQNameFault"/> </w:operation> <w:operation name="SetResourceProperties"> <w:input name="SetResourcePropertiesRequest" message="wsrf-rpw:SetResourcePropertiesRequest" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/SetResourcePropertiesRequest"/> <w:output name="SetResourcePropertiesResponse" message="wsrf-rpw:SetResourcePropertiesResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/SetResourcePropertiesResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/ResourceUnknownFault"/> <w:fault name="InvalidSetResourcePropertiesRequestContentFault" message="wsrf-rpw:InvalidSetResourcePropertiesRequestContentFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/InvalidSetResourcePropertiesRequestContentFault"/> <w:fault name="UnableToModifyResourcePropertyFault" message="wsrf-rpw:UnableToModifyResourcePropertyFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/UnableToModifyResourcePropertyFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/InvalidResourcePropertyQNameFault"/> <w:fault name="SetResourcePropertyRequestFailedFault" message="wsrf-rpw:SetResourcePropertyRequestFailedFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/SetResourceProperties/SetResourcePropertyRequestFailedFault"/> </w:operation> <w:operation name="QueryResourceProperties"> <w:input name="QueryResourcePropertiesRequest" message="wsrf-rpw:QueryResourcePropertiesRequest" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/QueryResourcePropertiesRequest"/> <w:output name="QueryResourcePropertiesResponse" message="wsrf-rpw:QueryResourcePropertiesResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/QueryResourcePropertiesResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/ResourceUnknownFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault"



4468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537

181

182

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/InvalidResourcePropertyQNameFault"/> <w:fault name="UnknownQueryExpressionDialectFault" message="wsrf-rpw:UnknownQueryExpressionDialectFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/UnknownQueryExpressionDialectFault"/> <w:fault name="InvalidQueryExpressionFault" message="wsrf-rpw:InvalidQueryExpressionFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/InvalidQueryExpressionFault"/> <w:fault name="QueryEvaluationErrorFault" message="wsrf-rpw:QueryEvaluationErrorFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/QueryResourceProperties/QueryEvaluationErrorFault"/> </w:operation>


<w:operation name="QueryRelationshipsByType"> <w:input name="QueryRelationshipsByTypeRequest" message="muws-p2-w:QueryRelationshipsByTypeRequest" wsa:Action="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.wsdl/Relationships/QueryRelationshipsByTypeRequest"/> <w:output name="QueryRelationshipsByTypeResponse" message="muws-p2-w:QueryRelationshipsByTypeResponse" wsa:Action="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.wsdl/Relationships/QueryRelationshipsByTypeResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> </w:operation>

<w:operation name="Subscribe"> <w:input message="wsntw:SubscribeRequest" wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/SubscribeRequest"/> <w:output message="wsntw:SubscribeResponse" wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/SubscribeResponse"/> <w:fault name="ResourceUnknownFault" message="wsntw:ResourceUnknownFault" /> <w:fault name="SubscribeCreationFailedFault" message="wsntw:SubscribeCreationFailedFault"/> <w:fault name="TopicPathDialectUnknownFault" message="wsntw:TopicPathDialectUnknownFault"/> </w:operation>

<w:operation name="GetCurrentMessage"> <w:input message="wsntw:GetCurrentMessageRequest"



4538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574

457545764577457845794580458145824583458445854586458745884589

459045914592459345944595459645974598459946004601460246034604

460546064607

183

184





wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/GetCurrentMessageRequest"/> <w:output message="wsntw:GetCurrentMessageResponse" wsa:Action="http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/GetCurrentMessageResponse"/> <w:fault name="ResourceUnknownFault" message="wsntw:ResourceUnknownFault" /> <w:fault name="InvalidTopicExpressionFault" message="wsntw:InvalidTopicExpressionFault" /> <w:fault name="TopicNotSupportedFault" message="wsntw:TopicNotSupportedFault" /> <w:fault name="NoCurrentMessageOnTopicFault" message="wsntw:NoCurrentMessageOnTopicFault" /> </w:operation>

<w:operation name="Shutdown"> <w:input name="ShutdownRequest" message="pdaw:ShutdownRequest" wsa:Action= "http://example.org/services/MyPdaDevice.wsdl/DeviceState/ShutdownRequest"/> <w:output name="ShutdownResponse" message="pdaw:ShutdownResponse" wsa:Action= "http://example.org/services/MyPdaDevice.wsdl/DeviceState/ShutdownResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> <w:fault name="InvalidStatusFault" message="pda:InvalidStatusFault" wsa:Action="http://example.org/services/MyPdaDevice.wsdl/MyPdaDevicePortType/InvalidStatusFault"/> </w:operation>

</w:portType>


<w:operation name="GetResourceProperty"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> </w:operation> <w:operation name="GetMultipleResourceProperties"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/>



46084609461046114612461346144615461646174618461946204621

4622462346244625462646274628462946304631463246334634463546364637463846394640464146424643

464446454646464746484649

4650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677

185

186

http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/GetCurrentMessageResponse

http://docs.oasis-open.org/wsn/2004/06/WS-BaseNotification/GetCurrentMessageResponse



</w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> </w:operation> <w:operation name="SetResourceProperties"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidSetResourcePropertiesRequestContentFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="UnableToModifyResourcePropertyFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="SetResourcePropertyRequestFailedFault" use="literal"/> </w:fault> </w:operation> <w:operation name="QueryResourceProperties"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="UnknownQueryExpressionDialectFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidQueryExpressionFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="QueryEvaluationErrorFault" use="literal"/> </w:fault> </w:operation>

<w:operation name="ResetServerConnectionMetricOperation"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> </w:operation>



46784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733

47344735473647374738473947404741474247434744474547464747

187

188

<w:operation name="Subscribe"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidStatusFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="SubscribeCreationFailedFault"/> </w:fault> <w:fault> <soapw;fault name="TopicPathDialectUnknownFault"/> <w:fault> </w:operation>

<w:operation name="GetCurrentMessage"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <w:fault> <soapw:fault name="InvalidTopicExpressionFault"/> </w:fault> <w:fault> <soapw.fault name="TopicNotSupportedFault"/> </w:fault> <w:fault> <soapw:name="NoCurrentMessageOnTopicFault"/> </w:fault> </w:operation>

<w:operation name="Shutdown"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidStatusFault" use="literal"/> </w:fault> </w:operation>

<w:operation name="QueryRelationshipsByType"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/>



47484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770

477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794

47954796479747984799480048014802480348044805480648074808480948104811

481248134814481548164817

189

190

</w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> </w:operation>

</w:binding>

<w:service name="MyPdaDeviceService"> <w:port name="MyPdaDeviceSoapPort" binding="pdaw:MyPdaDeviceSoapOverHttpBinding"> <soapw:address location="http://example.org/services/MyPdaDeviceEndpoint"/> </w:port> </w:service>

</w:definitions>

The following TopicSpace document is defined:

<?xml version="1.0" encoding="UTF-8"?><wstop:TopicSpace name="MyPdaNotificationTopics" targetNamespace="http://example.org/MyPdaTopics.xml" xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws- part1.xsd" xmlns:wstop="http://docs.oasis-open.org/wsn/2004/06/wsn-WS-Topics-1.2-draft-01.xsd">

<wstop:Topic name="BatteryCondition" messageTypes="muws-p1-xs:ManagementEvent">

<wstop:Topic name="BatteryFullyCharged"messageTypes="muws-p1-xs:ManagementEvent"/>

<wstop:Topic name="BatteryHalfCharged"messageTypes="muws-p1-xs:ManagementEvent"/>

<wstop:Topic name="BatteryCriticalLevel"messageTypes="muws-p1-xs:ManagementEvent"/>

<wstop:Topic name="BatteryDischarged"messageTypes="muws-p1-xs:ManagementEvent"/>

<wstop:Topic name="BatteryRemoved"messageTypes="muws-p1-xs:ManagementEvent"/>

</wstop:Topic>

<wstop:Topic name="PDAMetricsCapability" messageTypes="muws-p1-xs:ManagementEvent"/> <wstop:Topic name="ServerConnectionFailure" messageTypes="muws-p1-xs:ManagementEvent"> <wstop:MessagePattern Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"> //muws-p1-xs:ManagementEvent[count(pda:ServerConnectionFailureNotification)=1] </wstop:MessagePattern> </wstop:Topic></wstop:TopicSpace>

The following metadata document describes the metadata for the properties and operations of the PDA device:

<?xml version="1.0" encoding="UTF-8"?><rmd:Definitions xmlns:rmd="http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd"



48184819482048214822482348244825

48264827

48284829483048314832483348344835

48364837

4838

4839484048414842484348444845

484648474848

484948504851

485248534854

485548564857

485848594860

4861486248634864

486548664867486848694870487148724873487448754876

48774878

4879488048814882

191

192

xmlns:muws-p1-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part1.xsd" xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd" xmlns:pda="http://example.com/services/MyPdaDevice.xsd" xmlns:pdaw="http://example.com/services/MyPdaDevice.wsdl" targetNamespace="http://example.com/services/MyPdaDevice.rmd">

<rmd:MetadataDescriptor name="PdaDeviceMetadataDescriptor" interface="pdaw:MyPdsDevicePortType" wsdlLocation="http://example.com/services/MyPdaDevice.wsdl http://example.com/wsdl/MyPdaDevice.wsdl">

<rmd:Property path="muws-p1-xs:ResourceId" mutability="constant" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity </muws-p2-xs:Capability> </rmd:Property>

<rmd:Property path="muws-p1-xs:Description" mutability="mutable" modifiability="read-write"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p2-xs:Capability> </rmd:Property>

<rmd:Property path="muws-p1-xs:Caption" mutability="mutable" modifiability="read-write"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p2-xs:Capability> </rmd:Property>

<rmd:Property path="muws-p1-xs:Version" mutability="mutable" modifiability="read-write"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p2-xs:Capability> <rmd:StaticValues> <muws-p1-xs:Version>Version 1.4.2, January 2005</muws-p1-xs:Version> </rmd:StaticValues> </rmd:Property>

<rmd:Property path="muws-p1-xs:ManageabilityCapability" mutability="constant" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics </muws-p2-xs:Capability> <rmd:StaticValues> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Identity </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Description </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/ManageabilityCharacteristics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability>



4883488448854886488748884889

489048914892489348944895

48964897489848994900490149024903

49044905490649074908490949104911

49124913491449154916491749184919

49204921492249234924492549264927492849294930

4931493249334934493549364937493849394940494149424943494449454946494749484949495049514952

193

194

http://example.org/capabilities/TranslateableDescription </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://example.org/capabilities/PDAMetrics </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://example.org/capabilities/DeviceState </muws-p1-xs:ManageabilityCapability> <muws-p1-xs:ManageabilityCapability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Relationships </muws-p1-xs:ManageabilityCapability> </rmd:StaticValues> </rmd:Property>

<rmd:Property path="muws-p2-xs:CurrentTime" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> </rmd:Property>

<rmd:Property path="pda:FailedServerConnections" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> <muws-p2-xs:ChangeType>Counter</muws-p2-xs:ChangeType> <muws-p2-xs:TimeScope>SinceReset</muws-p2-xs:TimeScope> <muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime> <muws-p2-xs:MetricGroup> http://example.org/services/RemoteMetrics </muws-p2-xs:MetricGroup> </rmd:Property> <rmd:Property path="pda:MessagesReceived" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> <muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType> <muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope> <muws-p2-xs:GatheringTime>OnChange</muws-p2-xs:GatheringTime> <muws-p2-xs:MetricGroup> http://example.org/services/RemoteMetrics </muws-p2-xs:MetricGroup> </rmd:Property> <rmd:Property path="pda:AverageResponseTime" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability>



49534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975

49764977497849794980498149824983

498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022

195

196

<muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> <muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType> <muws-p2-xs:TimeScope>Interval</muws-p2-xs:TimeScope> <muws-p2-xs:GatheringTime>Periodic</muws-p2-xs:GatheringTime> <muws-p2-xs:CalculationInterval>PT2M</muws-p2-xs:CalculationInterval> <muws-p2-xs:MetricGroup> http://example.org/services/RemoteMetrics </muws-p2-xs:MetricGroup> </rmd:Property> <rmd:Property path="pda:MemoryInUse" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> <muws-p2-xs:ChangeType>Gauge</muws-p2-xs:ChangeType> <muws-p2-xs:TimeScope>PointInTime</muws-p2-xs:TimeScope> <muws-p2-xs:GatheringTime>OnDemand</muws-p2-xs:GatheringTime> <muws-p2-xs:MetricGroup> http://example.org/services/RemoteMetrics </muws-p2-xs:MetricGroup> </rmd:Property>

<rmd:Property path="muws-p2-xs:OperationalStatus" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/OperationalStatus </muws-p2-xs:Capability> <rmd:ValidValues> <muws-p2-xs:OperationalStatus>Available</muws-p2-xs:OperationalStatus> <muws-p2-xs:OperationalStatus>PartiallyAvailable</muws-p2-xs:OperationalStatus> <muws-p2-xs:OperationalStatus>Unavailable</muws-p2-xs:OperationalStatus> <muws-p2-xs:OperationalStatus>Unknown</muws-p2-xs:OperationalStatus> </rmd:ValidValues> </rmd:Property>

<rmd:Property path="pda:DeviceState" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/DeviceState </muws-p2-xs:Capability> <rmd:ValidValues> <pda:DeviceState><pda:Off/></pda:DeviceState> <pda:DeviceState><pda:Initializing/></pda:DeviceState> <pda:DeviceState> <pda:NetworkConnected><pda:Connected/></pda:NetworkConnected> </pda:DeviceState> <pda:DeviceState> <pda:ServerConnected><pda:Connected/></pda:ServerConnected> </pda:DeviceState> <pda:DeviceState><pda:Synchronizing/></pda:DeviceState> <pda:DeviceState><pda:Idle/></pda:DeviceState> </rmd:ValidValues> </rmd:Property>

<rmd:Property path="pda:LastStateTransition" mutability="mutable" modifiability="read-only">



502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049

5050505150525053505450555056505750585059506050615062506350645065

50665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088

5089509050915092

197

198

<muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/DeviceState </muws-p2-xs:Capability> </rmd:Property>

<rmd:Property path="muws-p2-xs:Relationships" mutability="mutable" modifiability="read-only"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Relationships </muws-p2-xs:Capability> </rmd:Property>

<rmd:Operation path="muws-p2-xs:QueryRelationshipByType" idempotent="true"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Relationship </muws-p2-xs:Capability> </rmd:Operation>

<rmd:Operation path="pda:ResetServerConnectionMetric" idempotent="false"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/Metrics </muws-p2-xs:Capability> <muws-p2-xs:Capability> http://example.org/capabilities/PDAMetrics </muws-p2-xs:Capability> </rmd:Operation>

<rmd:Operation path="pda:shutdown" idempotent="false"> <muws-p2-xs:Capability> http://docs.oasis-open.org/wsdm/2004/12/muws/capabilities/State </muws-p2-xs:Capability> <rmd:ValidWhile Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"> count(/pda:MyPdaDeviceProperties/pda:DeviceState/pda:Off) = 0 </rmd:ValidWhile> <rmd:PostCondition Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"> /pda:MyPdaDeviceProperties/pda:DeviceState/pda:Off </rmd:PostCondition> </rmd:Operation>

</rmd:MetadataDescriptor></rmd:Definitions>

Finally, the following documents are required to support Relationships as resources:

The following represents the XML Schema of the resource properties document of the relationship between the PDA device and its server (GatewayRelationship is not a WSDM manageable resource, therefore, it does not require the MUWS ResourceID property):

<?xml version="1.0" encoding="utf-8"?><xs:schema targetNamespace="http://example.org/services/GatewayRelationship.xsd" xmlns:relext="http://example.org/services/GatewayRelationship.xsd" xmlns:muws-p2-xs="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">

<xs:import namespace="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"



5093509450955096509750985099

51005101510251035104510551065107

5108510951105111511251135114

5115511651175118511951205121512251235124

512551265127512851295130513151325133513451355136513751385139514051415142

5143

514451455146

51475148514951505151515251535154

515551565157

199

200

schemaLocation="http://docs.oasis-open.org/wsdm/2004/12/muws/wsdm-muws-part2.xsd"/>

<xs:element name="Date" type="xs:dateTime"/> <xs:element name="Location" type="xs:string"/>

<xs:element name="GatewayRelationshipProperties"> <xs:complexType> <xs:sequence> <xs:element ref="muws-p2-xs:Name" minOccurs="0"/> <xs:element ref="muws-p2-xs:Type"/> <xs:element ref="muws-p2-xs:Participant" minOccurs="2" maxOccurs="unbounded"/> <xs:element ref="relext:Date" minOccurs="0"/> <xs:element ref="relext:Location" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element></xs:schema>

The WSDL for this WS-Resource is as follows:

<?xml version="1.0" encoding="utf-8"?><w:definitions targetNamespace="http://example.org/services/GatewayRelationship.wsdl" xmlns:gatewayw="http://example.org/services/GatewayRelationship.wsdl" xmlns:gateway-xs="http://example.org/services/GatewayRelationship.xsd" xmlns:exh="http://example.org/services/localDefinitions.xsd" xmlns:wsrf-rp="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd" xmlns:wsrf-rpw="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl" xmlns:wsa="http://schemas.xmlsoap.org/ws/2005/08/addressing" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soapw="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:w="http://schemas.xmlsoap.org/wsdl/">


<w:import namespace="http://schemas.xmlsoap.org/ws/2005/08/addressing" location="http://schemas.xmlsoap.org/ws/2005/08/addressing/ws-addr.xsd"/>

<w:types> <xs:schema> <xs:import namespace="http://example.org/services/GatewayRelationship.xsd" schemaLocation="http://example.org/services/GatewayRelationship.xsd"/>


<xs:import namespace="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd" schemaLocation="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.xsd"/> </xs:schema> </w:types>


<w:portType name="GatewayRelationshipPortType" wsrf-rp:ResourceProperties="gateway-xs:GatewayRelationshipProperties"> <w:operation name="GetResourceProperty"> <w:input name="GetResourcePropertyRequest" message="wsrf-rpw:GetResourcePropertyRequest"



51585159

516051615162

51635164516551665167516851695170517151725173517451755176

5177

51785179518051815182518351845185518651875188518951905191

51925193519451955196

519751985199

52005201520252035204

520552065207

5208520952105211521252135214

5215521652175218

521952205221522252235224

201

202

wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyRequest"/> <w:output name="GetResourcePropertyResponse" message="wsrf-rpw:GetResourcePropertyResponse" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/GetResourcePropertyResponse"/> <w:fault name="ResourceUnknownFault" message="wsrf-rpw:ResourceUnknownFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/ResourceUnknownFault"/> <w:fault name="InvalidResourcePropertyQNameFault" message="wsrf-rpw:InvalidResourcePropertyQNameFault" wsa:Action="http://docs.oasis-open.org/wsrf/2004/06/wsrf-WS-ResourceProperties-1.2-draft-01.wsdl/GetResourceProperty/InvalidResourcePropertyQNameFault"/> </w:operation> </w:portType>

<w:binding name="GatewayRelationshipSoapOverHttpBinding" type="gatewayw:GatewayRelationshipPortType"> <soapw:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>

<w:operation name="GetResourceProperty"> <soapw:operation style="document"/> <w:input> <soapw:body use="literal"/> <soapw:header message="pdaw:ToHeader" part="document" use="literal"/> </w:input> <w:output> <soapw:body use="literal"/> </w:output> <w:fault> <soapw:fault name="ResourceUnknownFault" use="literal"/> </w:fault> <w:fault> <soapw:fault name="InvalidResourcePropertyQNameFault" use="literal"/> </w:fault> </w:operation> </w:binding>

<w:service name="GatewayRelationshipService"> <w:port name="GatewayRelationshipSoapPort" binding="gatewayw:GatewayRelationshipSoapOverHttpBinding"> <soapw:address location="http://example.org/services/GatewayRelationshipEndpoint"/> </w:port> </w:service>

</w:definitions>



5225522652275228522952305231523252335234523552365237523852395240524152425243

524452455246524752485249

525052515252525352545255525652575258525952605261526252635264526552665267

52685269527052715272527352745275

52765277

203

204

Appendix B. AcknowledgmentsThe following people made contributions to the WSDM MUWS Primer Version 1.0: Vaughn Bullard, Fred Carter, Zulah Eckert, Mark Ellison, Heather Kreger, Frederico Maciel, Bryan Murray, Richard Nikula, Thomas Studwell, Kirk Wilson, Zhili Zhang with special thanks to Bryan Murray, Kirk Wilson, and Mark Ellison as editors.

The following individuals were members of the committee while the WSDM MUWS Version 1.1 specification was developed and approved by the technical committee: Guru Bhat, Jeff Bohren, Vaughn Bullard, Winston Bumpus, Fred Carter, Michael Clements, David Cox, Zulah Eckert, Mark Ellison, John Fuller, Tony Gullotta, Heather Kreger, Richard Landau, Frederico Maciel, Tom Maguire, David Melgar, Bryan Murray, Richard Nikula, Mark Peel, Mitsunori Satomi, Thomas Studwell, William Vambenepe, Zhili Zhang.



5278

5279528052815282

528352845285528652875288

205

206

Appendix C. Revision History

Rev Date By Whom What

CD 2006-02-24 Kirk Wilson Title changes

wd-24 2006-01-29 Kirk Wilson, Mark Ellison

Final readability edits

Added references in text; completed Reference section

Added Acknowledgements section


Edit XML in Appendix A

Readability edits (section 2)

wd-22 2005-11-28 Kirk Wilson, Mark Elison

Continuation of wd-21.

Rewrite Metric examples

Example code simplication


Editorial corrections; result of F2F

Apply Mark Ellision’s edits

wd-20 2005-10-27 Kirk Wilson Make Relationships a separate major section.

Table of contents to show 5 levels

wd-19 2005-10-19 Kirk Wilson Continue verification of example XML

Transfer full RPDoc to Appendix A; show only snippets in text for readability

Reorganize sections of Chapter 2


Move MOWS chapters to a separate Primer. Add “MUWS” to Primer title

Include Mark Ellison’s edits on sections 2.1 through 2.7.

Verified consistency of example XML

Standardized namespace prefixes, spacing and styles

wd-17 2005-09-08 Bryan Murray No changes, only accepting all updates

wd-16 2005-09-08 Bryan Murray, Heather Kreger, Kirk Wilson

Added OperableCollections, updates in metadata section, XML example consistency, add more XML in appendix, use consistent prefix for pda



5289

207

208


and pdaw namespaces

wd-15 2005-09-07 Heather Kreger, Richard Nicula, Bryan Murray

Content for metadata section, updates in Metrics section, XML formatting and consistent examples

wd-14 2005-09-05 Bryan Murray, Richard Nicula, Fred Carter, Kirk Wilson

Moved adding resource-specific properties and operations to before extending a capability, added Metrics section content, updates in sections 4 and 5, updates in section 6.5, work on consistency in section 2, remove some references to spec features newer than WSDM 1.0, format some XML

wd-13 2005-09-02 Kirk Wilson, Heather Kreger, Bryan Murray

Updates to section 2.12, update section 2.6 to extend Description, starting text for Metrics section, add paragraph to Notification section, some XML in Extending Capability section, tweaks throughout based on suggestions from others

wd-12 2005-08-30 Bryan Murray Incorporate review of section 3, formatting changes throughout

wd-11 2005-08-26 Bryan Murray, Mark Ellison, Kirk Wilson, Heather Kreger

Modified sections as homework to people at the f2f, critical review of section 1, updates to Relationships

wd-10 2005-08-22 Bryan Murray Changes from f2f

wd-09 2005-08-19 Bryan Murray, Kirk Wilson, Heather Kreger

Added content to many sections

wd-08 2005-07-20 Kirk Wilson Sections 1, 3, 5

wd-07 2005-07-26 Bryan Murray Updates from June 2005 f2f. Add Advertisement section.

wd-06 2005-06-29 Bryan Murray, Winston Bumpus, Kirk Wilson, Richard Landau

Formatting, FCAPS, section 4, introduction

wd-05 2005-05-04 Zhili Zhang Add section 2.4 “Adding Property Access Operations”. Modify WSDL document in Appendix A.

wd-04 2005-04-27 Bryan Murray Changes discussed during April f2f. Added text to Description section.



209

210


wd-03 2005-02-28 Bryan Murray Outline revised based on Jan 2005 face-to-face, some section 2 content added

wd-02 2005-01-17 Bryan Murray Revised outline to incrementally add capabilities

wd-01 2004-09-30 Bryan Murray Initial version



5290

211

212

Appendix D. NoticesOASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification, can be obtained from the OASIS Executive Director.

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.

Copyright © OASIS Open 2004-2005. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself does not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.



5291

529252935294529552965297529852995300

530153025303

5304

530553065307530853095310531153125313

53145315

53165317531853195320

213

214