0.9

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3074 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0237.xml

@@ -22,9 +22,15 @@
   <supersededby/>
   <shortname>N/A</shortname>
   &stpeter;
+  <revision>
+    <version>0.9</version>
+    <date>2009-04-22</date>
+    <initials>psa</initials>
+    <remark><p>Further clarified several implementation notes.</p></remark>
+  </revision>
   <revision>
     <version>0.8</version>
-    <date>2009-04-10</date>
+    <date>2009-04-20</date>
     <initials>psa</initials>
     <remark><p>Defined schema for stream feature; adjusted some wording for improved clarity.</p></remark>
   </revision>
@@ -99,8 +105,9 @@
 <section1 topic='Protocol' anchor='proto'>
   <section2 topic='Data Format' anchor='format'>
     <p>This document adds a new 'ver' attribute to the &QUERY; element qualified by the 'jabber:iq:roster' namespace, defined as follows.</p>
-    <p class='def'><strong>Definition:</strong> The 'ver' attribute is a strictly increasing sequence number that is increased (but not necessarily incremented-by-one) with any modification to the roster data. The value of the attribute MUST be a non-negative 64-bit integer, MUST be changed only by the server, and MUST be treated by the client as opaque. The server MUST ensure that each change to the roster data will result in a different sequence number and that the sequence number associated with a given roster modification will be greater than the sequence number associated with any previous roster modification. (Note: This rule effectively disallows the use of the system clock as a sequence number, since if the system time changes, e.g. because of an adjustment based on an NTP update (see &rfc0958;), the next generated value might be less than the previous one.)</p>
+    <p class='def'><strong>Definition:</strong> The <strong>'ver' attribute</strong> is a strictly increasing sequence number that is increased (but not necessarily incremented-by-one) with any modification to the roster data. The value of the attribute MUST be a non-negative 64-bit integer, MUST be changed only by the server, and MUST be treated by the client as opaque. The server MUST ensure that each change to the roster data will result in a different sequence number and that the sequence number associated with a given roster modification will be greater than the sequence number associated with any previous roster modification for this session.</p>
-    <p>For purposes of this specification, a "roster modification" is any change to the roster data that would result in a roster push to a connected client. Therefore internal states related to roster processing within the server that do not result in a roster push do not necessitate a increase in the sequence number. If a series of roster modifications result in a roster item that does not differ from the version cached by the client (e.g., a change to the item's 'name' attribute and then a change back to the original value), the server MUST consider the item to have been changed and MUST send the item to the client (typically via a roster push).</p>
+    <p>An XMPP server cannot guarantee that a timestamp will be strictly increasing (e.g., the system time might change because of an adjustment based on an update triggered by the user of the Network Time Protocol (&rfc0958;); therefore, because the 'ver' attribute is defined as a strictly increasing sequence number, server implementations are advised to employ a method other than timestamps for generation of the 'ver' attribute.</p>
+    <p class='def'><strong>Definition:</strong> A <strong>"roster modification"</strong> is any change to the roster data that would result in a roster push to a connected client. Therefore internal states related to roster processing within the server that would not result in a roster push do not necessitate a increase in the sequence number. If a series of roster modifications result in a roster item that does not differ from the version cached by the client (e.g., a change to the item's 'name' attribute and then a change back to the original value), the server MUST consider the item to have been modified and therefore MUST send the item to the client (typically via a roster push as described below).</p>
   </section2>
   <section2 topic='Client Request' anchor='request'>
     <p>If a client supports roster versioning, it SHOULD include the 'ver' element in its request for the roster, where the 'ver' attribute is set to the sequence number associated with its last cache of the roster.</p>
@@ -113,7 +120,7 @@ C: <iq from='romeo@montague.lit/home' id='r1h3vzp7' to='romeo@montague.lit' type
     <p>Naturally, if the client does not support roster versioning or does not wish to bootstrap the use of roster versioning, it will behave like an RFC-3921-compliant client by not including the 'ver' attribute.</p>
   </section2>
   <section2 topic='Server Response' anchor='response-result'>
-    <p>Whether or not the roster has changed since the version enumerated by the client, the server MUST either return the complete roster as described in RFC 3921 or return an empty IQ-result (thus indicating that any roster modifications will be sent via roster pushes, as described below). In general, unless 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 send an empty IQ-result and then send the modifications (if any) via roster pushes.</p>
+    <p>Whether or not the roster has changed since the version enumerated by the client, the server MUST either return the complete roster as described in RFC 3921 or return an empty IQ-result (thus indicating that any roster modifications will be sent via roster pushes, as described below). In general, unless 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 send an empty IQ-result and then send the modifications (if any) via roster pushes. In addition, if the client signals a sequence number that is greater than the sequence number currently on file at the server for that JID, the server MUST return the whole current roster as if client announced its version to be zero, thus bootstrapping the client's local cache.</p>
     <example caption="Empty roster result"><![CDATA[
 S: <iq from='romeo@montague.lit' id='r1h3vzp7' to='romeo@montague.lit/home' type='result'/>
     ]]></example>
@@ -280,7 +287,7 @@ S: <iq from='romeo@montague.lit' id='dh361f35' to='romeo@montague.lit/home' type
 </section1>
 
 <section1 topic='Acknowledgements' anchor='ack'>
-  <p>Thanks to Dave Cridland, Richard Dobson, Leonid Evdokimov, Fabio Forno, Alexander Gnauck, Juha Hartikainen, Joe Hildebrand, Justin Karneges, Sachin Khandelwal, Curtis King, Pedro Melo, Matthew Wild, and Jiří Zárevúcký for their comments. The definition of a sequence number borrows concepts and text from &rfc4551;</p>
+  <p>Thanks to Dave Cridland, Richard Dobson, Leonid Evdokimov, Fabio Forno, Alexander Gnauck, Juha Hartikainen, Joe Hildebrand, Justin Karneges, Sachin Khandelwal, Curtis King, Pedro Melo, Matthew Wild, and Jiří Zárevúcký for their comments. The definition of a sequence number borrows some concepts from the definition of the CONDSTORE extension to IMAP as provided in &rfc4551;</p>
 </section1>
 
 </xep>