Introducing the Implied Resource Pattern - GetResourceProperty
(Page 4 of 7 )
WS-ResourceProperties defines a simple "get by name" method to retrieve a WS-Resource's resource property values in a standard way. You can think of this operation as a simple, straightforward getter method. WS-ResourceProperties requires that this operation appear on any portType that supports access to a WS-Resource. In fact, it's a rule that any portType that includes the resourceProperties attribute in its definition must include this operation. The other operations defined by WS-ResourceProperties are optional.
In our situation, the customer is interested in examining the status of the purchase order. Given that SkatesTown didn't define an application-specific operation to retrieve the status of the PurchaseOrder WS-Resource, the customer needs to use the GetResourceProperty operation.
To retrieve the value of the poRP:status resource property, the customer would need to send the following message to the WS-Resource. Recall that in the WS-Resource Framework, a particular WS-Resource is targeted by sending a message to a Web service (as indicated by the Address element of an endpoint reference) and including the identity of the WS-Resource (as indicated by the referenceProperties element of the endpoint reference). Here is an example SOAP request message to retrieve the status of the PurchaseOrder:
<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/
soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/
addressing"
xmlns:wsrp=
"http://www.ibm.com/xmlns/stdwip/web-services/
WS-ResourceProperties"
xmlns:poRP="http://www.skatestown.com/ns/
poResourceProperties">
<soap:Header>
<wsa:Action>
http://www.ibm.com/xmlns/stdwip/web-services/
WS-ResourceProperties/
GetResourceProperty
</wsa:Action>
<wsa:To soap:mustUnderstand="1">
http://www.skatestown.com/services/PO
</wsa:To>
<poRP:POResourceID>43871</poRP:POResourceID>
</soap:Header>
<soap:Body>
<wsrp:GetResourceProperty>
poRP:status
</wsrp:GetResourceProperty>
</soap:Body>
</soap:Envelope>
Note the use of the implied resource pattern in the request message. The wsa:To element and the reference property (poRP:POResourceID) are derived from the endpoint reference.
The response message is straightforward; it contains the value of the status resource property for the WS-Resource targeted in the request message:
<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/
soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/
addressing"
xmlns:wsrp=
"http://www.ibm.com/xmlns/stdwip/web-services/
WS-ResourceProperties"
xmlns:poRP="http://www.skatestown.com/ns/
poResourceProperties">
<soap:Header>
<wsa:Action>
http://www.ibm.com/xmlns/stdwip/web-services/
WS-ResourceProperties/
GetResourceProperty
</wsa:Action>
<wsa:To soap:mustUnderstand="1">
http://www.skateWarehouse.com/someEndpoint
</wsa:To>
</soap:Header>
<soap:Body>
<wsrp:GetResourcePropertyResponse
<poRP:status>received</poRP:status>
</wsrp:GetResourcePropertyResponse>
</soap:Body>
</soap:Envelope>
The Skateboard Warehouse could use the simple GetResourceProperty operation to retrieve single resource property values. However, if its application needs to frequently retrieve the value of multiple resource properties, it's better off using the operation we describe in the next section.
GetMultipleResourceProperties
The designers of WS-ResourceProperties included another get operation, GetMultipleResourceProperties, that looks similar to the GetResourceProperty operation. Although both operations allow a requestor to retrieve values of resource properties, GetMultipleResourceProperties allows the requestor to retrieve the values of multiple resource properties with a single message exchange by including a list of resource property QNames in the request message. Although there is overlap between the two operations, they address different usage scenarios:
The GetResourceProperty operation is a required operation. It's the minimal, simple operation to allow resource-constrained Web services to participate in WS-ResourceProperties.
The GetMultipleResourceProperties operation allows requestors to avoid multiple round trips to retrieve the value of multiple resource property elements. This avoids applications doing too many fine-grained network accesses to retrieve resource property information, which yields poor application performance and inefficient use of the network.
In our running example with the SkatesTown purchase order WS-Resource, if The Skateboard Warehouse wanted to examine the values of several resource properties of their PurchaseOrder WS-Resource—say, status, status date, and contact person—then it could retrieve this information with a single GetMultipleResourceProperties operation:
<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/
soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/
addressing"
xmlns:wsrp=
"http://www.ibm.com/xmlns/stdwip/web-services/
WS-ResourceProperties"
xmlns:poRP="http://www.skatestown.com/ns/
poResourceProperties">
<soap:Header>
<wsa:Action>
http://www.ibm.com/xmlns/stdwip/web-services/
WS-ResourceProperties/
GetResourceProperty
</wsa:Action>
<wsa:To soap:mustUnderstand="1">
http://www.skatestown.com/services/PO
</wsa:To>
<poRP:POResourceID>43871</poRP:POResourceID>
</soap:Header>
<soap:Body>
<wsrp:GetMultipleResourceProperties>
<wsrp:ResourceProperty>poRP:
status</wsrp:ResourceProperty>
<wsrp:ResourceProperty>poRP:
statusDate</wsrp:ResourceProperty>
<wsrp:ResourceProperty>poRP:
contactPerson</wsrp:ResourceProperty>
</wsrp:GetMultipleResourceProperties>
</soap:Body>
</soap:Envelope>
Again, remember that the implied resource pattern is used to target the correct PurchaseOrder WS-Resource. The response message contains the values of the resource properties identified by QName:
<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/
soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/
addressing"
xmlns:wsrp=
"http://www.ibm.com/xmlns/stdwip/web-services/
WS-ResourceProperties"
xmlns:poRP="http://www.skatestown.com/ns/
poResourceProperties">
<soap:Header>
<wsa:Action>
http://www.ibm.com/xmlns/stdwip/web-
services/WS-ResourceProperties/
GetResourceProperty
</wsa:Action>
<wsa:To soap:mustUnderstand="1">
http://www.skateWarehouse.com/someEndpoint
</wsa:To>
</soap:Header>
<soap:Body>
<wsrp:GetMultipleResourcePropertiesResponse>
<poRP:status>received</poRP:status>
<poRP:statusDate>2004-03-01T12:00:00</poRP:
statusDate>
<poRP:contactPerson>Jane Smith</poRP:
contactPerson>
<poRP:contactPerson>Alex Jones</poRP:
contactPerson>
</wsrp:GetMultipleResourcePropertiesResponse>
</soap:Body>
</soap:Envelope>
It's up to the requestor's application to correlate which elements in the response message correspond to which resource properties listed in the request message. Because this is all XML, the correlation is simple: the values of the resource property named poRP:status are identified by elements whose tag is poRP:status.
Note that one of the resource properties, poRP:contactPerson, has multiple values. The cardinality of the resource property is determined by the minOccurs and maxOccurs attributes in the resource property document declaration. Whereas many resource properties will have minOccurs and maxOccurs values of 1, an optional resource property is indicated by a minOccurs value of 0; and a resource property with possibly multiple values is indicated by a maxOccurs value greater than 1.
Next: QueryResourceProperties >>
More Web Services Articles
More By Sams Publishing
|
 This article is excerpted from chapter 8 of the book Building Web Services with Java: Making sense of XML, SOAP, WSDL, and UDDI, written by Steve Graham et al. (Sams; ISBN: 0672326418). Check it out today at your favorite bookstore. Buy this book now.
|
|
