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

Enumeration

The WS-Enumeration specification provides mechanisms to request contents of a sequence of elements hosted by a Web service. In our example scenario, we use this capability for the procurement system to request the list of custom electronic books related to a particular topic that are available from the Microsoft Press order management system. Specifically, the procurement system requests the list of all available books related to Art History. An example of this is shown in Figure 16-1.

The procurement system sends an Enumerate message [Message 1] to the order management system to request the set of books that are available.

The order management system replies with an EnumerateResponse message [Message 2] carrying the enumeration context that can be used to traverse the list of books that are available.

The enumeration context is then used as a part of a series of Pull [Message 3] and Pull-Response [Message 4] messages. The procurement system iterates through the list until the end.

Once the last item in the sequence is retrieved, the procurement system frees the enumeration context with a Release message [Message 5], which is confirmed by a Release-Response message [Message 6].

The procurement system then uses the list of available books to send PurchaseOrders as described in our earlier scenario.

Examples of each message transmitted in this scenario are shown below.

The Enumerate message is used to request a list of items matching a specified filter. In our example here, we show a request for the list of all items where the subject (as defined by the Microsoft Press order management system) is Art History.

Enumerate
(01) <env:Envelope>
(02)  <env:Header>
(03)   <wsa:Action>
(04)    http://schemas.xmlsoap.org/ws/2004/09/enumeration/Enumerate
(05)   </wsa:Action>
(06)   ...
(07)  </env:Header>
(08)  <env:Body>
(09)   <wsen:Enumerate>
(10)    <wsen:Expires>PT20M</wsen:Expires>
(11)    <wsen:Filter Dialect="msp:Subject">Art History</wsen:Filter>
(12)   </wsen:Enumerate>
(13)  </env:Body>
(14) </env:Envelope>

Lines 0305 This URI identifies the message as an Enumerate message.

Line 10 The requested expiration duration for the enumeration context is 20 minutes.

Line 11 The request filter is a custom application-specific dialect for book subjects. The value of the Filter element is the subject of Art History.

If the request for an enumeration context is accepted, the endpoint returns an Enumerate-Response message containing the enumeration context that will be used in subsequent Pull messages:

EnumerateResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/09/enumeration/EnumerateResponse
(05)    </wsa:Action>
(06)    ...
(07)   </env:Header>
(08)   <env:Body>
(09)    <wsen:Enumerate>
(10)     <wsen:Expires>PT10M</wsen:Expires>
(11)     <wsen:EnumerationContext>
(12)      <msp:ContextID>12345</msp:ContextID>
(13)     </wsen:EnumerationContext>
(14)    </wsen:Enumerate>
(15)   </env:Body>
(16)  </env:Envelope>

Lines 0305 This value for the Action element indicates that the message is an Enumerate-Response message.

Line 10 Although the requested expiration time for the enumeration context was set for 20 minutes, the endpoint overrode this request and the enumeration context expires after 10 minutes.

Lines 1113 The identifier for the enumeration context for subsequent Pull messages is provided. The XML representation of the enumeration context is application-defined.

Once the enumeration context is established, a series of Pull messages are used to retrieve the list of Art Historyrelated books that are available:

Pull
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/09/enumeration/Pull
(05)    </wsa:Action>
(06)    ...
(07)   </env:Header>
(08)   <env:Body>
(09)    <wsen:Pull>
(10)     <wsen:EnumerationContext>
(11)      <msp:ContextID>12345</msp:ContextID>
(12)     </wsen:EnumerationContext>
(13)     <wsen:MaxTime>PT1M</wsen:MaxTime>
(14)     <wsen:MaxElements>25<wsen:MaxElements>
(15)     <wsen:MaxCharacters>2048</wsen:MaxCharacters>
(16)    </wsen:Pull>
(17)   </env:Body>
(18)  </env:Envelope>

Lines 0305 This value for the Action element indicates that the message is a Pull message.

Line 06 Other SOAP header elements, such as addressing and security information, are omitted for brevity.

Lines 1012 The enumeration context specifies what list of values is being requested.

Line 13 The MaxTime element specifies the maximum amount of time that the sender is willing to wait for a response from the data source. In this example, the data source should not spend more than one minute assembling the response.

Line 14 The MaxElements element specifies the maximum number of items to return in a single response. In this example, no more than 25 titles are returned in a single response.

Line 15 The MaxCharacters element specifies the maximum number of Unicode characters that can be returned in an item list. This value does not include the size of the SOAP message headers or other elements in the body. In our example, the item list must be no larger than 2048 characters.

The PullResponse message then returns the set of requested items:

PullResponse
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/09/enumeration/PullResponse
(05)    </wsa:Action>
(06)    ...
(07)   </env:Header>
(08)   <env:Body>
(09)    <wsen:PullResponse>
(10)     <wsen:EnumerationContext>
(11)      <msp:ContextID last="Canvas Restoration">12345</msp:ContextID>
(12)     </wsen:EnumerationContext>
(13)     <wsen:Items>
(14)      <msp:Title ISBN="...">Ancient Pottery</msp:Title>
(15)      <msp:Title ISBN="...">Baskets and Buckets</msp:Title>
(16)      <msp:Title ISBN="...">Canvas Restoration</msp:Title>
(17)     </wsen:Items>
(18)    </wsen:PullResponse>
(19)   </env:Body>
(20)  </env:Envelope>

Lines 0305 This value for the Action element indicates that the message is a PullResponse message.

Line 06 Other SOAP header elements, such as addressing and security information, are omitted for brevity.

Lines 1012 An updated enumeration context is returned with additional information to support processing of subsequent Pull messages. In this example, the application-specific enumeration context includes an additional attribute indicating the value of the last item returned.

Lines 1317 The first three items in the enumeration context are returned.

Because there was no explicit indicator that the entire list has been returned in the previous PullResponse message (the EndOfSequence element), another Pull message is sent:

Pull (version 2)
(01)  <env:Envelope>
(02)   <env:Header>...</env:Header>
(03)   <env:Body>
(04)    <wsen:Pull>
(05)     <wsen:EnumerationContext>
(06)      <msp:ContextID last="Canvas Restoration">12345</msp:ContextID>
(07)     </wsen:EnumerationContext>
(08)     ...
(09)    </wsen:Pull>
(10)   </env:Body>
(11)  </env:Envelope>

Lines 0507 The updated enumeration context is used in the next call to the service.

When the second PullResponse message is returned, additional items are included, along with a specific indication that the entire set of items has been traversed:

PullResponse (version 2)
(01)  <env:Envelope>
(02)   <env:Header>...</env:Header>
(03)   <env:Body>
(04)    <wsen:PullResponse>
(05)     <wsen:EnumerationContext>
(06)      <msp:ContextID last="Oil and Watercolor">12345</msp:ContextID>
(07)     </wsen:EnumerationContext>
(08)     <wsen:Items>
(09)      <msp:Title ISBN="...">Oil and Watercolor</msp:Title>
(10)     </wsen:Items>
(11)     <EndOfSequence/>
(12)    </wsen:PullResponse>
(13)   </env:Body>
(14)  </env:Envelope>

Lines 0507 Another updated enumeration context is returned.

Line 11 The presence of the EndOfSequence element indicates that no additional items are available in the enumeration. The use of the same enumeration context in future messages will produce a protocol error.

Another possible scenario is that the client does not have a need to finish traversing the list of items in the enumeration context. In this case, a well-behaved client will explicitly release the enumeration context prior to its expiration.

Release
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/09/enumeration/Release
(05)    </wsa:Action>
(06)    ...
(07)   </env:Header>
(08)   <env:Body>
(09)    <wsen:Release>
(10)     <wsen:EnumerationContext>
(11)      <msp:ContextID>12345</msp:ContextID>
(12)     </wsen:EnumerationContext>
(13)    </wsen:Release>
(14)   </env:Body>
(15)  </env:Envelope>

Lines 0305 This value for the Action element indicates that the message is a Release message.

Lines 1012 The enumeration context to be released is communicated. This is an indication that the enumeration service can abandon the enumeration context prior to expiration and reclaim any resources that were allocated for it.

The ReleaseResponse message is simply an acknowledgement that the Release message was received and processed. As shown here, it has an empty message body:

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

Lines 0305 This value for the Action element indicates that the message is a ReleaseResponse message.

The enumeration service also is provided with a mechanism to end an enumeration context before it expires. This may be for any reason, such as a lack of resources or an unexpected server shutdown. A well-behaved service will attempt to send the EnumerationEnd message to its clients.

EnumerationEnd
(01)  <env:Envelope>
(02)   <env:Header>
(03)    <wsa:Action>
(04)     http://schemas.xmlsoap.org/ws/2004/09/enumeration/EnumerationEnd
(05)    </wsa:Action>
(06)    ...
(07)  </env:Header>
(08)  <env:Body>
(09)    <wsen:EnumerationContext>
(10)     <msp:ContextID>12345</msp:ContextID>
(11)    </wsen:EnumerationContext>
(12)    <wsen:Code>wsen:SourceCanceling</wsen:Code>
(13)    <wsen:Reason xml:lang="us-en">Too busy</wsen:Reason>
(14)   </env:Body>
(15)  </env:Envelope>

Lines 0305 This value for the Action element indicates that the message is an Enumeration-End message.

Lines 0911 The enumeration context that is being ended is communicated to the client.

Line 12 The reason code for the enumeration to be ended is provided. For this message, the source is canceling the enumeration for a reason other than shutdown. A shutdown reason would include the wsen:SourceShuttingDown value instead.

Line 13 The reason code provides additional human-readable information about why the enumeration context was cancelled. In this case, the server was too busy to continue to maintain the enumeration context. Any number of Reason elements can be included in order to support multiple languages.