Web Services Architecture and Its Specifications [Electronic resources] : Essentials for Understanding WS-* نسخه متنی

Transfer

The WS-Transfer specification defines how new Web services resources can be created with a factory and also how those resources can be retrieved and updated. In our example scenario, each professor has a collection of custom books available for download. Their custom collections can then be used to order additional courseware through the School of Fine Art's procurement system. The books within the collection are determined by each instructor at the beginning of the school year and then updated as needed.

Figure 16-2 illustrates how new book collection resources used in our sample scenario are created and maintained over time.

A Create message [Message 1] is sent to the factory to request a new Web services resource.

Once the Create message is processed, a CreateResponse message [Message 2] is returned, including the Endpoint Reference where the new resource can be found.

Updates to the resource are sent over a Put message [Message 3]. When the resource is updated, the service responds with a PutResponse message [Message 4].

The current XML representation of the resource is obtained from a Get message [Message 5], where a GetResponse message [Message 6] is returned.

Finally, when the resource is no longer needed, the client requests its destruction with a Delete message [Message 7], which is confirmed with a DeleteResponse [Message 8].

Examples of each message used to create, update, and delete the book collection resource are presented below.

Create
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)        http://schemas.xmlsoap.org/ws/2004/09/transfer/Create
(05)    </wsa:Action>
(06)        ...
(07)   </env:Header>
(08)   <env:Body>
(09)    <msp:Collection>
(10)     <msp:Instructor>L. F. Cabrera</msp:Instructor>
(11)     <msp:Email>l.cabrera@fineartschool.com</msp:Email>
(12)     <msp:Items>
(13)      <item ISBN="0-1234-..."/>
(14)      <item ISBN="0-2345-..."/>
(15)      <item ISBN="0-3456-..."/>
(16)      <item ISBN="0-4567-..."/>
(17)     </msp:Items>
(18)    </msp:Collection>
(19)   </env:Body>
(20)  </env:Envelope>

Lines 0305 This value for Action indicates that this is a Create message as specified in WS-Transfer.

Lines 0918 A Create message requests that a factory create a new resource. This resource is application-defined. This example is a request to create a book collection for Professor Cabrera, including four book titles.

If the resource is successfully created by the factory, the service responds with an endpoint reference to that resource and an optional update to information about the resource itself. In this example, a CollectionID element is included in the endpoint reference for more efficient update processing, and the professor's account ID is added to the resource itself.

CreateResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)        http://schemas.xmlsoap.org/ws/2004/09/transfer/CreateResponse
(05)    </wsa:Action>
(06)        ...
(07)   </env:Header>
(08)   <env:Body>
(09)    <wxf:ResourceCreated>
(10)     <wsa:Address>http://ex.mspress.com/collections</wsa:Address>
(11)     <wsa:ReferenceProperties>
(12)      <msp:CollectionID>cabrera1902</msp:CollectionID>
(13)     </wsa:ReferenceProperties>
(14)    <wxf:ResourceCreated>
(15)    <msp:Collection>
(16)     <msp:Instructor>L. F. Cabrera</msp:Instructor>
(17)     <msp:AccountID>1234</msp:AccountID>
(18)     <msp:Email>l.cabrera@fineartschool.com</msp:Email>
(19)     <msp:Items>...</msp:Items>
(20)    </msp:Collection>
(21)   </env:Body>
(22)  </env:Envelope>

Lines 0305 This value for Action indicates that this is a CreateResponse message as specified in WS-Transfer.

Lines 0914 The resource was successfully created, and an endpoint reference for future access was returned.

Line 17 The XML representation of the resource was also returned to the client, because the factory changed the resource by adding an application-specific AccountID element.

Once the resource is created, the School of Fine Art's procurement system, or any other endpoints with the appropriate endpoint reference, can access and update the collection. In our example scenario, the professor has entered a request to remove one of the book titles from the collection. The client sends a Put message to the resource with the requested change.

Put
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)        http://schemas.xmlsoap.org/ws/2004/09/transfer/Put
(05)    </wsa:Action>
(06)    <wsa:Address>http://ex.mspress.com/collections</wsa:Address>
(07)    <msp:CollectionID>cabrera1902</msp:CollectionID>
(08)        ...
(09)   </env:Header>
(10)   <env:Body>
(11)    <msp:Collection>
(12)     <msp:Instructor>L. F. Cabrera</msp:Instructor>
(13)     <msp:Email>l.cabrera@fineartschool.com</msp:Email>
(14)     <msp:AccountID>1234</msp:AccountID>
(15)     <msp:Items>
(16)      <item ISBN="0-1234-..."/>
(17)      <item ISBN="0-2345-..."/>
(18)      <item ISBN="0-3456-..."/>
(19)     </msp:Items>
(20)    </msp:Collection>
(21)   </env:Body>
(22)  </env:Envelope>

Lines 0305 This value for Action indicates that this is a Put message as specified in WS-Transfer.

Lines 0607 The request is sent to the address provided in the endpoint reference returned by the previous CreateResponse. The CollectionID reference property is also included in the message header.

Lines 1120 An updated XML representation of the book collection is provided in the SOAP message body. The item list has been revised to include only three book titles, and the AccountID element is included.

If the update is successful, the PutResponse message is structured as shown here:

PutResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)        http://schemas.xmlsoap.org/ws/2004/09/transfer/PutResponse
(05)   </wsa:Action>
(06)       ...
(07)  </env:Header>
(08)  <env:Body/>
(09) </env:Envelope>

Lines 0305 This value for Action indicates that this is a PutResponse message as specified in WS-Transfer.

Line 08 Because the service did not change the XML representation of the book collection when it saved the update, the SOAP Body is empty in this response.

Over time, other endpoints might cause updates to the resource. If this happens to our example book collection, the client can request an updated XML representation. In this example, the Get message returns the Collection as updated by the Put example:

Get
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)        http://schemas.xmlsoap.org/ws/2004/09/transfer/Get
(05)    </wsa:Action>
(06)    <wsa:Address>http://ex.mspress.com/collections</wsa:Address>
(07)    <msp:CollectionID>cabrera1902</msp:CollectionID>
(08)        ...
(09)   </env:Header>
(10)   <env:Body/>
(11)  </env:Envelope>

Lines 0305 This value for Action indicates that this is a Get message as specified in WS-Transfer.

Lines 0607 The Get request is routed using the endpoint information provided by the factory. This message has no body block.

Line 10 No Body blocks are defined for the Get message.

The expected response to this request is the current XML representation of our book collection:

GetResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)        http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse
(05)    </wsa:Action>
(06)        ...
(07)   </env:Header>
(08)   <env:Body>
(09)    <msp:Collection>
(10)     <msp:Instructor>L. F. Cabrera</msp:Instructor>
(11)     <msp:Email>l.cabrera@fineartschool.com</msp:Email>
(12)     <msp:AccountID>1234</msp:AccountID>
(13)     <msp:Items>
(14)      <item ISBN="0-1234-..."/>
(15)      <item ISBN="0-2345-..."/>
(16)      <item ISBN="0-3456-..."/>
(17)     </msp:Items>
(18)    </msp:Collection>
(19)   </env:Body>
(20)  </env:Envelope>

Lines 0305 This value for Action indicates that this is a GetResponse message as specified in WS-Transfer.

Lines 0918 The XML representation of Professor Cabrera's book collection is returned.

Finally, when the resource (this particular book collection) is no longer needed, a Delete message is sent to the Microsoft Press system as a notification that the resource can be deleted and that subsequent messages addressed to that resource should fail:

Delete
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)        http://schemas.xmlsoap.org/ws/2004/09/transfer/Delete
(05)    </wsa:Action>
(06)    <wsa:Address>http://ex.mspress.com/collections</wsa:Address>
(07)    <msp:CollectionID>cabrera1902</msp:CollectionID>
(08)    <wsa:MessageID>
(09)        uuid:11111111-2222-1111-2222-888888888888
(10)    </wsa:MessageID>
(11)        ...
(12)   </env:Header>
(13)   <env:Body/>
(14)  </env:Envelope>

Lines 0305 This value for Action indicates that this is a Delete message as specified in WS-Transfer.

Lines 0607 The Delete request is addressed directly to the resource endpoint.

Lines 0810 The MessageID is used to correlate the response returned by the endpoint.

Line 13 Delete requests do not have a SOAP Body block.

The response returned after successfully deleting the resource is shown next. Determining exactly which resource was deleted is achieved using the RelatesTo element.

DeleteResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)        http://schemas.xmlsoap.org/ws/2004/09/transfer/DeleteResponse
(05)    </wsa:Action>
(06)        ...
(07)    <wsa:RelatesTo>
(08)        uuid:11111111-2222-1111-2222-888888888888
(09)    </wsa:RelatesTo>
(10)   </env:Header>
(11)   <env:Body/>
(12)  </env:Envelope>

Lines 0305 This value for Action indicates that this is a DeleteResponse message as specified in WS-Transfer.

Lines 0709 The RelatesTo element provides the mechanism to correlate this response with the related Delete request.