[PubSub] versioning

[Peter Saint-Andre]

I've added text about the 'ver' attribute to XEP-0060. It's perhaps a
bit underspecified right now. Feedback welcome. See also:

http://xmpp.org/extensions/tmp/xep-0060-1.13.html

######

7.1.2.4 Item Versioning

If configured to do so (via the "pubsub#versioning" configuration
field), the service can include the "version" of the published data when
it generates notifications.

Example 105. Service Notifies Subscribers

<message from='pubsub.shakespeare.lit' to='franci...@denmark.lit' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='princely_musings'
           ver='some-version-string'>
      <item id='ae890ac52d0df67ed7cfdf51b644e901'
            publisher='ham...@denmark.lit'>
        [ ... ENTRY ... ]
      </item>
    </items>
  </event>
</message>


Definition: The 'ver' attribute is a string that identifies a particular
version of the data published at a node. The value MUST be generated
only by the server and MUST be treated by the client as opaque. The
server can use any appropriate method for generating the version ID,
such as a hash of the published data (e.g., of all the current items
cached at the node) or a strictly-increasing sequence number.

Note: The value of the 'ver' attribute is conceptually equivalent to the
'ver' attribute from Roster Sequencing [22].

The value of the 'ver' attribute MUST be generated by the service, not
accepted by the service in the published item.

The combination of the ItemID and 'ver' MUST be unique, such that a
subsequent publish with the same ItemID MUST have a different value of
the 'ver' attribute than the earlier published item.

######

6.5.9 Requesting All Items Since a Given Version

The subscriber can request all items published since a particular
version of the published data by specifying the Node ID and 'ver'
attribute (about which see Item Versioning).

Example 87. Subscriber requests items since a given version

<iq type='get'
    from='franci...@denmark.lit/barracks'
    to='pubsub.shakespeare.lit'
    id='items3'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='princely_musings'
           ver='some-version-string'/>
  </pubsub>
</iq>


The service would then return all the items published since that version
of the data published at the node.

######


  <field var='pubsub#versioning'
         type='boolean'
         label='Provide versioning information about published items'>
    <value>0</value>
  </field>

######

  <xs:element name='items'>
    <xs:complexType>
      <xs:choice>
        <xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='retract' minOccurs='0' maxOccurs='unbounded'/>
      </xs:choice>
      <xs:attribute name='node' type='xs:string' use='required'/>
      <xs:attribute name='ver' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='item'>
    <xs:complexType>
      <xs:choice minOccurs='0'>
        <xs:any namespace='##other'/>
      </xs:choice>
      <xs:attribute name='id' type='xs:string' use='optional'/>
      <xs:attribute name='node' type='xs:string' use='optional'/>
      <xs:attribute name='publisher' type='xs:string' use='optional'/>
      <xs:attribute name='ver' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

######

smime.p7s
Description: S/MIME Cryptographic Signature