<abstract>This specification defines an XMPP extension that enables a requesting entity to receive a large data set only if the set has changed; the primary use case is sequencing of roster changes for more efficient downloading of the roster information.</abstract>
<remark><p>Defined protocol solely in terms of full rosters and roster pushes (no more roster diffs); added implementation notes; clarified server behavior if cached version is unavailable.</p></remark>
<remark><p>Initial published version; per Council consensus, removed optionality regarding semantics of the version attribute.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-03-05</date>
<initials>psa</initials>
<remark><p>Corrected semantics of version attribute (should be a strictly increasing sequence number but may be any unique identifier).</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-03-04</date>
<initials>psa</initials>
<remark><p>Clarified description of roster diff; added diff attribute and specified its use in roster results; specified use of version attribute in roster pushes.</p></remark>
<p>Certain XMPP technologies can return large data sets to users (examples are rosters as specified in &xmppim; and item lists as specified in &xep0030;). Although &xep0059; provides a generic way to page through such data sets, it does not provide a way to learn if the data set has changed since it was last retrieved. If the client could cache the data set (e.g., the roster) and retrieve only changes to the data set, certain use cases (e.g., the login process) could be significantly streamlined. This feature might be especially valuable over low-bandwidth connections such as those common in mobile environments. This document defines a method for such streamlining, via the concept of data sequencing.</p>
<p>This document defines a <seq/> element qualified by the 'urn:xmpp:tmp:seq' namespace &NSNOTE;. This element can be included in any IQ request that might result in a large data set. Because only one child element is allowed in an IQ stanza, the <seq/> element MUST be included as a child of the payload element (i.e., as a grandchild of the IQ stanza).</p>
<p>The <seq/> element is defined as empty (except when used to advertise a <linkurl='#support-stream'>stream feature</link>). It possesses a single attribute: 'num'.</p>
<p>The value of the 'num' attribute MUST be a non-negative integer representing a strictly increasing sequence number that is increased (but not necessarily incremented-by-one) with any change to the data set.</p>
</section1>
<section1topic='Use With Rosters'anchor='roster'>
<section2topic='Roster Get'anchor='roster-get'>
<p>If a client supports data sequencing and knows that the server does so (see <linkurl='#support'>Determining Support</link>), it SHOULD include the <seq/> element in its request for the roster, where the 'num' attribute is set to the sequence number associated with its last cache of the roster.</p>
<p>If the client has not yet cached the roster or the cache is lost or corrupted, but the client wishes to bootstrap the use of data sequencing, it SHOULD include the <seq/> element with the 'num' attribute set to a value of zero (0).</p>
<p>Naturally, if the client does not support data sequencing or does not wish to bootstrap use of data sequencing, it will behave like an RFC-3921-compliant client by not including the <seq/> element.</p>
<section2topic='Roster Has Changed'anchor='roster-changed'>
<p>If the roster has changed since the version enumerated by the client, the server MUST return a &QUERY; element that includes the latest sequence number.</p>
<p>The &QUERY; element MUST either contain the complete roster (including the sequence number to indicate that the roster has changed) or be empty (indicating that roster changes will be sent as interim roster pushes).</p>
<p>In general, if returning the complete roster would use less bandwidth than sending individual roster pushes to the client (e.g., if the roster contains only a few items), the server SHOULD return the complete roster.</p>
<p>However, if returning the complete roster would use more bandwidth than sending individual roster pushes to the client (e.g., if the roster contains many items, only a few of which have changed), the server SHOULD return an empty &QUERY; element, then send individual roster pushes.</p>
<li>Imagine that the client had an active presence session for the entire time between its cached roster version (in this case, 305) and the new roster version (317).</li>
<li>During that time, the client might have received roster pushes related to data sequence numbers 306, 307, 310, 311, 313, 314, 315, and 317 (the sequence numbers must be strictly increasing but there is no requirement that the sequence shall be continuous).</li>
<li>However, some of those roster pushes might have contained intermediate updates to the same roster item (e.g., changes in the subscription state for bill@shakespeare.lit from "none" to "to" and from "to" to "both").</li>
<li>The interim roster pushes would not include all of the intermediate steps, only the final result of all changes applied while the client was in fact offline.</li>
<p>The client can determine when the interim roster pushes have ended by comparing the sequence number it received on the empty &QUERY; element against the sequence number it receives in roster pushes.</p>
<p>When the server sends subsequent roster pushes to the client, it MUST include the updated data sequence number. Roster pushes MUST occur in sequence order. The sequence number contained in a roster push MUST be unique. A "change to the roster" is any addition of, update to, or removal of a roster item that would result in a roster push, including changes in subscription states, as described in <cite>RFC 3921</cite> or <cite>rfc3921bis</cite>.</p>
<section1topic='Use With Service Discovery'anchor='disco'>
<section2topic='Items Request'anchor='disco-get'>
<p>If the requesting supports data sequencing and knows that another entity does so (see <linkurl='#support'>Determining Support</link>), it MAY include the <seq/> element in its disco#items request, where the 'num' attribute is set to the sequence number associated with its last cache of the items.</p>
<examplecaption="Items request with sequence number"><![CDATA[
<p>As above, if the requesting entity has not yet cached the data set (or the cache is lost or corrupted) but wishes to bootstrap the use of data sequencing, it SHOULD include the <seq/> element with the 'num' attribute set to a value of zero (0).</p>
</section2>
<section2topic='Disco Items Are Unchanged'anchor='disco-unchanged'>
<p>If the set of disco items has not changed since the version enumerated by the requesting entity, the responding entity MUST return an empty IQ-result.</p>
<examplecaption="Disco items result (unchanged)"><![CDATA[
<iqfrom='chat.shakespeare.lit'
id='r1'
to='bill@shakespeare.lit/globe'
type='result'/>
]]></example>
</section2>
<section2topic='Disco Items Have Changed'anchor='disco-changed'>
<p>If the set of disco items has changed since the version enumerated by the client, the server MUST return a &QUERY; element that includes the latest sequence number.</p>
<p>The &QUERY; element MUST either contain the complete set of items (including the sequence number to indicate that the set has changed) or be empty (indicating that changes will be sent as notifications as specified in &xep0230;).</p>
<p>In general, if returning the complete set of items would use less bandwidth than sending individual notifications (e.g., if the set contains only a few items), the server SHOULD return the complete set.</p>
<examplecaption="Disco items result with complete set"><