git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3701 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2009-12-07 21:18:46 +00:00
parent 5a23155264
commit eec8632379
1 changed files with 33 additions and 33 deletions

View File

@ -51,8 +51,8 @@
&ralphm;
<revision>
<version>1.13rc11</version>
<date>in progress, 2009-12-03</date>
<version>1.13rc12</version>
<date>in progress, 2009-12-07</date>
<initials>psa</initials>
<remark>
<ul>
@ -345,14 +345,14 @@
<section1 topic='Introduction' anchor='intro'>
<section2 topic='Overview' anchor='intro-overview'>
<p>The XMPP publish-subscribe extension defined in this document provides a framework for a wide variety of applications, including news feeds, content syndication, extended presence, geolocation, avatar management, shared bookmarks, auction and trading systems, workflow systems, network management systems, NNTP gateways, profile management, and any other application that requires event notifications.</p>
<p>This technology uses the classic "publish-subscribe" or "observer" design pattern: a person or application publishes information, and an event notification (with 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. The focal point for publication and subscription is a "node" to which publishers send data and from which subscribers receive notifications. Nodes can also maintain a history of events and provide other services that supplement the pure pubsub model.</p>
<p>This technology uses the classic "publish-subscribe" or "observer" design pattern: a person or application publishes information, and an event notification (with 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. The focal point for publication and subscription is a "node" to which publishers send data and from which subscribers receive event notifications. Nodes can also maintain a history of events and provide other services that supplement the pure pubsub model.</p>
<p>This document defines a generic protocol that all pubsub applications can use. Compliant implementations are not required to implement all of the features defined here (see 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>Although this specification is large because it defines many side use cases and possible error flows, the basic idea is simple:</p>
<ol>
<li>An entity publishes information to a node at a publish-subscribe service.</li>
<li>The pubsub service pushes a notification to all entities that are authorized to learn about the published information.</li>
<li>The pubsub service pushes an event notification to all entities that are authorized to learn about the published information.</li>
</ol>
<p>Perhaps the most popular application of pubsub-like functionality is content syndication, which has become familiar from the RSS and Atom (&rfc4287;) feeds associated with weblogs, news sites, and other frequently-updated information available on the Internet. Consider the example of a weblog published by &lt;hamlet@denmark.lit&gt;. When Hamlet writes a new weblog entry, his blogging software publishes the entry to a pubsub node hosted at &lt;pubsub.shakespeare.lit&gt;:</p>
<example caption='Publisher Publishes a New Weblog Entry'><![CDATA[
@ -426,7 +426,7 @@ And by opposing end them?
</event>
</message>
]]></example>
<p>Here is an even simpler example: a transient node that sends only notifications without a payload:</p>
<p>Here is an even simpler example: a transient node that sends only event notifications without a payload:</p>
<example caption='A Transient Notification'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
@ -434,7 +434,7 @@ And by opposing end them?
</event>
</message>
]]></example>
<p>Naturally, the entities involved may need to complete other use cases in order to enable full pubsub functionality -- for example, the publisher may need to create the node (see <link url='#owner-create'>Create a Node</link>) and subscribers may need to sign up for notifications (see <link url='#subscriber-subscribe'>Subscribe to a Node</link>). These use cases are fully described in the remainder of this document. (For information about which features are required and which are recommended or optional, consult the <link url='#features'>Feature Summary</link>.)</p>
<p>Naturally, the entities involved may need to complete other use cases in order to enable full pubsub functionality -- for example, the publisher may need to create the node (see <link url='#owner-create'>Create a Node</link>) and subscribers may need to sign up for event notifications (see <link url='#subscriber-subscribe'>Subscribe to a Node</link>). These use cases are fully described in the remainder of this document. (For information about which features are required and which are recommended or optional, consult the <link url='#features'>Feature Summary</link>.)</p>
</section2>
</section1>
@ -457,7 +457,7 @@ And by opposing end them?
<di><dt>Owner</dt><dd>The manager of a node, of which there may be more than one; often but not necessarily the node creator.</dd></di>
<di><dt>Payload</dt><dd>The full data associated with an event rather than just the event notification itself.</dd></di>
<di><dt>Open Access Model</dt><dd>A node access model under which any entity may subscribe and retrieve items without approval.</dd></di>
<di><dt>Payload</dt><dd>The XML data that is contained within the &lt;item/&gt; element of a publication request or a notification event. A given payload is defined by an XML namespace and associated schema. A document that defines a payload format SHOULD specify whether the payload can be used only for a NodeID whose value is the same as the XML namespace, or whether the payload can be used for any NodeID. Such a document also SHOULD specify whether it is suggested that node at which such payloads are published are best configured as <link url='#impl-singleton'>Singleton Nodes</link>.</dd></di>
<di><dt>Payload</dt><dd>The XML data that is contained within the &lt;item/&gt; element of a publication request or an event notification. A given payload is defined by an XML namespace and associated schema. A document that defines a payload format SHOULD specify whether the payload can be used only for a NodeID whose value is the same as the XML namespace, or whether the payload can be used for any NodeID. Such a document also SHOULD specify whether it is suggested that node at which such payloads are published are best configured as <link url='#impl-singleton'>Singleton Nodes</link>.</dd></di>
<di><dt>Personal Eventing</dt><dd>A simplified subset of Publish-Subscribe for use in the context of instant messaging and presence applications, whereby each IM user's JID is a virtual pubsub service; for details, see &xep0163;.</dd></di>
<di><dt>Presence Access Model</dt><dd>A node access model under which any entity that is subscribed to the owner's presence with a subscription of type "from" or "both" (see &rfc3921;) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.</dd></di>
<di><dt>Publisher</dt><dd>An entity that is allowed to publish items to a node.</dd></di>
@ -654,22 +654,22 @@ And by opposing end them?
</section2>
<section2 topic='Event Types' anchor='events'>
<p>The requirements for the publish-subscribe protocol imply that there are two major dimensions along which we can measure events: persistent vs. transient, and pure notification vs. inclusion of payload. An implementation SHOULD enable an owner to configure a node along both of these dimensions.</p>
<p>The requirements for the publish-subscribe protocol imply that there are two major dimensions along which we can measure events: persistent vs. transient, and pure event notification vs. inclusion of payload. An implementation SHOULD enable an owner to configure a node along both of these dimensions.</p>
<p>No matter whether a node is configured for persistent or transient events, a service MAY cache the last item published to the node, in which case it SHOULD send that item to subscribers based on configuration of the "send_last_published_item" option (see the <link url='#impl-caching'>Item Caching</link> section of this document); if the service supports the "http://jabber.org/protocol/pubsub#last-published" feature then the value of this option MUST default to "on_sub_and_presence" (though the service SHOULD allow the node owner to override the default).</p>
<p class='box'>Note: The "on_sub_and_presence" setting relates to the <em>subscriber's</em> presence, not the publisher's presence.</p>
<p>A pubsub service MUST validate publish requests against the configuration of the node along both of these dimensions (see the <link url='#publisher-publish'>Publish An Item to a Node</link> section of this document for the relevant error conditions).</p>
<p>The node configuration and desired event type determine whether an item must be provided by the publisher, whether the item includes a payload in the publish request or notification, and whether an item ID is provided by the publisher or generated by the pubsub service. We can summarize the relevant rules as follows:</p>
<p>The node configuration and desired event type determine whether an item must be provided by the publisher, whether the item includes a payload in the publish request or event notification, and whether an item ID is provided by the publisher or generated by the pubsub service. We can summarize the relevant rules as follows:</p>
<table caption='Items, Payloads, and Item IDs'>
<tr><th>&#160;</th><th>Notification-Only Node *</th><th>Payload-Included Node *</th></tr>
<tr>
<td><strong>Persistent Node **</strong></td>
<td>Publish request MUST include an &ITEM; element, which MAY be empty or MAY contain a payload; even if publish request contains a payload, pubsub service MUST NOT include the payload in notifications; if publish request did not include item ID, pubsub service MUST generate item ID</td>
<td>Publish request MUST include an &ITEM; element, which SHOULD contain a payload; if publish request included a payload, notifications MUST include the payload; if publish request did not include item ID, pubsub service MUST generate item ID</td>
<td>Publish request MUST include an &ITEM; element, which MAY be empty or MAY contain a payload; even if publish request contains a payload, pubsub service MUST NOT include the payload in event notifications; if publish request did not include item ID, pubsub service MUST generate item ID</td>
<td>Publish request MUST include an &ITEM; element, which SHOULD contain a payload; if publish request included a payload, event notifications MUST include the payload; if publish request did not include item ID, pubsub service MUST generate item ID</td>
</tr>
<tr>
<td><strong>Transient Node **</strong></td>
<td>Publish request MUST NOT include an &ITEM; element; payload is not included in publish request or notifications, although notifications MUST include an empty &ITEMS; element; item ID is neither provided in publish request nor generated by pubsub service</td>
<td>Publish request MUST include an &ITEM; element, which SHOULD contain a payload; if publish request included a payload, notifications MUST include the payload; pubsub service MAY generate an item ID</td>
<td>Publish request MUST NOT include an &ITEM; element; payload is not included in publish request or event notifications, although event notifications MUST include an empty &ITEMS; element; item ID is neither provided in publish request nor generated by pubsub service</td>
<td>Publish request MUST include an &ITEM; element, which SHOULD contain a payload; if publish request included a payload, event notifications MUST include the payload; pubsub service MAY generate an item ID</td>
</tr>
</table>
<p>* Note: Whether the node is notification-only or includes payloads is determined by the "pubsub#deliver_payloads" configuration field.</p>
@ -1388,7 +1388,7 @@ And by opposing end them?
]]></example>
</section3>
<section3 topic='Configuration Required' anchor='subscriber-subscribe-configure'>
<p>If the entity must configure its subscription options (see the <link url='#subscriber-configure'>Configure Subscription Options</link> section of this document) before receiving notifications, the service MUST so inform the entity. It SHOULD do so by returning an IQ-result to the requesting entity with a notation that configuration of subscription options is required.</p>
<p>If the entity must configure its subscription options (see the <link url='#subscriber-configure'>Configure Subscription Options</link> section of this document) before receiving event notifications, the service MUST so inform the entity. It SHOULD do so by returning an IQ-result to the requesting entity with a notation that configuration of subscription options is required.</p>
<example caption='Service replies with success and indicates that subscription configuration is required'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
@ -1406,7 +1406,7 @@ And by opposing end them?
</pubsub>
</iq>
]]></example>
<p>Note: The node shall include the &lt;required/&gt; child element only if the subscriber must configure the subscription before receiving any notifications. A service MAY time out subscription requests if configuration is required and a configuration request is not submitted within a reasonable amount of time (which shall be determined by the service or node configuration).</p>
<p>Note: The node shall include the &lt;required/&gt; child element only if the subscriber must configure the subscription before receiving any event notifications. A service MAY time out subscription requests if configuration is required and a configuration request is not submitted within a reasonable amount of time (which shall be determined by the service or node configuration).</p>
<p>Alternatively, if the service is unable to create the subscription without simultaneous configuration, the service MAY return a &notacceptable; error, specifying a pubsub-specific error condition of &lt;configuration-required/&gt;.</p>
<example caption='Service returns error specifying that subscription configuration is required'><![CDATA[
<iq type='error'
@ -1459,10 +1459,10 @@ And by opposing end them?
<section3 topic='Multiple Subscriptions' anchor='subscriber-subscribe-multi'>
<p>An entity may wish to subscribe using different subscription options, which it can do by subscribing multiple times to the same node. Support for this feature ("multi-subscribe") is OPTIONAL.</p>
<p>If multiple subscriptions for the same JID are allowed, the service MUST use the 'subid' attribute to differentiate between subscriptions for the same entity (therefore the SubID MUST be unique for each node+JID combination and the SubID MUST be present on the entity element any time it is sent to the subscriber). It is NOT RECOMMENDED for clients to generate SubIDs, since collisions might result; therefore a service SHOULD generate the SubID on behalf of the subscriber and MAY overwrite SubIDs if they are provided by subscribers. If the service does not allow multiple subscriptions for the same entity and it receives an additional subscription request, the service MUST return the current subscription state (as if the subscription was just approved).</p>
<p>When the pubsub service generates notifications, it SHOULD send only one notification to an entity that has multiple subscriptions, rather than one notification for each subscription. By "entity" here is meant the JID specified for the subscription, whether bare JID or full JID; however, if the same bare JID has multiple subscriptions but those subscriptions are for different full JIDs (e.g., one subscription for user@domain.tld./foo and another subscription for user@domain.tld/bar), the service MUST treat those as separate JIDs for the purpose of generating notifications.</p>
<p>When the pubsub service generates event notifications, it SHOULD send only one event notification to an entity that has multiple subscriptions, rather than one event notification for each subscription. By "entity" here is meant the JID specified for the subscription, whether bare JID or full JID; however, if the same bare JID has multiple subscriptions but those subscriptions are for different full JIDs (e.g., one subscription for user@domain.tld./foo and another subscription for user@domain.tld/bar), the service MUST treat those as separate JIDs for the purpose of generating event notifications.</p>
</section3>
<section3 topic='Receiving the Last Published Item' anchor='subscriber-subscribe-last'>
<p>When a subscription request is successfully processed, the service MAY send the last published item to the new subscriber. The message containing this item SHOULD be stamped with extended information qualified by the 'urn:xmpp:delay' namespace (see &xep0203;) to indicate it is sent with delayed delivery. (Note that in this example the message notification is sent to the bare JID since that is the subscribed JID.)</p>
<p>When a subscription request is successfully processed, the service MAY send the last published item to the new subscriber. The message containing this item SHOULD be stamped with extended information qualified by the 'urn:xmpp:delay' namespace (see &xep0203;) to indicate it is sent with delayed delivery. (Note that in this example the event notification is sent to the bare JID since that is the subscribed JID.)</p>
<example caption='Service sends last published item'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
@ -1657,7 +1657,7 @@ And by opposing end them?
var='pubsub#show-values'
type='list-multi'
label='Select the presence types which are
allowed to receive notifications'>
allowed to receive event notifications'>
<option label='Want to Chat'><value>chat</value></option>
<option label='Available'><value>online</value></option>
<option label='Away'><value>away</value></option>
@ -2505,7 +2505,7 @@ And by opposing end them?
<p>The syntax is as follows:</p>
<ul>
<li>The &lt;publish/&gt; element MUST possess a 'node' attribute, specifying the NodeID of the node.</li>
<li>Depending on the node configuration, the &lt;publish/&gt; element MAY contain no &ITEM; elements or one &ITEM; element. <note>The inclusion of more than one &ITEM; element is no longer allowed, given the removal of batch publishing from version 1.13 of this specification.</note> <note>It is not necessary for a publication request to include a payload or even an &ITEM; element in order to trigger a notification. For example, the result of publishing to a transient, notification-only node will be a notification that does not include even an &ITEM; element. However, for the sake of convenience we refer to the act of publication as "publishing an item" (rather than, say, "triggering a notification") even though a publication request will not always contain an &ITEM; element.</note></li>
<li>Depending on the node configuration, the &lt;publish/&gt; element MAY contain no &ITEM; elements or one &ITEM; element. <note>The inclusion of more than one &ITEM; element is no longer allowed, given the removal of batch publishing from version 1.13 of this specification.</note> <note>It is not necessary for a publication request to include a payload or even an &ITEM; element in order to trigger an event notification. For example, the result of publishing to a transient, notification-only node will be an event notification that does not include even an &ITEM; element. However, for the sake of convenience we refer to the act of publication as "publishing an item" (rather than, say, "triggering an event notification") even though a publication request will not always contain an &ITEM; element.</note></li>
<li>The &lt;item/&gt; element provided by the publisher MAY possess an 'id' attribute, specifying a unique ItemID for the item. If an ItemID is not provided in the publish request, the pubsub service MUST generate one and MUST ensure that it is unique for that node.</li>
</ul>
<p>An example follows.</p>
@ -2553,7 +2553,7 @@ And by opposing end them?
</iq>
]]></example>
<p>Note: If the publisher previously published an item with the same ItemID, successfully processing the request means that the service MUST overwrite the old item with the new item and then proceed as follows.</p>
<p>The pubsub service MUST then send 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-bounce'>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 then send one event notification to each entity that meets the criteria for receiving an event notification (typically to each approved subscriber, although there are other contexts in which an entity may receive an event 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-bounce'>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>
<p>Note: If the service or node is configured so that there is a maximum number of items cached at the node and the maximum is reached when an item is published, the service MUST delete one of the existing items. It is RECOMMENDED for the service to follow the "first in, first out" rule and delete the oldest item. Depending on node configuration, deletion of an existing item MAY result in sending of a delete notification to the subscribers.</p>
<section4 topic='Notification With Payload' anchor='publisher-publish-success-withpayload'>
@ -2693,7 +2693,7 @@ And by opposing end them?
]]></example>
</section4>
<section4 topic='Item Publisher' anchor='publisher-publish-success-publisher'>
<p>If configured to do so, the service can include the pubisher of the item when it generates notifications.</p>
<p>If configured to do so, the service can include the pubisher of the item when it generates event notifications.</p>
<example caption='Service Notifies Subscribers'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
@ -2809,8 +2809,8 @@ And by opposing end them?
<section4 topic='Request Does Not Match Configuration' anchor='publisher-publish-error-badrequest'>
<p>If the request does not conform to the configured <link url='#events'>event type</link> for the node, the service MAY bounce the request with a &badrequest; error, which SHOULD also include a pubsub-specific error condition. The following rules apply:</p>
<ul>
<li>If the event type is persistent (either notification or payload) and the publisher does not specify an ItemID, the service MUST generate the ItemID and MUST NOT bounce the publication request.</li>
<li>If the event type is persistent (either notification or payload) and the publisher does not include an item, the service MUST bounce the publication request with a &badrequest; error and a pubsub-specific error condition of &lt;item-required/&gt;.</li>
<li>If the event type is persistent (either event notification or payload) and the publisher does not specify an ItemID, the service MUST generate the ItemID and MUST NOT bounce the publication request.</li>
<li>If the event type is persistent (either event notification or payload) and the publisher does not include an item, the service MUST bounce the publication request with a &badrequest; error and a pubsub-specific error condition of &lt;item-required/&gt;.</li>
<li>If the event type is payload (either persistent or transient) and the publisher does not include a payload, the service SHOULD bounce the publication request with a &badrequest; error and a pubsub-specific error condition of &lt;payload-required/&gt;.</li>
<li>If the event type is notification + transient and the publisher provides an item, the service MUST bounce the publication request with a &badrequest; error and a pubsub-specific error condition of &lt;item-forbidden/&gt;.</li>
</ul>
@ -2931,7 +2931,7 @@ And by opposing end them?
id='retract1'/>
]]></example>
<section4 topic='Delete And Notify' anchor='publisher-delete-success-notify'>
<p>If no error occurs and the &lt;retract/&gt; element included a 'notify' attribute with a value of "true" or "1" &BOOLEANNOTE;, then the service MUST delete the item and MUST send message notifications to all subscribers as shown below. The syntax is identical to publish notifications except that instead of an &ITEM; element, the notification includes a &lt;retract/&gt; element.</p>
<p>If no error occurs and the &lt;retract/&gt; element included a 'notify' attribute with a value of "true" or "1" &BOOLEANNOTE;, then the service MUST delete the item and MUST notify all subscribers as shown below. The syntax is identical to event notifications except that instead of an &ITEM; element, the &ITEMS; element includes a &lt;retract/&gt; element.</p>
<example caption='Subscribers are notified of deletion'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
@ -2951,7 +2951,7 @@ And by opposing end them?
]]></example>
</section4>
<section4 topic='Inclusion of Subscription ID' anchor='publisher-delete-success-subid'>
<p>If a single entity is subscribed to the node multiple times, the service SHOULD notate the notification of item deletion so that the entity can determine which subscription identifier(s) generated this event. As above, if these notations are included, they MUST use the <cite>Stanza Headers and Internet Metadata (SHIM)</cite> protocol and SHOULD be included after the event notification information (i.e., as the last child of the &MESSAGE; stanza).</p>
<p>If a single entity is subscribed to the node multiple times, the service SHOULD notate the item deletion so that the entity can determine which subscription identifier(s) generated this event. As above, if these notations are included, they MUST use the <cite>Stanza Headers and Internet Metadata (SHIM)</cite> protocol and SHOULD be included after the notification data (i.e., as the last child of the &MESSAGE; stanza).</p>
<example caption='Subscriber receives notated event notification'><![CDATA[
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
@ -3398,11 +3398,11 @@ And by opposing end them?
<value>never</value>
</field>
<field var='pubsub#presence_based_delivery' type='boolean'
label='Deliver notifications only to available users'>
label='Deliver event notifications only to available users'>
<value>0</value>
</field>
<field var='pubsub#notification_type' type='list-single'
label='Specify the delivery style for notifications'>
label='Specify the delivery style for event notifications'>
<option><value>normal</value></option>
<option><value>headline</value></option>
<value>headline</value>
@ -3566,7 +3566,7 @@ And by opposing end them?
to='hamlet@denmark.lit/elsinore'
id='config2'/>
]]></example>
<p>Note: If the node type was changed from leaf to collection and there are items associated with the node, the service MUST purge the node of all items (with or without notification).</p>
<p>Note: If the node type was changed from leaf to collection and there are items associated with the node, the service MUST purge the node of all items (with or without notifying the subscribers).</p>
</section4>
<section4 topic='Failure' anchor='owner-configure-process-failure'>
<p>If the requested node configuration change cannot be processed (e.g., because the node owner has attempted to change the configuration so that there are no node owners), the service MUST return a &notacceptable; error to the owner.</p>
@ -3582,7 +3582,7 @@ And by opposing end them?
]]></example>
</section4>
<section4 topic='Success With Notifications' anchor='owner-configure-process-notify'>
<p>If the "pubsub#notify_config" option is set to true, the service MUST send a notification of configuration change to all subscribers. (A service SHOULD support this option for leaf nodes and MUST support it for collection nodes as described in <cite>XEP-0248</cite>.) If the node configuration is set to event notifications only, the notification MUST consist of an empty &lt;configuration/&gt; element whose 'node' attribute is set to the NodeID of the node; if the node configuration is set to full payloads, the &lt;configuration/&gt; element MUST in addition contain the node configuration as represented via the <strong>Data Forms</strong> protocol.</p>
<p>If the "pubsub#notify_config" option is set to true, the service MUST notify subscribes of the configuration change. (A service SHOULD support this option for leaf nodes and MUST support it for collection nodes as described in <cite>XEP-0248</cite>.) If the node configuration is set to notification-only, the notification MUST consist of an empty &lt;configuration/&gt; element whose 'node' attribute is set to the NodeID of the node; if the node configuration is set to full payloads, the &lt;configuration/&gt; element MUST in addition contain the node configuration as represented via the <strong>Data Forms</strong> protocol.</p>
<example caption='Service sends configuration change notification (event notification only)'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
@ -4621,7 +4621,7 @@ And by opposing end them?
<p>In order to remove an entity from the affiliations list, the owner MUST set the value of the 'affiliation' attribute to "none" and the service MUST remove that entity from the affiliations list and not return it in response to future list requests.</p>
</section3>
<section3 topic='Notifying Entities' anchor='owner-affiliations-notify'>
<p>An implementation MAY send a message to an entity whose affiliation has changed, which MAY contain a &BODY; element specifying natural-language text regarding the affiliation change and which SHOULD contain the modified affiliation data.</p>
<p>An implementation MAY send an event notification to an entity whose affiliation has changed, which MAY contain a &BODY; element specifying natural-language text regarding the affiliation change and which SHOULD contain the modified affiliation data.</p>
<example caption='Service sends notification of affiliation change'><![CDATA[
<message from='pubsub.shakespeare.lit' to='polonius@denmark.lit'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
@ -5177,7 +5177,7 @@ 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>
<p>There are many possible triggers for sending an event notification to an entity for the currently published item or the last published item, as summarized below:</p>
<ol>
<li>The entity explicitly requests one or more items from the node and is authorized to retrieve items; when the service receives such a request, it sends the items to the entity.</li>
<li>The entity is an authorized subscriber to the node (explicitly via subscription or implicitly based on a role of owner or publisher); when the publisher sends a publish request, the service sends the currently published item to the entity (subject to presence checks and notification filtering if appropriate).</li>
@ -5248,7 +5248,7 @@ And by opposing end them?
</section2>
<section2 topic='IQ Notifications' anchor='impl-iqnotify'>
<p>If the pubsub service supports presence-based delivery and a node is configured to enable such delivery, the service MAY offer a value of "iq" for the "pubsub#notification_type" node configuration option. If this value is chosen, the service shall deliver notifications in XMPP IQ stanzas instead of in XMPP message stanzas. Because IQ stanzas are addressed to full JIDs &LOCALFULL;, if the service does not know the full JID of a given subscriber then it SHOULD NOT send a notification at all (just as it would not for presence-based delivery via &MESSAGE; stanzas). The IQ stanza containing a notification shall be of type "set", and in accordance with the semantics of the IQ stanza defined in <cite>RFC 3920</cite> the recipient MUST return either an IQ stanza of type "result" or an IQ stanza of type "error". An example follows</p>
<p>If the pubsub service supports presence-based delivery and a node is configured to enable such delivery, the service MAY offer a value of "iq" for the "pubsub#notification_type" node configuration option. If this value is chosen, the service shall deliver notifications in XMPP IQ stanzas instead of in XMPP message stanzas. Because IQ stanzas are addressed to full JIDs &LOCALFULL;, if the service does not know the full JID of a given subscriber then it SHOULD NOT send an event notification at all (just as it would not for presence-based delivery via &MESSAGE; stanzas). The IQ stanza containing an event notification shall be of type "set", and in accordance with the semantics of the IQ stanza defined in <cite>RFC 3920</cite> the recipient MUST return either an IQ stanza of type "result" or an IQ stanza of type "error". An example follows</p>
<example caption='Service Notifies Subscriber via IQ'><![CDATA[
<iq from='pubsub.shakespeare.lit'
id='jc9jn253'
@ -6386,7 +6386,7 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=retrieve;node=princely_musings;item=ae
<code><![CDATA[
<header>
<name>Collection</name>
<desc>The collection via which a notification was received from the originating node.</desc>
<desc>The collection via which an event notification was received from the originating node.</desc>
<doc>XEP-0248</doc>
</header>
<header>