1.10pre9

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

xep-0060.xml

@@ -49,8 +49,8 @@
   &ralphm;
 
   <revision>
-    <version>1.10pre8</version>
-    <date>in progress, last updated 2007-08-24</date>
+    <version>1.10pre9</version>
+    <date>in progress, last updated 2007-09-12</date>
     <initials>psa</initials>
     <remark>
       <ul>
@@ -62,6 +62,8 @@
         <li>Defined member affiliation to properly implement whitelist feature</li>
         <li>Split several long sections into smaller sub-sections.</li>
         <li>Clarified that a pubsub service must generate an ItemID if the publisher does not provide one.</li>
+        <li>Specified recommended ItemID for singleton nodes.</li>
+        <li>Summarized triggers for sending notifications.</li>
       </ul>
     </remark>
   </revision>
@@ -288,7 +290,7 @@
   <section2 topic='Overview' anchor='intro-overview'>
     <p>As Jabber/XMPP technologies have matured, the need for a generic publish-subscribe ("pubsub") mechanism has arisen in a number of domains. These include (but are not limited to): news feeds and content syndication, extended presence, avatar management, shared bookmarks, auction and trading systems, online catalogs, workflow systems, network management systems, NNTP gateways, profile management, and event notification.</p>
     <p>In all of these domains, it is desirable for data communication to follow the classic "publish-subscribe" or "observer" design pattern: a person or application publishes information, and an event notification (without or without payload) is broadcasted to all authorized subscribers. In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts event notifications to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. In most pubsub services, the focal point for publication and subscription is a "topic" or "node" to which publishers send data and from which subscribers receive notifications. Additionally, some nodes may also maintain a history of events and provide other services that supplement the pure pubsub model.</p>
-    <p>This document defines a single, cohesive, generic protocol that all forms of pubsub can use. While compliant implementations are not required to implement all of the features defined herein, this document addresses most use cases that may be requested of a pubsub service. (For information about which features are required and which are recommended or optional, consult the <link url='#features'>Feature Summary</link>.) Other specifications may define "subsets" or "profiles" of publish-subscribe for use in specialized contexts (e.g., &xep0163;), but such profiles are out of scope for this document.</p>
+    <p>This document defines a single, cohesive, generic protocol that all forms of pubsub can use. While compliant implementations are not required to implement all of the features defined herein, this document addresses most use cases that may be requested of a pubsub service. (For information about which features are required and which are recommended or optional, consult the <link url='#features'>Feature Summary</link>.) Other specifications may define "subsets" or "profiles" of publish-subscribe for use in specialized contexts, but such profiles are out of scope for this document.</p>
   </section2>
   <section2 topic='How It Works' anchor='intro-howitworks'>
     <p>This specification is large. However, the basic idea behind pubsub is rather simple (see <link url='#publisher-publish'>Publish an Item to a Node</link>):</p>
@@ -2326,7 +2328,7 @@ And by opposing end them?
     to='hamlet@denmark.lit/blogbot'
     id='publish1'/>
       ]]></example>
-      <p>The pubsub service MUST send then one &MESSAGE; stanza containing a pubsub event notification to each approved subscriber. Each &MESSAGE; stanza generated by a pubsub service SHOULD possess an 'id' attribute with a unique value so that the service can properly track any notification-related errors that may occur (see the <link url='#impl-errors'>Handling Notification-Related Errors</link> section of this document). Depending on the node configuration, the event notification either will or will not contain the payload, as shown below.</p>
+      <p>The pubsub service MUST send then one &MESSAGE; stanza containing a pubsub event notification to each entity that meets the criteria for receiving a notification (typically to each approved subscriber, although there are other contexts in which an entity may receive a notification as summarized under <link url='#impl-notify'>Notification Triggers</link>). Each &MESSAGE; stanza generated by a pubsub service SHOULD possess an 'id' attribute with a unique value so that the service can properly track any notification-related errors that may occur (see the <link url='#impl-errors'>Handling Notification-Related Errors</link> section of this document). Depending on the node configuration, the event notification either will or will not contain the payload, as shown below.</p>
       <p>Note: In order to facilitate authorization for item removal as described in the <link url='#publisher-delete'>Delete an Item from a Node</link> section of this document, implementations that support persistent items SHOULD store the item (if the node is so configured) and maintain a record of the publisher.</p>
       <section4 topic='Notification With Payload' anchor='publisher-publish-success-withpayload'>
         <p>If the node is configured to include payloads, the subscribers will receive payloads with the event notifications.</p>
@@ -5326,6 +5328,18 @@ And by opposing end them?
 
 <section1 topic='Implementation Notes' anchor='impl'>
 
+  <section2 topic='Notification Triggers' anchor='impl-notify'>
+    <p>There are many possible triggers for sending a notification to an entity for the currently published item or the last published item, as summarized below:</p>
+    <ol>
+      <li>The entity has explicitly requested one or more items from the node and is authorized to retrieve items.</li>
+      <li>The entity is an authorized subscriber to the node; The publisher sends a publish request, the service sends the currently published item to the entity.</li>
+      <li>The entity is not subscribed but is eligible to do so and has sent presence (potentially containing appropriate entity capabilities data) to a node that is presence-enabled; when the publisher sends a publish request, the service sends the currently published item to the entity.</li>
+      <li>The entity is not subscribed but is eligible to do so and sends presence (potentially containing appropriate entity capabilities data) to a node that is presence-enabled; as a result, the service sends the last published item to the entity.</li>
+      <li>The entity gains access to the node because of a change to the node access model; as a result, the service sends the last published item to the entity.</li>
+      <li>The entity is added to the roster group associated with a node access model of "roster"; as a result, the service sends the last published item to the entity.</li>
+    </ol>
+  </section2>
+
   <section2 topic='Intended Recipients for Notifications' anchor='impl-recipients'>
     <p>When a pubsub service generates notifications, it MUST adhere to the delivery rules implicit in the subscription option configuration for each subscriber. In particular, the 'to' address SHOULD be that of the subscribed JID only. The service SHOULD NOT attempt to guess at the most available resource associated with the subscribed JID (e.g., in the context of instant messaging systems).</p>
   </section2>
@@ -5775,6 +5789,9 @@ O, what a rogue and peasant slave am I!
 </message>
     ]]></example>
   </section2>
+  <section2 topic='Singleton Nodes' anchor='impl-singleton'>
+    <p>For some nodes where the NodeID is an XML namespace (e.g., as used in <cite>XEP-0163</cite>), it is desirable to have at most one item associated with the node at any one time (for example, a client may want to store its preferences using a node name that is a namespace controlled by that client). When this pattern is desired, it is RECOMMENDE for the publisher to specify an ItemID of "SINGLETON" to ensure that the publication of a new item will overwrite the existing item.</p>
+  </section2>
 </section1>
 
 <section1 topic='Internationalization Considerations' anchor='i18n'>