Archive Content

Please note this page is present for reference only. QMan has been removed and is no longer a released component.

Metadata Exchange (WS-MetadataExchange)

Description

QMan WS-Resources are basically web services. Web Services use metadata to describe what other endpoints need to know in order to interact with them.
The MetadataExchange interface allows a requestor to query a specific WS-Resource for its metadata.

Request

01.	<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
02.		<soap:Header>
03.     	        <wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
04.				http://localhost:8080/qman/services/QManWsResource
05.			</wsa:To>
06.     	        <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
07.				http://schemas.xmlsoap.org/ws/2004/09/mex/GetMetadata
08.			</wsa:Action>
09.        	        <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">
10.				uuid:0cdb5112-09e0-ac39-06ba-393843f06e42
11.			</wsa:MessageID>
12.        	        <wsa:From xmlns:wsa="http://www.w3.org/2005/08/addressing">
13.          	                <wsa:Address>
14.					http://www.w3.org/2005/08/addressing/role/anonymous
15.				</wsa:Address>
16.        	        </wsa:From>
17.        	        <qman-wsa:ResourceId
				xmlns:wsa="http://www.w3.org/2005/08/addressing"
				xmlns:qman-wsa="http://amqp.apache.org/qpid/management/qman/addressing"
				wsa:IsReferenceParameter="true">
18.				a3759467-bede-476d-8dde-169f1a652191
19.	   		</qman-wsa:ResourceId>
		</soap:Header>
20.		<soap:Body>
21.    		<wsx:GetMetadata xmlns:wsx="http://schemas.xmlsoap.org/ws/2004/09/mex">
22.			<wsx:Dialect>
23.				http://schemas.xmlsoap.org/wsdl/
24.			</wsx:Dialect>
    		</wsx:GetMetadata>
		</soap:Body>
	</soap:Envelope>

Line(s)	Description
01	The SOAP <Envelope> is the root element in every SOAP message, and contains two child elements, <Header> and <Body>
02	The SOAP Header will contain all metadata used for identifying the conversation participants (requestor and provider)
03 - 05	Convey the target endpoint also known (in the request phase) as service provider. Note that an additional information (ResourceId) needs to be supplied in order to correctly identify the target WS-Resource
06 - 08	Indicate this is a Get Metadata request. This is done using a wsa:Action that is part of WS-Addressing specification
09 - 11	Convey a unique identifier associated with the current message. This will be used for request / response messages correlation
12 - 15	Provide the address of the source endpoint also known (in the request phase) as service requestor
17 - 19	Provide the WS-Resource identifier. That allows to correctly identify the requested instance
20	The SOAP <Body> is a mandatory sub-element of the Envelope, which contains information intended for the recipient of the current message;
21	The GetMetadata request;
22	Dialect associated with the requested metadata. We could say that it identifies a specific kind of metadata. As MetadataExchange specs says : "When this element is present, the response MUST include only Metadata Sections with the indicated dialect; if the receiver does not have any Metadata Sections of the indicated dialect, the response MUST include zero Metadata Sections. When this element is not present, the implied value is any dialect." At the moment there are two supported dialects : Web Service Description Language (WSDL) : dialect in this case is : _http://schemas.xmlsoap.org/wsdl/_ Resource Metadata Descriptor (RMD) : dialect in this case is : _http://docs.oasis-open.org/wsrf/rmd-1_

Response

MetadataExchange supports two dialects and therefore there could be two different responses depending on the requested dialect.

WSDL Dialect

The following illustrates an example response of a GetMetadata request with WSDL dialect.
For simplicity only the top level <wsdl:definitions> element has been reported. You can find a complete metadata exchange conversation under the example directory.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
    <soap:Header>
01.		<wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
02.			http://www.w3.org/2005/08/addressing/role/anonymous
03.		</wsa:To>
04.		<wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
05.			http://schemas.xmlsoap.org/ws/2004/09/mex/GetMetadataResponse
06.		</wsa:Action>
07.		<wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">
08.			uuid:980617c8-e3a0-ebf1-8f5a-2b43d3d6d416
09.		</wsa:MessageID>
10.		<wsa:RelatesTo RelationshipType="wsa:Reply" xmlns:wsa="http://www.w3.org/2005/08/addressing">
11.			uuid:0cdb5112-09e0-ac39-06ba-393843f06e42
12.		</wsa:RelatesTo>
13.		<wsa:From xmlns:wsa="http://www.w3.org/2005/08/addressing">
14.			<wsa:Address>
15.				http://localhost:8080/qman/services/QManWsResource
16.			</wsa:Address>
17.			<wsa:ReferenceParameters>
18.				<qman-wsa:ResourceId
					wsa:IsReferenceParameter="true"
                                        xmlns:qman-wsa="http://amqp.apache.org/qpid/management/qman/addressing"
					xmlns:wsa="http://www.w3.org/2005/08/addressing">
19.					a3759467-bede-476d-8dde-169f1a652191
20.				</qman-wsa:ResourceId>
            </wsa:ReferenceParameters>
        </wsa:From>
    </soap:Header>
    <soap:Body>
21.		<wsx:Metadata xmlns:wsx="http://schemas.xmlsoap.org/ws/2004/09/mex">
22.		<wsx:MetadataSection>
23.			<wsdl:definitions>
				...
24.			</wsdl:definitions>
			</wsx:MetadataSection>
		</wsx:Metadata>
	</soapBody>
</soap:Envelope>

Line(s)	Description
01 - 03	Convey the recipient of the response message. Note that this time we are talking about the service requestor; The address matches the <wsa:From> previously found in the corresponding request
04 - 06	Indicate this is a Get Metadata response. This is done as usual using a wsa:Action that is part of WS-Addressing specification
07 - 09	Convey a unique identifier associated with the current response message
10 - 12	This element provides the identifier of the correlated (request) message
13	The <wsa:From> element (part of WS-Addressing specs too) identifies the source endpoint, the originator of this response message
14 - 15	This is the address of the source service endpoint. As said for lines 01-03 this time this is referred to service provider (the message originator)
17	This element will contain all parameters needed to identify the originator identity
18 - 20	This is the (source) resource identifier which correctly identify a specific WS-Resource (instance)
21	<wsx:Metadata> is the top level container element of received metadata. It is composed by several sections (one for each requested dialect)
22	Metadata section for WSDL
23 - 24	Web Service Description Language (WSDL)

RMD Dialect

The following illustrates an example response of a GetMetadata request with RMD dialect.
For <Header> section information please refer to the previous section.
For simplicity we will report a metadata descriptor for a resource that has only one properties.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
    <soap:Header>
01.		<wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
02.			http://www.w3.org/2005/08/addressing/role/anonymous
03.		</wsa:To>
04.		<wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
05.			http://schemas.xmlsoap.org/ws/2004/09/mex/GetMetadataResponse
06.		</wsa:Action>
07.		<wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">
08.			uuid:980617c8-e3a0-ebf1-8f5a-2b43d3d6d416
09.		</wsa:MessageID>
10.		<wsa:RelatesTo RelationshipType="wsa:Reply" xmlns:wsa="http://www.w3.org/2005/08/addressing">
11.			uuid:0cdb5112-09e0-ac39-06ba-393843f06e42
12.		</wsa:RelatesTo>
13.		<wsa:From xmlns:wsa="http://www.w3.org/2005/08/addressing">
14.			<wsa:Address>
15.				http://localhost:8080/qman/services/QManWsResource
16.			</wsa:Address>
17.			<wsa:ReferenceParameters>
18.				<qman-wsa:ResourceId
					wsa:IsReferenceParameter="true"
                                        xmlns:qman-wsa="http://amqp.apache.org/qpid/management/qman/addressing"
					xmlns:wsa="http://www.w3.org/2005/08/addressing">
19.					a3759467-bede-476d-8dde-169f1a652191
20.				</qman-wsa:ResourceId>
            </wsa:ReferenceParameters>
        </wsa:From>
    </soap:Header>
    <soap:Body>
21.		<wsx:Metadata xmlns:wsx="http://schemas.xmlsoap.org/ws/2004/09/mex">
22.		<wsx:MetadataSection>
24.			<wsrmd:MetadataDescriptor
				interface="qman:QManWsResourcePortType"
                                name="QManWsResourceMetadata"
                                wsdlLocation="http://docs.oasis-open.org/wsrf/rmd-1 QManWsResource.wsdl"
                                      xmlns:qman="http://amqp.apache.org/qpid/management/qman" xmlns:wsrmd="http://docs.oasis-open.org/wsrf/rmd-1">
25.				<wsrmd:Property
26.					xmlns:qman="http://amqp.apache.org/qpid/management/qman">
27.					modifiability="read-write"
28.					mutability="mutable"
29.					name="qman:operatingSystem"

30.					<wsrmd:ValidValues>
						<qman:operatingSystem>Linux</<qman:operatingSystem>
						<qman:operatingSystem>Tru64</<qman:operatingSystem>
						<qman:operatingSystem>HP-UX</<qman:operatingSystem>
						<qman:operatingSystem>Windows XP</<qman:operatingSystem>
31.					</wsrmd:ValidValues>

32.					<wsrmd:StaticValues>
						...
						...
33.					</wsrmd:StaticValues>

34.					<wsrmd:InitialValues>
						...
						...
35.					</wsrmd:InitialValues>

				</wsrmd:Property>
				...
			</wsrmd:MetadataDescriptor>
			</wsx:MetadataSection>
		</wsx:Metadata>
	</soapBody>
</soap:Envelope>

Line(s)	Description
24	Top level element for resource metadata descriptor. The most important things are its attributes. There you can see port type (interface), descriptor name (name) and wsdl location
25 - 29	Property metadata descriptor. This contains metadata information about a specific property. As you can see a property has several attributes : mutability : The property has a constant (constant) value or it could change (mutable); modifiability : Property access mode. Can be "read-only" or "read-write"; name : the name of the property.
30 - 31	ValidValues are used to restrict the set of valid values that a property can assume
32 - 33	StaticValues are used to define a minimum set of values that a property can assume
34 - 35	InitialValues are used to declatively define the set of values that a property will contain when the owner resource is initialized at first time

Faults

The only exception that could be thrown in a metadata exchange scenario is when the requestor indicates an unknown dialect.

Quick links

WS-MetadataExchange
Web Services Addressing (WS-Addressing)
Web Service Description Language
Web Services Resource Metadata 1.0 (WS-ResourceMetadataDescriptor)

Child pages

MetadataExchange