[Source: http://www.oasis-open.org/committees/download.php/16894/wsdm-primer-muws-cd.doc; cache.]

---

Document identifier:

wsdm-primer-muws-cd

Location:

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

Editors:

Bryan Murray, Hewlett-Packard <bryan.murray@hp.com>

Kirk Wilson, Computer Associates <kirk.wilson@ca.com>

Mark Ellison, Ellison Software Consulting <ellison@ieee.org>

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 wsdm@lists.oasis-open.org list. Others should subscribe to and send comments to the wsdm-comment@lists.oasis-open.org list. To subscribe, send an email message to wsdm-comment-request@lists.oasis-open.org 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.

1      Introduction. 5

1.1 Namespaces. 5

2      Building a Manageable Resource. 7

2.1 The Resource. 7

2.2 Exposing Resource Identity. 7

2.2.1 The Resource Properties Document 7

2.2.2 The WSDL Document 9

2.2.3 Example SOAP Messages. 11

2.3 Adding a WSDM Capability. 13

2.3.1 Modifying the Resource Properties Document 14

2.3.2 Examples of Description Capability Messages. 15

2.4 Manageability Characteristics. 16

2.5 Adding Property Access Operations. 17

2.5.1 Modifying the WSDL Document 17

2.5.2 Example of Property Access Operation Messages. 21

2.6 Operational Status. 23

2.7 Metrics. 24

2.7.1 A Scenario for PDA Metrics. 25

2.7.2 Metric Datatypes and Exposing Metrics. 25

2.8 Extending a Capability. 27

2.9 Adding Resource-specific Operations and Properties. 28

2.9.1 Adding Resource-specific Properties. 28

2.9.2 Adding Resource-specific operations. 28

2.10 Notifications. 29

2.10.1 Changes to the Resource Properties Document 30

2.10.2 Changes to the WSDL Document 30

2.10.3 ManagementEvent Format 31

2.10.3.1 Example. 33

2.10.4 Creating a TopicSpace. 34

2.10.4.1 Topics for Resource-Specific Metrics. 34

2.11 Building and Exposing a Metadata Document 35

2.11.1 Constructing PDA Device Metadata. 37

2.11.2 Metric Metadata. 39

2.11.2.1 PDA Resource-specific Metrics. 40

2.11.2.2 Example PDA Resource Properties Document with Metrics. 42

2.12 State. 43

2.12.1 State Model Metadata. 47

2.13 Advertising a Resource. 48

2.14 Operable Collections. 49

3      Building Relationships. 52

3.1 WSDM Relationships and UML Associations. 52

3.1.1 Defining a Relationship Type. 53

3.2 The Relationship Capability. 54

3.2.1 Relationships in the Resource Properties Document 54

3.2.2 Querying Relationships by Type: WSDL Modifications. 55

3.2.2.1 An Example using QueryingRelationshipsByType. 56

3.2.3 Relationship Events. 57

3.2.4 Relationship Metadata. 59

3.2.5 Guidelines for Supporting the Relationships Capability. 59

3.3 Accessing Relationships as WS-Resources. 60

3.3.1 Accessing a MUWS Relationships as a WS-Resource. 60

3.3.2 Treating Relationships as Standalone Resources. 61

4      Managing MUWS Resources. 63

4.1 Discovering Resources. 63

4.1.1 Explicit Configuration. 63

4.1.2 Resource Advertisement and Registries. 63

4.1.2.1 UDDI 64

4.1.2.2 ServiceGroup. 64

4.1.2.3 Relationship Registries. 64

4.1.3 Using The MUWS Relationship Capability. 64

4.1.3.1 Discovering Resources from Relationships. 65

4.1.3.2 Monitoring Relationships. 66

4.1.4 Summary. 66

4.2 Managing and Monitoring. 67

4.2.1 Discovering Manageability Capabilities. 67

4.2.2 Using Manageability Capabilities. 67

4.2.2.1 Determining Resource Identity. 67

4.2.2.2 Obtaining Description and State Information. 69

4.2.2.3 Configuring the Manageable Resource. 70

4.2.2.4 Querying and Traversing Relationships. 70

5      Further Considerations. 72

5.1 Defining a Taxonomy in WSDM.. 72

5.1.1 Steps for Constructing a Taxonomy. 74

5.2 Alternate Means of Accessing Manageability. 74

5.3 FCAPS Discussion. 75

5.4 The Web Services Platform.. 75

5.4.1 Initial Focus. 76

5.4.1.1 Properties. 76

5.4.1.2 Meta Data. 76

5.4.1.3 Addressing. 76

5.4.1.4 Notification. 77

5.4.1.5 Versioning. 77

5.4.1.6 Security. 77

5.4.1.7 Registration, Discovery and Location. 78

5.4.2 Future Focus. 78

5.4.2.1 Policy. 78

5.4.2.2 Name Resolution. 78

5.4.2.3 Transaction. 79

5.4.2.4 Flow.. 79

5.4.2.5 Negotiation. 80

6      References. 81

Appendix A. Complete XML Documents. 83

Appendix B. Acknowledgments. 103

Appendix C. Revision History. 104

Appendix D. Notices. 107

 

After 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 Namespaces

Common 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
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.

 

This 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 Resource

We 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 Identity

The 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 Document

In 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 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:

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.

2.2.2 The WSDL Document

Now 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::

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 ...> ... </w:portType>	the portType section	The portType “MyPdaDevicePortType” includes the 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 Messages

We 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:

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 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:

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:

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:

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.

2.3 Adding a WSDM Capability

Now 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 Document

The 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:

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

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.

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 Messages

We 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 wit