If a server supports entity versioning, it MUST inform the connecting client when returning stream features during the stream negotiation @@ -166,34 +165,34 @@ The entity versioning stream feature is merely informative and therefore is never mandatory-to-negotiate.
-- Version tokens are short case-sensitive strings which are generated by - the server. Their format is not defined in this spec, but a - recommendation may be found in the Implementation Notes. Version tokens - are akin to a weakly-validated etag for the entity in question. -
-- Servers that implement this protocol must assign such a version token to - each entity that is controlled by the server. The server MUST then update - this version every time any mutable property of the entity changes (eg. - when the subscription status of a user changes). The server MAY choose to - update this token at any time (to force the clients to invalidate their - cached representation fo the object). This version token MUST then be - included with every object representation of that entity sent down in the - stream. This is done by including a sub-node called "version" qualified - by the entity versioning XML namespace defined in this document. - Similarly, clients MAY also add version nodes for each version token they - possess to the request for a list (not specifying a version token will - force the server to send information on that entity to the client). If a - server sends up a list of version tokens, the server MUST then check to - see if those tokens correspond to any entity which it knows about, and - not send down any entities with matching version tokens in the response. -
-For example, a roster request might look like:
-+ Version tokens are short case-sensitive strings which are generated by the + server. Their format is not defined in this spec, but a recommendation may + be found in the Implementation Notes. Version + tokens are akin to a weakly-validated etag for the entity in question. +
++ Servers that implement this protocol must assign such a version token to + each entity that is controlled by the server. The server MUST then update + this version every time any mutable property of the entity changes (eg. + when the subscription status of a user changes). The server MAY choose to + update this token at any time (to force the clients to invalidate their + cached representation fo the object). This version token MUST then be + included with every object representation of that entity sent down in the + stream. This is done by including a sub-node called "version" qualified + by the entity versioning XML namespace defined in this document. + Similarly, clients MAY also add version nodes for each version token they + possess to the request for a list (not specifying a version token will + force the server to send information on that entity to the client). If a + server sends up a list of version tokens, the server MUST then check to + see if those tokens correspond to any entity which it knows about, and + not send down any entities with matching version tokens in the response. +
+For example, a roster request might look like:
+
- When a client syncs with the server and indicates that it has a version
- token in its cache that does not match any entity on the server (or when
- the server wants to remove an entity from the clients cache for any other
- reason), the server MUST reply with an empty <version/> node. When
- the client receives such an empty version node it SHOULD purge the entity
- from its cache. For example, the following exchange would trigger the
- removal of 'inverness@chat.shakespeare.lit' from the cached MUC list:
-
+ When a client syncs with the server and indicates that it has a version
+ token in its cache that does not match any entity on the server (or when
+ the server wants to remove an entity from the clients cache for any other
+ reason), the server MUST reply with an empty <version/> node. When
+ the client receives such an empty version node it SHOULD purge the entity
+ from its cache. For example, the following exchange would trigger the
+ removal of 'inverness@chat.shakespeare.lit' from the cached MUC list:
+
+
- If the client receives an indication that it should delete an item from a
- list by any other means (eg. via a roster push), it SHOULD remove the
- version token associated with that entity from its cache.
-
+ If the client receives an indication that it should delete an item from a + list by any other means (eg. via a roster push), it SHOULD remove the + version token associated with that entity from its cache. +
+While the version token approach to caching does not require a great deal of state to be stored on the client or the server, it does require a lot @@ -327,9 +327,11 @@ avoid sending the large request entirely). To do this, we can request an aggregate version token from the server. This aggregate token is calculated by constructing a string of comma separated "bare JID:version" pairs sorted - in byte-wise order, and taking the MD5 hash of the constructed string. For - example, if the server is calculating the aggregate version token for a - roster, it might end up with the following string: + in byte-wise order (because the JID:version pair is constructed before + sorting, if two items in the list have the same JID they can still be + sorted by the version token), and taking the MD5 hash of the constructed + string. For example, if the server is calculating the aggregate version + token for a roster, it might end up with the following string:
Similarly, to fetch the aggregate token for a list of MUC rooms, one would - query the MUC component directly: + query the MUC component directly with the type set to the 'disco#items' + namespace:
+ If an aggregate token is requested for a list that may contain more than + one type of entity (eg. MUC rooms and pubsub nodes that live on the same + component), then the server MUST return the aggregate token constructed + with the entire list (rooms and pubsub nodes). +
Clients are also NOT REQUIRED to check aggregate tokens. However, clients MAY wish to check aggregate tokens before making a roster or MUC request when the cached roster or MUC list is very large. When to check aggregate - tokens is left up to the clients. + tokens (if at all) is left up to the implementation.
-