All changes to be submitted by the Working Group Chair (or designee) after approval by the working group.
The Change Request sample (http://www.dmtf.org/members/zdata/CRTemplateSample.html) contains more detailed information on how to complete the template.
DMTF Change Request Number [sysdevCR006655] |
WIP-WSMAN-CR00006.001.htm |
CR Owner Name, Email [My Name, my.name@company.com] |
Bryan Murray, bryan.murray@hp.com |
Errata [Yes/No] |
No |
Short Description |
Enumeration results optimization |
Spec, Document or Model(s) Being Changed [Device Model] |
wsman-baseline-00 |
Spec, Document or Model Version Incorporating the Change [V2.9 Final] |
|
Filename(s) Incorporating the Change [Device_USB.mof] |
n/a |
Date Originated [mm/dd/yyyy] |
12/06/2005 |
Date of Last Revision of the Change Request [mm/dd/yyyy] |
12/21/2005 |
Dependencies [smwgCR00567,sysdevCR00555] |
n/a |
Terminology
The terminology used in this CR should conform to the "Rules for the structure and drafting of International Standards", 5th Edition, 2005 available at:
Particular attention shall be paid to Annex H which lays out guidelines for the expression of provisions.
Background/Rationale (Explanation of the background and reason(s) for the requested change, and supporting documentation):
Many enumerable resources are likely to have a small number of items to enumerate. The baseline WS-Management specification requires at least two roundtrip request/response message exchanges to retrieve any content (an Enumerate request and its response and a Pull request and its response). Optimizing the required message exchanges to a single request/response pair will help save network bandwidth and time.
Requested Change (Change information such as details before/after the change, readable/indented MOF, and/or references to "Uploaded" MOF and other documents if the changes are too lengthy to include inline):
Page 57, after last paragraph: Add the
following text:
In order to optimize the number of round-trip messages required to enumerate the items in an enumerable resource, a client MAY request optimized enumeration behavior. A client initiates an optimized enumeration by placing the wsman:OptimizeEnumeration element as child element of the wsen:Enumerate element, and can optionally include the wsman:MaxElements element.
(01) <wsman:OptimizeEnumeration/>
(02) <wsman:MaxElements>xs:positiveInteger</wsman:MaxElements>
?
The following describes additional, normative constraints on the outline listed above:
wsman:OptimizeEnumeration
The presence of this element as a
child of the wsen:Enumerate element indicates that the
client is requesting an optimized enumeration.
wsman:MaxElements
This optional element (of type xs:positiveInteger) indicates the number of items (child
elements of wsen:Items in the Enumerate response) the consumer is willing to
accept. When this element is absent, its implied value is 1. Implementations
MUST NOT return more than this number of elements in the Enumerate response
message. Implementations MAY return fewer than this number based on either the
wsman:OperationTimeout SOAP header,
wsman:MaxEnvelopeSize SOAP header, or implementation-specific constraints.
R5.2-6:
A conformant service MAY support enumeration optimization. If a service
receives the wsman:OptimizeEnumeration element in an
wsen:Enumerate message and it does not support enumeration optimization, it
SHOULD ignore the element and complete the enumeration request as described in
WS-Enumeration.
R5.2-7:
A conformant service receiving an wsen:Enumerate
message without the wsman:OptimizeEnumeration element MUST NOT return any
enumeration items in the wsen:EnumerateResponse message and MUST return an
wsen:EnumerationContext initialized to return the first items when the first
wsen:Pull message is received.
A service implementing the optimized enumeration will respond with the following additional content in an wsen:EnumerateResponse message if the wsen:Enumerate message includes wsman:OptimizeEnumeration:
(01) <wsman:Items>
(02)
<xs:any> enumeration-specific element </xs:any> *
(03) </wsman:Items> ?
(04) <wsman:EndOfSequence>
?
The following describes additional, normative constraints on the outline listed above:
wsman:Items/any
The optional Items element contains
one or more enumeration-specific elements, one for each element being returned.
The service will return no more than wsman:MaxElements
elements in this list if wsman:MaxElements is specified in the request message.
wsman:EndOfSequence
This optional element indicates that
no more elements are available from this enumeration. Additionally, if this
element is returned in a wsen:EnumerateResponse
message, subsequent Pull requests using that enumeration context SHOULD
generate a wsen:InvalidEnumerationContext fault message; in any case, they MUST
NOT return a valid wsen:PullResponse.
R5.2-8:
A conformant service that supports optimized enumeration and is responding with
an wsen:EnumerateResponse message MUST include either or
both the wsman:Items or wsman:EndOfSequence elements in the response as an
indication to the client that the optimized enumeration request was understood
and honored. If neither wsman:Items nor
wsman:EndOfSequence is in the wsman:EnumerateResponse message, the client can
continue to use the enumeration message exchanges as they are defined in
WS-Enumeration.
R5.2-9:
A conformant service that supports optimized enumeration and has not returned
all items of the enumeration sequence in the wsen:EnumerateResponse message
MUST return an wsen:EnumerationContext that is initialized such that a
subsequent wsen:Pull message will return the set of items after those returned
in the wsen:EnumerateResponse. If all items of the enumeration sequence have
been returned in the wsen:EnumerateResponse message,
the service SHOULD return an empty wsen:EnumerationContext element and MUST
return the wsen:EndOfSequence element in the response.
A client that has requested optimized enumeration can determine if this request was understood and honored by the service by examining the response message. An wsen:EnumerateResponse message with optimized enumeration will include either or both the wsman:Items and wsman:EndOfSequence elements.
Page 148, after EnumerationMode
element: Add the following text:
<xs:element name=”OptimizeEnumeration”/>
<xs:element name=”MaxElements” type=”xs:positiveInteger”/>
<xs:element name=”Items” type=”wsen:ItemListType”/>
<xs:element name=”EndOfSequence”/>
Discussion Points (Summary of decisions and discussions of the WG in creating this CR) :
The result of this change is that many Enumerate message exchanges will be able to obtain an entire set of items from an enumerable resource using a single message exchange rather than needing to use two roundtrip message exchanges.
Change History (Mandatory after submission to the TC, May be used by the WGs):
Version |
Date |
Short description of changes |
0 |
12/07/2005 |
Initial CR |
1 |
12/21/2005 |
Incorporate feedback from Dec 2006 f2f |
Note that this document is labeled as "DMTF Confidential". It is intended only for DMTF member companies and alliance partners. This Change Request may be withdrawn or modified by subsequent Change Requests.
All submissions MUST comply with the DMTF Patent and Technology policy (http://www.dmtf.org/about/policies/patent-10-18-01.pdf)
Template Sample Version 2.0.0c.