mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-24 10:12:19 -05:00
2ac91f50c8
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2 4b5297f7-1745-476d-ba37-a9c6900126ab
6430 lines
316 KiB
XML
6430 lines
316 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE jep SYSTEM '../jep.dtd' [
|
|
<!ENTITY % ents SYSTEM '../jep.ent'>
|
|
%ents;
|
|
<!ENTITY ITEM "<item/>">
|
|
<!ENTITY ITEMS "<items/>">
|
|
<!ENTITY PUBSUB "<pubsub/>">
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
|
|
<jep>
|
|
<header>
|
|
<title>Publish-Subscribe</title>
|
|
<abstract>This document specifies an XMPP protocol extension for generic publish-subscribe functionality.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0060</number>
|
|
<status>Draft</status>
|
|
<type>Standards Track</type>
|
|
<jig>Standards JIG</jig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>JEP-0004</spec>
|
|
<spec>JEP-0030</spec>
|
|
<spec>JEP-0068</spec>
|
|
<spec>JEP-0082</spec>
|
|
<spec>JEP-0131</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>pubsub</shortname>
|
|
<schemaloc>
|
|
<ns>pubsub</ns>
|
|
<url>http://jabber.org/protocol/pubsub/pubsub.xsd</url>
|
|
</schemaloc>
|
|
<schemaloc>
|
|
<ns>pubsub#errors</ns>
|
|
<url>http://jabber.org/protocol/pubsub/errors.xsd</url>
|
|
</schemaloc>
|
|
<schemaloc>
|
|
<ns>pubsub#event</ns>
|
|
<url>http://jabber.org/protocol/pubsub/event.xsd</url>
|
|
</schemaloc>
|
|
<schemaloc>
|
|
<ns>pubsub#owner</ns>
|
|
<url>http://jabber.org/protocol/pubsub/owner.xsd</url>
|
|
</schemaloc>
|
|
|
|
&pgmillard;
|
|
&stpeter;
|
|
&ralphm;
|
|
|
|
<revision>
|
|
<version>1.9</version>
|
|
<date>2006-09-13</date>
|
|
<initials>psa</initials>
|
|
<remark>
|
|
<ul>
|
|
<li>Replaced boolean send_item_subscribe node configuration option with more comprehensive send_last_published_item option per list discussion</li>
|
|
<li>Added deliver_notifications node configuration option to enable quiet nodes without notifications, if desired enabling pull-model item retrieval only.</li>
|
|
<li>Modified subscription and affiliation retrieval to return empty element if no results.</li>
|
|
</ul>
|
|
</remark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<version>1.8</version>
|
|
<date>2006-06-27</date>
|
|
<initials>psa</initials>
|
|
<remark>
|
|
<ul>
|
|
<li>Defined five access models: open, presence, roster, authorize, and whitelist</li>
|
|
<li>Renamed pubsub#subscription_model feature to pubsub#access_model</li>
|
|
<li>Separated affiliations retrieval from subscriptions retrieval</li>
|
|
<li>Removed subscription information from affiliations management</li>
|
|
<li>Changed <entity/> element to <subscription/> element in response to subscription request</li>
|
|
<li>Clarified batch processing of item publication and item deletion</li>
|
|
<li>Added basic example to introduction</li>
|
|
<li>More fully specified node creation flows</li>
|
|
<li>More fully specified recommended behavior for caching last published item, including use of jabber:x:delay protocol</li>
|
|
<li>Specified that semantic meaning of NodeIDs must not be used to encapsulate hierarchy</li>
|
|
<li>More fully specified error conditions</li>
|
|
<li>Changed some feature-related conditions to <unsupported/> plus feature attribute</li>
|
|
<li>Changed some error conditions from <not-authorized/> to <forbidden/></li>
|
|
<li>Harmonized error conditions for unsubscribe if entity is not subscribed (unexpected-request rather than not-found)</li>
|
|
<li>Further defined error conditions related to item publication</li>
|
|
<li>Specified structure of <affiliations/>, <delete/>, <purge/>, and <subscriptions/> elements qualified by pubsub#owner namespace</li>
|
|
<li>Changed retrieval of default configuration options to use <default/> element, not <configure/> element</li>
|
|
<li>Allowed caching of last published item</li>
|
|
<li>Added pubsub#deliver subscription option</li>
|
|
<li>Added meta-data fields for pubsub#owners and pubsub#contact</li>
|
|
<li>Changed element for retrieval of default node configuration options from <configure/> to <default/> to prevent ambiguity related to configuration of root collection node</li>
|
|
<li>Specified pubsub#node_type configuration field</li>
|
|
<li>Specified pubsub#collection SHIM header</li>
|
|
<li>Specified conformance with Resourceprep for nodes addressable as JIDs</li>
|
|
<li>Added pubsub#modify-affiliations feature</li>
|
|
<li>Added pubsub#digest_frequency field to subscribe_options FORM_TYPE</li>
|
|
<li>Added pubsub#roster_groups_allowed field to node_config FORM_TYPE</li>
|
|
<li>More clearly specified the requirements level (MUST, SHOULD, MAY) for each service discovery feature</li>
|
|
<li>Defined pubsub#include_body subscription option and the pubsub#body_xslt node configuration option to transform payload format into an XMPP message body, and clarified rules for inclusion of message bodies</li>
|
|
<li>Clarified nature of collections and association of a node to a collection</li>
|
|
<li>Specified that simultaneous subscriptions of type nodes and items are allowed to collection nodes</li>
|
|
<li>Added examples and further explanation of time-based and content-based subscriptions</li>
|
|
<li>Added Internationalization Considerations</li>
|
|
<li>Clarified terminology</li>
|
|
<li>Corrected and updated the schemas</li>
|
|
</ul>
|
|
</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.7</version>
|
|
<date>2005-03-03</date>
|
|
<initials>psa/rm</initials>
|
|
<remark>
|
|
<ul>
|
|
<li>Reinstated pubsub#subscribe feature (deleted in error)</li>
|
|
<li>Added type attribute for the <create/> and <configure/> elements to differentiate between leaf nodes and collection nodes</li>
|
|
<li>In Section 8.1.7, changed affiliations retrieval support to SHOULD and added pubsub#retrieve-affiliations feature</li>
|
|
<li>In Section 8.1.10, removed two duplicate examples</li>
|
|
<li>In Section 8.1.12, clarified relationship between normal disco#info data and node meta-data (which uses a service discovery extension)</li>
|
|
<li>In Section 8.2.4, specified that node purgation MUST result in one event notification, not a notification per item</li>
|
|
<li>In Section 8.1.8, further specified handling of SubIDs</li>
|
|
<li>Clarified nature of the pubsub#type field</li>
|
|
<li>Mentioned that the forbidden error should be returned in response to certain operations requested by an outcast</li>
|
|
<li>Corrected datatype of max_items attribute from xs:string to xs:positiveInteger</li>
|
|
<li>Corrected <requesting-entity-not-subscribed/> error to <not-subscribed/> since the subscribed JID need not be that of the requesting entity</li>
|
|
<li>Added service discovery features for more optional use cases: retracting items, purging nodes, deleting nodes</li>
|
|
<li>Updated relevant registries</li>
|
|
</ul>
|
|
</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.6</version>
|
|
<date>2004-07-13</date>
|
|
<initials>pgm/psa</initials>
|
|
<remark><p>Added service discovery features for pubsub#meta-data, and pubsub#retrieve-items. Added pubsub#subscription_depth configuration option. Specified pubsub-specific error condition elements qualified by pubsub#errors namespace.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.5</version>
|
|
<date>2004-07-07</date>
|
|
<initials>pgm/psa</initials>
|
|
<remark><p>Fixed typos. Added more details to the section on collections. Added paragraph to create node use case to allow the service to change the requested node-id to something which it creates. Added text about bouncing publish requests when the request does not match the event-type for that node. Added disco features for the jabber registrar. Changed affiliation verbiage to allow publishers to remove any item. Tweaked verbiage for create node, eliminated extra example. Fully defined Jabber Registrar submissions. Corrected schemas.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.4</version>
|
|
<date>2004-06-22</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Added subid syntax in a variety of places. Added more information about disco#info and disco#items support. Added more info about subscription options. Added collection information. Added implementation notes about subscription leases, and content-based pubsub services.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.3</version>
|
|
<date>2004-04-25</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Editorial review; added one implementation note.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.2</version>
|
|
<date>2004-03-09</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added XMPP error handling.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.1</version>
|
|
<date>2004-01-14</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added Jabber Registrar Considerations subsection for Service Discovery category/type registration.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.0</version>
|
|
<date>2003-10-28</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.16</version>
|
|
<date>2003-10-23</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Clarified JID addressing usage for nodes. Added specific MAY requirement for disco usage. Added sentence about implementations verifying that an entity has a subscription before getting the current items.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.15</version>
|
|
<date>2003-10-21</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Fixed invalid XML in examples for subscription deny/allow.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.14</version>
|
|
<date>2003-10-21</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Clarified restrictions on addressing nodes by JID. Added section on Approving and Denying Subscription Requests. Changed get-pending to use Ad-Hoc Commands. Changed semantics when sending in a form type='cancel' for pending subscriptions.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.13</version>
|
|
<date>2003-09-30</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Removed item as a possible child of subscribe and unsubscribe and pubsub in the schemas. Removed retract as a possible child of item in the pubsub#event schema. Added verbiage to requirements for addressing nodes either via JIDs or disco nodes.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.12</version>
|
|
<date>2003-08-13</date>
|
|
<initials>pgm/psa</initials>
|
|
<remark><p>Defined public vs. private nodes; described how changes to existing nodes might trigger meta-node events (e.g., configuration changes); changed <x/> to <event/> for #events namespace; added meta-data about meta-nodes; fully defined Jabber Registrar considerations.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.11</version>
|
|
<date>2003-06-25</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Removed subscription notifications since they have inherent issues. Removed empty implementation note sub-section.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.10</version>
|
|
<date>2003-06-11</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Fixed error example when returning 501 from an items-get request. Added note about receiving subscription requests when an entity is already subscribed. Fixed some entity elements in various subscription examples. Many were missing the node attribute. Added subscription change notification verbiage and example. Added verbiage and example of subscription state notification being sent to the requesting entity. Added disco#items information for getting a list of item identifiers for a single node. Added verbiage for returning the current entity element when a curent subscriber attempts to subscribe again.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.9</version>
|
|
<date>2003-04-30</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Include JID attributes in the entity elements when receiving your affiliations. Changed error code 406 (which was wrong) to 404, which is correct. Changed many 405 errors to 401, and modified the error table to make it more implementable (rules are more concrete). Added subscribe-options element for indicating subscriptions may be configured.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.8</version>
|
|
<date>2003-04-03</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Clarified the affiliations table and the semantics around subscribing and unsubscribing. Added protocol to get all of your affiliations in the service. Added protocol for services informing subscribers that configurable subscription options are available. Added protocol for obtaining existing node configuration settings and for concatenating configuration and node creation requests into a single stanza. Added meta-node implementation notes and specified the interaction with the Jabber Registrar and the meta NodeIDs. Added authorization notes to subscription options.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.7</version>
|
|
<date>2003-02-14</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Clarified requirements around what affiliations must be supported. Moved requirements about specifying entities which can subscribe and publish out of the MUSTs to MAYs. Changed SHOULD to MAY when talking about allowing entities to create nodes. Added ability to send configuration requests in the same stanza as a creation request.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.6</version>
|
|
<date>2003-02-06</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Added more details and an example about publishing without NodeID. Added more implementation notes about NodeIDs and persistent storage.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.5</version>
|
|
<date>2003-01-22</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Fixed header for delete item example. Added examples showing subscribers being notified of deleted items. Added examples for notification of node deletion, and configuration for node deletion. Added Subscriber option semantics and examples. Added examples for 402 and 407 errors on subscribe and create respectively. Added clarification about ItemID handling to impl notes.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2003-01-21</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Clarified in-band and out-of-band configuration requirement. Added Delete Item privilege for all affiliations to the table. Added Delete item protocol for publishers and owners. Added 401 error case for subscribing to an illegal jid. Changed subscription request form. Added defaults to configuration form, and clarified role of the Jabber Registrar for the features show. Added text explaining the max_items attribute. Changed "last items" to "most recent items". Removed default configuration acceptance -- owners should just cancel. Added the notify_retract configuration option. Clarified error handling for affiliation modifications. </p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2003-01-20</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Added subscription attribute for entities. Removed subscriber from the affiliations table. Clarified configuration details. Clarified JabberID usages. Added Jabber Registrar Considerations. Added link to JEP-0068 about the FORM_TYPE element in subscription request notifications. Fixed some typos in examples. Added unsupported configuration namespace to example. Added a default configuration example. </p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2003-01-02</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Added numerous implementation notes; added get-pending action with regard to subscriptions; added error table; changed purge and delete to use IQ type='set'.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2002-11-19</date>
|
|
<initials>pgm</initials>
|
|
<remark><p>Initial version.</p></remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<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 problem spaces. 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 or the data itself 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 and/or the data itself 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 and/or data. 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 which all forms of pubsub can utilize. While compliant implementations are not required to implement all of the features defined herein, this document addresses most usages that may be requested of a pubsub service. Other specifications may define subsets of publish-subscribe for use in specialized contexts, but such profiles are out of scope for this document.</p>
|
|
</section2>
|
|
<section2 topic='Motivating Example' anchor='intro-example'>
|
|
<p>In order to motivate the discussion, we provide a simple, introductory example of a pubsub protocol flow.</p>
|
|
<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 one of the Shakespearean characters typical of Jabber/XMPP protocol documentation. When this character authors a new weblog entry, his blogging software publishes the entry to a pubsub node hosted at a pubsub service:</p>
|
|
<example caption='Publisher Publishes a New Weblog Entry'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/blogbot'
|
|
to='pubsub.shakespeare.lit'
|
|
id='pub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<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'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... ENTRY ...
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... ENTRY ...
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='horatio@denmark.lit' id='baz'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... ENTRY ...
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='marcellus@denmark.lit' id='fez'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... ENTRY ...
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
.
|
|
.
|
|
.
|
|
]]></example>
|
|
<p>Naturally, many other protocol flows may be required in order to enable publication of items to a node (e.g., the publisher first needs to create the node and subscribers need to sign up for notifications). These protocol flows are fully described in the remainder of this document.</p>
|
|
<p>An even simpler example is that of a transient node that sends only notifications, which is the pure pubsub model:</p>
|
|
<example caption='A Transient Notification'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='elsinore/doorbell'/>
|
|
</event>
|
|
</message>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Glossary' anchor='glossary'>
|
|
<p>The following terms are used throughout this document to refer to elements, objects, or actions that occur in the context of a pubsub service. (Note: Some of these terms are specified in greater detail within the body of this document.)</p>
|
|
<table caption='Publish-Subscribe Terms'>
|
|
<tr><td>Authorize Access Model</td><td>A node access model under which an entity can subscribe only through having a subscription request approved by a node owner (subscription requests are accepted but only provisionally) and only subscribers may retrieve items.</td></tr>
|
|
<tr><td>Address</td><td>(1) A JID as defined in &xmppcore;, or (2) the combination of a JID and a &jep0030; node.</td></tr>
|
|
<tr><td>Collection Node</td><td>A type of node that contains nodes and/or other collections but no published items. Collections make it possible to represent hierarchial node structures.</td></tr>
|
|
<tr><td>Entity</td><td>A JID-addressable Jabber entity (client, service, application, etc.).</td></tr>
|
|
<tr><td>Event</td><td>A change in the state of a node.</td></tr>
|
|
<tr><td>Instant Node</td><td>A node whose NodeID is automatically generated by a pubsub service.</td></tr>
|
|
<tr><td>Item</td><td>An XML fragment which is published to a node, thereby generating an event.</td></tr>
|
|
<tr><td>ItemID</td><td>A unique identifier for an item in the context of a specific node.</td></tr>
|
|
<tr><td>Leaf Node</td><td>A type of node that contains published items only. It is NOT a container for other nodes.</td></tr>
|
|
<tr><td>Node</td><td>A virtual location to which information can be published and from which event notifications and/or payloads can be received (in other pubsub systems, this may be labelled a "topic").</td></tr>
|
|
<tr><td>NodeID</td><td>The unique identifier for a node within the context of a pubsub service. The NodeID is either supplied by the node creator or generated by the pubsub service (if the node creator requests an Instant Node). The NodeID MAY have semantic meaning, but such meaning is OPTIONAL.</td></tr>
|
|
<tr><td>Notification</td><td>A message sent to a subscriber informing them of an event.</td></tr>
|
|
<tr><td>Outcast</td><td>An entity that is disallowed from subscribing or publishing to a node.</td></tr>
|
|
<tr><td>Owner</td><td>The manager of a node, of which there may be more than one; often but not necessarily the node creator.</td></tr>
|
|
<tr><td>Payload</td><td>The full data associated with an event rather than just the event notification itself.</td></tr>
|
|
<tr><td>Open Access Model</td><td>A node access model under which any entity may subscribe and retrieve items without approval.</td></tr>
|
|
<tr><td>Personal Eventing</td><td>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 &jep0163;.</td></tr>
|
|
<tr><td>Presence Access Model</td><td>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.</td></tr>
|
|
<tr><td>Publisher</td><td>An entity that is allowed to publish items to a node.</td></tr>
|
|
<tr><td>Pubsub Service</td><td>An XMPP server or component that adheres to the protocol defined herein.</td></tr>
|
|
<tr><td>Roster Access Model</td><td>A node access model under which any entity that is subscribed to the owner's presence and in the specified roster group(s) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.</td></tr>
|
|
<tr><td>Subscriber</td><td>An entity that is subscribed to a node.</td></tr>
|
|
<tr><td>Whitelist Access Model</td><td>A node access model under which an entity can subscribe only through being added by a node owner (subscription requests are rejected) and only subscribers may retrieve items.</td></tr>
|
|
</table>
|
|
</section1>
|
|
|
|
|
|
<!-- =================== REQS ======================== -->
|
|
<section1 topic='Requirements' anchor='reqs'>
|
|
<p>Requirements for a pubsub service can be driven by end-user needs as well as the needs of other components and services which can use the service. First, a pubsub service implemented using Jabber MUST provide the basic features which implement a pure publish-subscribe pattern:</p>
|
|
<!-- ================== MUSTS =================== -->
|
|
<ul>
|
|
<li>An entity MUST be able to publish events to a service such that all subscribers to a node receive notification of the event.</li>
|
|
<li>An entity MUST be allowed to be affiliated with a node. Allowable affiliations are owner, publisher, none, and outcast. Implementations MUST support affiliations of owner and none, and MAY support affiliations of outcast and publisher.</li>
|
|
<li>An entity MUST be allowed to query the pubsub service (or a specific node) to determine what optional features of this specification the service (or node) implements. This query MUST use the Service Discovery (disco#info) protocol.</li>
|
|
<li>An entity MUST be allowed to query a node to determine non-feature-related information about that node (e.g., the service discovery category+type). This query MUST use the Service Discovery (disco#info) protocol.</li>
|
|
</ul>
|
|
|
|
<!-- =================== MAYS and SHOULDS =================== -->
|
|
<p>Some of the possible uses of a Jabber-based pubsub service will require other features, but these features are OPTIONAL and therefore not mandatory for compliance with this specification. However, if these features are implemented, they MUST adhere to the protocol described herein in to be compliant. These features include:</p>
|
|
<ul>
|
|
<li>A service MAY cache the last item published to a node (even if the "persistent-items" option is not set to true); if it does so default "cache-last-item" to true, it SHOULD send the last published item (or notification thereof) to subscribed entities based on configuration of the "send_last_published_item" field.</li>
|
|
<li>A node owner SHOULD be able to specify who may subscribe to a node.</li>
|
|
<li>A node owner SHOULD be able to specify who may publish to a node.</li>
|
|
<li>A node MAY be configured to deliver the published payload inside the event notification.</li>
|
|
<li>A node MAY be configured to persist published items to some persistent storage mechanism.</li>
|
|
<li>A node MAY be configured to persist only a limited number of items.</li>
|
|
<li>A service MAY support collections.</li>
|
|
<li>A service or node MAY support extended service discovery information (meta-data).</li>
|
|
</ul>
|
|
|
|
</section1>
|
|
|
|
<section1 topic='Preliminaries' anchor='preliminaries'>
|
|
|
|
<section2 topic='Affiliations' anchor='affiliations'>
|
|
<p>To manage permissions, the protocol defined herein uses a hierarchy of affiliations, similiar to those introduced in &jep0045;.</p>
|
|
<p>Support for the "owner" and "none" affiliations is REQUIRED. Support for all other affiliations is RECOMMENDED. Particular kinds of pubsub services MAY enforce additional requirements.</p>
|
|
<table caption='Affiliations and their Privileges'>
|
|
<tr>
|
|
<th>Affiliation</th>
|
|
<th>Subscribe</th>
|
|
<th>Publish Items</th>
|
|
<th>Purge Items</th>
|
|
<th>Configure Node</th>
|
|
<th>Delete Node</th>
|
|
<th>Delete Item</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Owner</td>
|
|
<td>Yes</td>
|
|
<td>Yes</td>
|
|
<td>Yes</td>
|
|
<td>Yes</td>
|
|
<td>Yes</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Publisher</td>
|
|
<td>Yes</td>
|
|
<td>Yes</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>Yes/No *</td>
|
|
</tr>
|
|
<tr>
|
|
<td>None</td>
|
|
<td>Yes</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Outcast</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
<td>No</td>
|
|
</tr>
|
|
</table>
|
|
<p>* Note: A service MAY allow any publisher to delete any item once it has been published to that node instead of allowing only the original publisher to remove it (this is discoverable via the "pubsub#delete-any" feature).</p>
|
|
<p>The ways in which an entity changes its affiliation with a node are well-defined. Typically, an owner action is required to make an affiliation state transition. Affiliation changes and their triggering actions are specified in the following table.</p>
|
|
<table caption='Affiliation State Chart'>
|
|
<tr>
|
|
<th>--></th>
|
|
<th>Outcast</th>
|
|
<th>None</th>
|
|
<th>Publisher</th>
|
|
<th>Owner</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Outcast</td>
|
|
<td>--</td>
|
|
<td>Owner removes ban</td>
|
|
<td>Owner adds entity to publisher list</td>
|
|
<td>Owner adds entity to owner list</td>
|
|
</tr>
|
|
<tr>
|
|
<td>None</td>
|
|
<td>Owner bans entity</td>
|
|
<td>--</td>
|
|
<td>Owner adds entity to publisher list</td>
|
|
<td>Owner adds entity to owner list</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Publisher</td>
|
|
<td>Owner bans entity</td>
|
|
<td>Owner removes entity from publisher list</td>
|
|
<td>--</td>
|
|
<td>Owner adds entity to owner list</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Owner</td>
|
|
<td>n/a</td>
|
|
<td>Owner resigns</td>
|
|
<td>n/a</td>
|
|
<td>--</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
|
|
<section2 topic='Subscription States' anchor='substates'>
|
|
<p>Subscriptions to a node may exist in several states.</p>
|
|
<table caption='Subscription States'>
|
|
<tr>
|
|
<th>Subscription State</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>None</td>
|
|
<td>The node MUST NOT send event notifications or payloads to the Entity.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Pending</td>
|
|
<td>An entity has requested to subscribe to a node and the request has not yet been approved by a node owner. The node MUST NOT send event notifications or payloads to the entity while it is in this state.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Unconfigured</td>
|
|
<td>An entity has subscribed but its subscription options have not yet been configured. The node MAY send event notifications or payloads to the entity while it is in this state. The service MAY timeout unconfigured subscriptions.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Subscribed</td>
|
|
<td>An entity is subscribed to a node. The node MUST send all event notifications (and, if configured, payloads) to the entity while it is in this state.</td>
|
|
</tr>
|
|
</table>
|
|
</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>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).</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>Whether an item must be provided by the publisher, and whether an item ID is provided by the publisher or generated by the pubsub service, depends on the type of event being published. We can summarize the relevant rules as follows:</p>
|
|
<table caption='Event Types, Items, and Item IDs'>
|
|
<tr><th>--></th><th>Notification</th><th>Payload</th></tr>
|
|
<tr>
|
|
<td><strong>Persistent</strong></td>
|
|
<td>Publisher MUST include an &ITEM; element, which MAY be empty or contain a payload; if item ID is not provided by publisher, it MUST be generated by pubsub service</td>
|
|
<td>Publisher MUST include an &ITEM; element that contains the payload; if item ID is not provided by publisher, it MUST be generated by pubsub service</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Transient</strong></td>
|
|
<td>Publisher MUST NOT include an &ITEM; element (therefore item ID is neither provided nor generated) but the notification will include an empty &ITEMS; element</td>
|
|
<td>Publisher MUST include an &ITEM; element that contains the payload, but the item ID is OPTIONAL</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
|
|
<section2 topic='Node Types' anchor='nodetypes'>
|
|
<p>There are two types of nodes:</p>
|
|
<table caption='Node Types'>
|
|
<tr>
|
|
<th>Node Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Leaf</td>
|
|
<td>A node that contains published items only. It is NOT a container for other nodes. This is the most common node type.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Collection</td>
|
|
<td>A node that contains nodes and/or other collections but no published items. Collections make it possible to represent hierarchial node structures.</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
|
|
<section2 topic='Node Access Models' anchor='accessmodels'>
|
|
<p>In order to make node creation simpler for clients, we define the following node access models (in order of openness):</p>
|
|
<table caption='Node Access Models'>
|
|
<tr>
|
|
<th>Access Model</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Open</td>
|
|
<td>Any entity may subscribe to the node (i.e., without the necessity for subscription approval) and any entity may retrieve items from the node (i.e., without being subscribed); this SHOULD be the default access model for generic pubsub services.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Presence</td>
|
|
<td>Any entity with a subscription of type "from" or "both" may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems (see <cite>RFC 3921</cite>).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Roster</td>
|
|
<td>Any entity in the specified roster group(s) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems (see <cite>RFC 3921</cite>).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Authorize</td>
|
|
<td>The node owner must approve all subscription requests, and only subscribers may retrieve items from the node.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Whitelist</td>
|
|
<td>An entity may be subscribed only through being added to a whitelist by the node owner (unsolicited subscription requests are rejected), and only subscribers may retrieve items from the node. In effect, the default affiliation is outcast. The node owner MUST automatically be on the whitelist. In order to add entities to the whitelist, the node owner SHOULD use the protocol specified in the <link url='#owner-affiliations'>Manage Affiliated Entities</link> section of this document.</td>
|
|
</tr>
|
|
</table>
|
|
<p>A generic publish-subscribe implementation SHOULD support all of the defined access models, although specialized publish-subscribe implementations MAY support only a subset of the access models. Which access models are provided in a particular deployment is a matter of service provisioning (e.g., some restricted deployments may wish to lock down permissions so that only the "authorize" and "whitelist" access models are provided, or even only the "whitelist" access model).</p>
|
|
<p>In order for a node creator or owner to specify the access model (see the <link url='#owner-create'>Create a Node With Default Configuration</link> and <link url='#owner-configure'>Configure a Node</link> sections of this document), the 'pubsub#access_model' configuration field is used.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Addressing' anchor='addressing'>
|
|
<p>If a pubsub node is addressable, it MUST be addressable either (1) as a JID or (2) as the combination of a JID and a node. <note>These nodes are equivalent to those used in <cite>JEP-0030: Service Discovery</cite>.</note></p>
|
|
<section3 topic='JID' anchor='addressing-jid'>
|
|
<p>If a pubsub node is addressable as a JID, the NodeID MUST be the resource identifier, and MUST NOT be specified by the "user" portion (node identifier) of the JID (e.g. "domain.tld/NodeID" and "user@domain.tld/NodeID" are allowed; "NodeID@domain.tld" is not allowed). JID addressing SHOULD be used when interacting with a pubsub node using a protocol that does not support the node attribute. For example, when a service makes it possible for entities to subscribe to nodes via presence, it would address nodes as JIDs. If a pubsub node is addressable as a JID, the pubsub service MUST ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in <cite>RFC 3920</cite>.</p>
|
|
<p>Consider the following example, in which the pubsub service is located at the hostname pubsub.shakespeare.lit.</p>
|
|
<example caption='Node addressed as domain.tld/NodeID'><![CDATA[
|
|
<iq to='pubsub.shakespeare.lit/news announcements'>
|
|
...
|
|
</iq>
|
|
]]></example>
|
|
<p>Now consider the following example, in which the pubsub service is located at pubsub@shakespeare.lit.</p>
|
|
<example caption='Node addressed as user@domain.tld/NodeID'><![CDATA[
|
|
<iq to='pubsub@shakespeare.lit/news announcements'>
|
|
...
|
|
</iq>
|
|
]]></example>
|
|
</section3>
|
|
<section3 topic='JID+NodeID' anchor='addressing-jidnode'>
|
|
<p>If a pubsub node is addressable as a JID plus node, the NodeID MUST be the value of both the Service Discovery 'node' attribute and the pubsub 'node' attribute; i.e., for discovery purposes, a pubsub node is equivalent to a Service Discovery node. If a pubsub node is addressable as a JID plus node, the pubsub service SHOULD ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in <cite>RFC 3920</cite>.</p>
|
|
<p>Consider the following example, in which the (virtual) pubsub service is located at hamlet@denmark.lit.</p>
|
|
<example caption='Node addressed as JID+NodeID'><![CDATA[
|
|
<iq to='hamlet@denmark.lit'>
|
|
<query node='princely_musings'/>
|
|
</iq>
|
|
]]></example>
|
|
</section3>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Entity Use Cases' anchor='entity'>
|
|
<p>This section defines the use cases for and protocols to be used by any entity that wishes to interact with a publish-subscribe service, mainly focused on Service Discovery use cases.</p>
|
|
|
|
<section2 topic='Discover Features' anchor='entity-features'>
|
|
<p>A service MUST respond to service discovery information requests qualified by the 'http://jabber.org/protocol/disco#info' namespace. The "disco#info" result returned by a pubsub service MUST indicate the identity of the service and indicate which pubsub features are supported.</p>
|
|
<example caption='Entity Queries Pubsub Service Regarding Supported Features'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='feature1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Pubsub Service Returns Set of Supported Features'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='feature1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<identity category='pubsub' type='service'/>
|
|
<feature var='http://jabber.org/protocol/pubsub'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>The possible pubsub features are noted throughout this document and have been registered as described in the <link url='#registrar'>Jabber Registrar Considerations</link> section of this document. For information regarding which features are required, recommended, and optional, see the <link url='#features'>Feature Summary</link> section of this document.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Discover Nodes' anchor='entity-nodes'>
|
|
<p>If a service implements a hierarchy of nodes (by means of <link url='#collections'>Collection Nodes</link>), it MUST also enable entities to discover the nodes in that hierarchy by means of the <strong>Service Discovery</strong> protocol, subject to the recommendations in <cite>JEP-0030</cite> regarding large result sets (for which &jep0055; or some other protocol SHOULD be used). The following examples show the use of service discovery in discovering the nodes available at a hierarchical pubsub service.</p>
|
|
<p>Note: Node hierarchies and collection nodes are OPTIONAL. For details, refer to the <link url='#impl-semantics'>NodeID Semantics</link> and <link url='#collections'>Collection Nodes</link> sections of this document.</p>
|
|
<p>In the first example, an entity sends a service discovery items ("disco#items") request to the root node (i.e., the service itself), which is a <link url='#collections'>Collection Node</link>:</p>
|
|
<example caption='Entity requests all first-level nodes'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='nodes1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service returns all first-level nodes'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='nodes1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'>
|
|
<item jid='pubsub.shakespeare.lit'
|
|
node='blogs'
|
|
name='Weblog updates'/>
|
|
<item jid='pubsub.shakespeare.lit'
|
|
node='news'
|
|
name='News and announcements'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>In the second example, an entity sends a disco#items request to one of the first-level nodes, which is also a collection node:</p>
|
|
<example caption='Entity requests second-level nodes'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='nodes2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='blogs'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service returns second-level nodes'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='nodes2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='blogs'>
|
|
<item jid='pubsub.shakespeare.lit'
|
|
node='princely_musings'/>
|
|
<item jid='pubsub.shakespeare.lit'
|
|
node='kingly_ravings'/>
|
|
<item jid='pubsub.shakespeare.lit'
|
|
node='starcrossed_stories'/>
|
|
<item jid='pubsub.shakespeare.lit'
|
|
node='moorish_meanderings'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If a node is a leaf node rather than a collection node and items have been published to the node, the service MAY return one &ITEM; element for each published item as described in the <link url='#entity-discoveritems'>Discover Items for a Node</link> section of this document, however such items MUST NOT include a 'node' attribute (since they are published items, not nodes).</p>
|
|
</section2>
|
|
|
|
<section2 topic='Discover Node Information' anchor='entity-info'>
|
|
<p>A pubsub service MUST allow entities to query individual nodes for the information associated with that node. The Service Discovery protocol MUST be used to discover this information. The "disco#info" result MUST include an identity with a category of "pubsub" and a type of either "leaf" or "collection".</p>
|
|
<p>Note: If a node has an identity type of "leaf", then it MUST NOT contain other nodes or collections (only items); if a node has an identity type of "collection", then it MUST NOT contain items (only other nodes or collections).</p>
|
|
<example caption='Entity queries collection node for information'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='info2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='blogs'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with identity of pubsub/collection'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='meta1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='blogs'>
|
|
...
|
|
<identity category='pubsub' type='collection'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Entity queries leaf node for information'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='princely_musings'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with identity of pubsub/collection'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<identity category='pubsub' type='leaf'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Discover Node Meta-Data' anchor='entity-metadata'>
|
|
<p>The "disco#info" result MAY include detailed meta-data about the node, encapsulated in the &jep0004; format as described in &jep0128;, where the data form context is specified by including a FORM_TYPE of "http://jabber.org/protocol/pubsub#meta-data" in accordance with &jep0068;. If meta-data is provided, it SHOULD include values for all configured options as well as "automatic" information such as the node creation date, a list of publishers, and the like.</p>
|
|
<example caption='Entity queries a node for information'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='meta1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='princely_musings'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with information and meta-data'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='meta1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='princely_musings'/>
|
|
<identity category='pubsub' type='leaf'/>
|
|
<feature var='http://jabber.org/protocol/pubsub'/>
|
|
<x xmlns='jabber:x:data' type='result'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#meta-data</value>
|
|
</field>
|
|
<field var='pubsub#type' label='Payload type'>
|
|
<value>http://www.w3.org/2005/Atom</value>
|
|
</field>
|
|
<field var='pubsub#creator' label='Node creator'>
|
|
<value>hamlet@denmark.lit</value>
|
|
</field>
|
|
<field var='pubsub#creation_date' label='Creation date'>
|
|
<value>2003-07-29T22:56Z</value>
|
|
</field>
|
|
<field var='pubsub#title' label='A short name for the node'>
|
|
<value>Princely Musings (Atom)</value>
|
|
</field>
|
|
<field var='pubsub#description' label='A description of the node'>
|
|
<value>Updates for Hamlet's Princely Musings weblog.</value>
|
|
</field>
|
|
<field var='pubsub#language' label='Default language'>
|
|
<value>en</value>
|
|
</field>
|
|
<field var='pubsub#contact' label='People to contact with questions'>
|
|
<value>bard@shakespeare.lit</value>
|
|
</field>
|
|
<field var='pubsub#owner' label='Node owners'>
|
|
<value>hamlet@denmark.lit</value>
|
|
</field>
|
|
<field var='pubsub#publisher' label='Publishers to this node'>
|
|
<value>hamlet@denmark.lit</value>
|
|
</field>
|
|
<field var='pubsub#num_subscribers' label='Number of subscribers to this node'>
|
|
<value>1066</value>
|
|
</field>
|
|
</x>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>Note: Node meta-data can be set in many ways. Some of it is based on node configuration (e.g., the owner's JID) whereas some of it may be dynamic (e.g., the number of subscribers). Any static information to be provided in the node meta-data SHOULD be provided as fields in the node configuration form.</p>
|
|
<p>Much of the meta-data provided about a node maps directly to selected &DUBLINCORE; meta-data attributes; specifically:</p>
|
|
<table caption='Dublin Core Meta-Data Mapping'>
|
|
<tr><th>Pubsub Field</th><th>Dublin Core Meta-Data Attribute</th></tr>
|
|
<tr><td>pubsub#creation_date</td><td>Date <note>The value SHOULD be a DateTime as defined in <cite>JEP-0082</cite>, and MUST conform to one of the profiles defined therein.</note></td></tr>
|
|
<tr><td>pubsub#creator</td><td>Creator</td></tr>
|
|
<tr><td>pubsub#description</td><td>Description</td></tr>
|
|
<tr><td>pubsub#language</td><td>Language</td></tr>
|
|
<tr><td>pubsub#publisher</td><td>Publisher</td></tr>
|
|
<tr><td>pubsub#title</td><td>Title</td></tr>
|
|
<tr><td>pubsub#type</td><td>Type <note>The pubsub type SHOULD be the namespace that defines the payload (such as 'http://www.w3.org/2005/Atom'), if payloads are supported.</note></td></tr>
|
|
</table>
|
|
</section2>
|
|
|
|
<section2 topic='Discover Items for a Node' anchor='entity-discoveritems'>
|
|
<p>To discover the published items which exist on the service for a specific node, an entity MAY send a "disco#items" request to the node itself, and the service MAY return each item as a Service Discovery &ITEM; element. The 'name' attribute of each Service Discovery item MUST contain its ItemID and the item MUST NOT possess a 'node' attribute. This ItemID MAY then be used to retrieve the item using the protocol defined in the <link url='#subscriber-retrieve'>Retrieve Items from a Node</link> section of this document.</p>
|
|
<example caption='Entity requests all of the items for a node'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='items1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='princely_musings'/>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='princely_musings'>
|
|
<item jid='pubsub.shakespeare.lit' name='368866411b877c30064a5f62b917cffe'/>
|
|
<item jid='pubsub.shakespeare.lit' name='3300659945416e274474e469a1f0154c'/>
|
|
<item jid='pubsub.shakespeare.lit' name='4e30f35051b7b8b42abe083742187228'/>
|
|
<item jid='pubsub.shakespeare.lit' name='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic='Retrieve Subscriptions' anchor='entity-subscriptions'>
|
|
<p>A service SHOULD allow an entity to query the service to retrieve its subscriptions for all nodes at the service. In order to make the request, the requesting entity MUST send an IQ-get whose &PUBSUB; child contains an empty <subscriptions/> element with no attributes.</p>
|
|
<example caption='Entity requests all current subscriptions'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='subscriptions1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscriptions/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service returns a list of subscriptions, it MUST return all subscriptions for all JIDs that match the bare JID (&BAREJID;) portion of the 'from' attribute on the request.</p>
|
|
<p>For each subscription, a <subscription/> element is returned specifying the NodeID, the JID that is affiliated (which MAY include a resource, depending on how the entity subscribed), and the current subscription state. If subscription identifiers are supported by the service, the 'subid' attribute MUST be present as well.</p>
|
|
<example caption='Service returns all current subscriptions'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit'
|
|
id='subscriptions1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscriptions>
|
|
<subscription node='node1' jid='francisco@denmark.lit' subscription='subscribed'/>
|
|
<subscription node='node2' jid='francisco@denmark.lit' subscription='subscribed'/>
|
|
<subscription node='node5' jid='francisco@denmark.lit' subscription='unconfigured'/>
|
|
<subscription node='node6' jid='francisco@denmark.lit' subscription='pending'/>
|
|
</subscriptions>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity has no subscriptions, the pubsub service MUST return an empty <subscriptions/> element.</p>
|
|
<example caption='No subscriptions'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='subscriptions1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscriptions/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service does not support subscriptions retrieval, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-subscriptions".</p>
|
|
<example caption='Subscriptions retrieval not supported'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='subscriptions1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscriptions/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='retrieve-subscriptions'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Retrieve Affiliations' anchor='entity-affiliations'>
|
|
<p>A service SHOULD allow an entity to query the service to retrieve its affiliations for all nodes at the service. In order to make the request, the requesting entity includes an empty <affiliations/> element with no attributes.</p>
|
|
<example caption='Entity requests all current affiliations'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='affil1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<affiliations/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service returns a list of affiliations, it MUST return all affiliations for all JIDs that match the bare JID (&BAREJID;) portion of the 'from' attribute on the request.</p>
|
|
<p>For each affiliation, an <affiliation/> element is returned containing the NodeID and the affiliation state (owner, publisher, or outcast).</p>
|
|
<example caption='Service replies with all current affiliations'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit'
|
|
id='affil1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<affiliations>
|
|
<affiliation node='node1' affiliation='owner'/>
|
|
<affiliation node='node2' affiliation='publisher'/>
|
|
<affiliation node='node5' affiliation='outcast'/>
|
|
<affiliation node='node6' affiliation='owner'/>
|
|
</affiliations>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity has no affiliations, the pubsub service MUST return an empty <affiliations/> element.</p>
|
|
<example caption='No affiliations'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='affil1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<affiliations/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service does not support affiliations retrieval, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-affiliations".</p>
|
|
<example caption='Affiliations retrieval not supported'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='affil1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<affiliations/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='retrieve-affiliations'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Subscriber Use Cases' anchor='subscriber'>
|
|
|
|
<p>This section defines the use cases for and protocols to be used by potential and actual subscribers. (Note: The <link url='#impl'>Implementation Notes</link> section of this document describes many important factors and business rules which a pubsub service MUST observe. In addition, the examples throughout assume the existence of a separate pubsub component and include any relevant 'from' addresses as stamped by a server or network edge.)</p>
|
|
|
|
<section2 topic='Subscribe to a Node' anchor='subscriber-subscribe'>
|
|
<p>When a Jabber entity wishes to subscribe to a node, it sends a subscription request to the pubsub service. The subscription request is an IQ-set where the <pubsub/> element contains one and only one <subscribe/> element. The <subscribe/> element MUST possess a 'node' attribute specifying the node to which the entity wishes to subscribe. The <subscribe/> element MUST also possess a 'jid' attribute specifying the exact XMPP address to be used as the subscribed JID -- often a bare JID (&BAREJID;) or full JID (&FULLJID;), although JIDs of the form &DOMAIN; or &DOMAINRES; may subscribe as well.</p>
|
|
<p>If the specified JID is a bare JID or full JID, the service MUST at a minimum check the bare JID portion against the bare JID portion of the 'from' attribute on the received IQ request to make sure that the requesting entity has the same identity as the JID which is being requested to be added to the subscriber list. However, some implementations MAY enable the service administrator to configure a list of entities that are excluded from this check; those entities may be considered "trusted proxies" that are allowed to subscribe on behalf of other entities. In the same way, implementations MAY enable blacklisting of entities that are not allowed to perform specific operations (such as subscribing or creating nodes).</p>
|
|
<p>A service MAY allow entities to subscribe multiple times to the same node. This enables an entity to subscribe using different subscription options. 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>Here is an example of a subscription request.</p>
|
|
<example caption='Entity subscribes to a node'><![CDATA[
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the subscription request is successfully processed, the server MUST inform the requesting entity that it is now subscribed (which MAY include a service-generated SubID).</p>
|
|
<example caption='Service replies with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'
|
|
subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'
|
|
subscription='subscribed'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>The service MAY also send the last published item to the new subscriber. The message containing this item SHOULD be stamped with extended information qualified by the 'jabber:x:delay' namespace (see &jep0091;) to indicate it is are 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>
|
|
<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'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
<x xmlns='jabber:x:delay' stamp='20031213T23:58:37'/>
|
|
</message>
|
|
]]></example>
|
|
<p>There are several reasons why the subscription request might fail:</p>
|
|
<ol>
|
|
<li>The bare JID portions of the JIDs do not match.</li>
|
|
<li>The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence.</li>
|
|
<li>The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups.</li>
|
|
<li>The node has an access model of "whitelist" and the requesting entity is not on the whitelist.</li>
|
|
<li>The service requires payment for subscriptions to the node.</li>
|
|
<li>The requesting entity is anonymous and the service does not allow anonymous entities to subscribe.</li>
|
|
<li>The requesting entity has a pending subscription.</li>
|
|
<li>The requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast).</li>
|
|
<li>The node does not support subscriptions.</li>
|
|
<li>The node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the bare JID portions of the JIDs do not match as described above and the requesting entity does not have some kind of admin or proxy privilege as defined by the implementation, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-jid/>.</p>
|
|
<example caption='JIDs do not match'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='bernardo@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<invalid-jid xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>For nodes with an access model of "presence", if the requesting entity is not subscribed to the owner's presence then the pubsub service MUST respond with a ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <presence-subscription-required/>.</p>
|
|
<example caption='Entity is not authorized to create a subscription (presence subscription required)'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<presence-subscription-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>For nodes with an access model of "roster", if the requesting entity is not in one of the authorized roster groups then the pubsub service MUST respond with a ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <not-in-roster-group/>.</p>
|
|
<example caption='Entity is not authorized to create a subscription (not in roster group)'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<not-in-roster-group xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <closed-node/>.</p>
|
|
<example caption='Node has whitelist access model'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<closed-node xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>Commercial deployments may wish to link subscribers to a database of paying customers. If the subscriber needs to provide payment in order to subscribe to the node (e.g., if the subscriber is not in the customer database or the customer's account is not paid up), the service SHOULD return a &payment; error to the subscriber.</p>
|
|
<example caption='Payment is required for a subscription'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<payment-required xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>Some XMPP servers may allow authentication using SASL ANONYMOUS; however, because the resulting entity is unstable (the assigned JID may not be owned by the same principal in a persistent manner), a service MAY prevent anonymous entities from subscribing to nodes and SHOULD use service discovery to determine if an entity has an identity of "account/anonymous". If a requesting entity is anonymous but the service does not allow anonymous entities to subscribe, the service SHOULD return a &forbidden; error to the subscriber.</p>
|
|
<example caption='Requesting entity is anonymous'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='anonymous@denmark.lit/foo'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='anonymous@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity has a pending subscription, the service MUST return a ¬authorized; error to the subscriber, specifying a pubsub-specific error condition of <pending-subscription/>.</p>
|
|
<example caption='Requesting entity has pending subscription'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<pending-subscription xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a &forbidden; error to the subscriber.</p>
|
|
<example caption='Requesting entity is blocked'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not allow entities to subscribe, the service SHOULD return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscribe".</p>
|
|
<example caption='Subscribing not supported'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='subscribe'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not exist, the service SHOULD return an ¬found; error to the subscriber.</p>
|
|
<example caption='Node does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>For nodes with an access model of "authorize", subscription requests MUST be approved by one of the node owners; therefore the pubsub service sends a message to the node owner(s) requesting authorization (see the <link url='#owner-subreq'>Manage Subscription Requests</link> section of this document). Because the subscription request may or may not be approved, the service MUST return a pending notification to the subscriber.</p>
|
|
<example caption='Service replies with pending'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'
|
|
subscription='pending'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<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>
|
|
<example caption='Service replies with success and indicates that subscription configuration is required'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'
|
|
subscription='unconfigured'>
|
|
<subscribe-options>
|
|
<required/>
|
|
</subscribe-options>
|
|
</subscription>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>Note: The node shall include the <required/> 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>Alternatively, if the service is unable to create the subscription without simultaneous configuration, the service MAY return a ¬acceptable; error, specifying a pubsub-specific error condition of <configuration-required/>.</p>
|
|
<example caption='Service returns error specifying that subscription configuration is required'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
<field var='pubsub#deliver'><value>1</value></field>
|
|
<field var='pubsub#digest'><value>0</value></field>
|
|
<field var='pubsub#include_body'><value>false</value></field>
|
|
<field var='pubsub#show-values'>
|
|
<value>chat</value>
|
|
<value>online</value>
|
|
<value>away</value>
|
|
</field>
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<configuration-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the <required/> element is not included and no error is returned, the subscription takes effect immediately and the entity may configure the subscription at any time (the service MAY indicate that subscription options are supported by including an empty <subscribe-options/> element in the IQ-result, as shown in the following example).</p>
|
|
<example caption='Service replies with success and indicates that subscription options are supported but not required'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'
|
|
subscription='unconfigured'>
|
|
<subscribe-options/>
|
|
</subscription>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic='Unsubscribe from a Node' anchor='subscriber-unsubscribe'>
|
|
<p>To unsubscribe from a node, the subscriber sends an IQ-set whose &PUBSUB; child contains an <unsubscribe/> element that specifies the node and the subscribed JID.</p>
|
|
<example caption='Entity unsubscribes from a node'><![CDATA[
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='unsub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<unsubscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the request can be successfully processed, the service MUST return an IQ result.</p>
|
|
<example caption='Service replies with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='unsub1'/>
|
|
]]></example>
|
|
<p>There are several reasons why the unsubscribe request might fail:</p>
|
|
<ol>
|
|
<li>The requesting entity has multiple subscriptions to the node but does not specify a subscription ID.</li>
|
|
<li>The request does not specify an existing subscriber.</li>
|
|
<li>The requesting entity does not have sufficient privileges to unsubscribe the specified JID.</li>
|
|
<li>The node does not exist.</li>
|
|
<li>The request specifies a subscription ID that is not valid or current.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <subid-required/>.</p>
|
|
<example caption='Entity did not specify SubID'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='unsub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<unsubscribe node='princely_musings' jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<subid-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the value of the 'jid' attribute does not specify an existing subscriber, the pubsub service MUST return an error stanza, which SHOULD be &unexpected; and which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.</p>
|
|
<example caption='Requesting entity is not a subscriber'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='unsub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<unsubscribe node='princely_musings' jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<unexpected-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<not-subscribed xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity is prohibited from unsubscribing the specified JID, the service MUST return a &forbidden; error. The service MUST validate that the entity making the request is authorized to unsubscribe the entity. If the subscriber's JID is of the form &FULLJID;, a service MUST perform this check by comparing the &BAREJID; part of the two JIDs to ensure that they match. If the bare JID portions of the JIDs do not match and the requesting entity is not authorized to unsubscribe the JID (e.g., because it is not a service-wide admin or authorized proxy), the service MUST return a &forbidden; error.</p>
|
|
<example caption='Requesting entity is prohibited from unsubscribing entity'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='unsub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<unsubscribe
|
|
node='princely_musings'
|
|
jid='bard@shakespeare.lit'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not exist, the pubsub service MUST return an ¬found; error.</p>
|
|
<example caption='Node does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='unsub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<unsubscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If a subscription identifier is associated with the subscription, the unsubscribe request MUST include an appropriate 'subid' attribute. If the unsubscribe request includes a SubID but SubIDs are not supported for the node (or the subscriber did not subscribe using a SubID in the first place), the service SHOULD ignore the SubID and simply unsubscribe the entity. If the subscriber originally subscribed with a SubID but the unsubscribe request includes a SubID that is not valid or current for the subscriber, the service MUST return a ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.</p>
|
|
<example caption='Invalid subscription identifier'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='unsub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<unsubscribe
|
|
node='princely_musings'
|
|
subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<invalid-subid xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Configure Subscription Options' anchor='subscriber-configure'>
|
|
<p>Implementations MAY allow subscribers to configure subscription options. Implementations SHOULD use the <strong>Data Forms</strong> protocol to accomplish this configuration (however, an out-of-band mechanism such as a web interface could be offered as well).</p>
|
|
<p>If a service supports subscription options it MUST advertise that fact in its response to a "disco#info" query by including a feature whose 'var' attribute is "pubsub#subscription-options".</p>
|
|
<example caption='Pubsub service indicates support for subscription options'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='feature1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='http://jabber.org/protocol/pubsub#subscription-options'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>A subscriber requests the subscription options by including an <options/> element inside an IQ-get stanza.</p>
|
|
<example caption='Subscriber requests subscription options form'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='options1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the request can be successfully processed, the service MUST respond with the options.</p>
|
|
<example caption='Service responds with the options form'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='options1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
<field var='pubsub#deliver' type='boolean'
|
|
label='Enable delivery?'>
|
|
<value>1</value>
|
|
</field>
|
|
<field var='pubsub#digest' type='boolean'
|
|
label='Receive digest notifications (approx. one per day)?'>
|
|
<value>0</value>
|
|
</field>
|
|
<field var='pubsub#include_body' type='boolean'
|
|
label='Receive message body in addition to payload?'>
|
|
<value>false</value>
|
|
</field>
|
|
<field
|
|
var='pubsub#show-values'
|
|
type='list-multi'
|
|
label='Select the presence types which are
|
|
allowed to receive notifications'>
|
|
<option label='Want to Chat'><value>chat</value></option>
|
|
<option label='Available'><value>online</value></option>
|
|
<option label='Away'><value>away</value></option>
|
|
<option label='Extended Away'><value>xa</value></option>
|
|
<option label='Do Not Disturb'><value>dnd</value></option>
|
|
<value>chat</value>
|
|
<value>online</value>
|
|
</field>
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>Note: The foregoing example shows some (but by no means all) of the possible configuration options that MAY be provided. If an implementation provides these options using the <strong>Data Forms</strong> protocol, it MUST use the field variables that are registered with the Jabber Registrar in association with the 'http://jabber.org/protocol/pubsub' namespace (a preliminary representation of those field variables is shown above and in the <link url='#registrar-formtypes-options'>pubsub#subscribe_options FORM_TYPE</link> section of this document, but MUST NOT be construed as canonical since the Jabber Registrar may standardize additional fields at a later date without changes to this document).</p>
|
|
<p>Note: Many of the relevant data form fields are of type "boolean" and MUST be handled accordingly. &BOOLEANNOTE;</p>
|
|
<p>There are several reasons why the options request might fail:</p>
|
|
<ol>
|
|
<li>The requesting entity does not have sufficient privileges to modify subscription options for the specified JID.</li>
|
|
<li>The requesting entity (or specified subscriber) is not subscribed.</li>
|
|
<li>The request does not specify both the NodeID and the subscriber's JID.</li>
|
|
<li>The request does not specify a subscription ID but one is required.</li>
|
|
<li>The request specifies a subscription ID that is not valid or current.</li>
|
|
<li>Subscription options are not supported.</li>
|
|
<li>The node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>When requesting subscription options, the subscriber MUST specify the JID that is subscribed to the node and SHOULD specify a node (if no node is specified, the service MUST assume that the requesting entity wishes to request subscription options for its subscription to the root collection node; see the <link url='#collections-root'>Root Collection Node</link> section of this document for details).</p>
|
|
<p>The service MUST validate that the entity making the request is authorized to set the subscription options for the subscribed entity. If the subscriber's JID is of the form &FULLJID;, a service MUST perform this check by comparing the &BAREJID; part of the two JIDs to ensure that they match. If the bare JID portions of the JIDs do not match and the requesting entity is not authorized to modify subscription options for the JID (e.g., because it is not a service-wide admin or authorized proxy), the service MUST return a &forbidden; error.</p>
|
|
<example caption='Requesting entity does not have sufficient privileges to modify subscription options'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='bernardo@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity (or specified subscriber, if different) is not subscribed, the service MUST return an &unexpected; error, which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.</p>
|
|
<example caption='No such subscriber'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='options1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<unexpected-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<not-subscribed xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the subscriber does not specify a JID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <jid-required/>.</p>
|
|
<example caption='Subscriber JID not specified'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='options1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<jid-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If a subscription identifier is associated with the subscription, the 'subid' attribute MUST be present on the request in order for the service to differentiate subscriptions for the same entity. If the 'subid' is required but not provided, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <subid-required/>.</p>
|
|
<example caption='SubID required'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<subid-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If a subscription identifier is associated with the subscription but the request includes a SubID that is not valid or current for the subscriber, the service MUST return a ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.</p>
|
|
<example caption='Invalid subscription identifier'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='unsub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<unsubscribe
|
|
node='princely_musings'
|
|
subid='991d7fd1616fd041015064133cd097a10030819e'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<invalid-subid xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node or service does not support subscription options, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscription-options".</p>
|
|
<example caption='Subscription options not supported'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='options1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='subscription-options'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not exist, the pubsub service MUST return an ¬found; error.</p>
|
|
<example caption='Node does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='options1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>After receiving the configuration form, the requesting entity SHOULD submit the form in order to update the entity's subscription options for that node.</p>
|
|
<example caption='Subscriber submits completed options form'><![CDATA[
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='options2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
<field var='pubsub#deliver'><value>1</value></field>
|
|
<field var='pubsub#digest'><value>0</value></field>
|
|
<field var='pubsub#include_body'><value>false</value></field>
|
|
<field var='pubsub#show-values'>
|
|
<value>chat</value>
|
|
<value>online</value>
|
|
<value>away</value>
|
|
</field>
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service can successfully process the submission, it MUST respond with success.</p>
|
|
<example caption='Service responds with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='options2'/>
|
|
]]></example>
|
|
<p>If the subscriber attempts to set an invalid group of options, the service MUST respond with a &badrequest; error.</p>
|
|
<example caption='Service responds with Bad Request for invalid options'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='options2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'>
|
|
<x xmlns='jabber:x:data'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
<field var='pubsub#deliver'><value>1</value></field>
|
|
<field var='pubsub#digest'><value>0</value></field>
|
|
<field var='pubsub#include_body'><value>false</value></field>
|
|
<field var='pubsub#show-values'>
|
|
<value>chat</value>
|
|
<value>online</value>
|
|
<value>away</value>
|
|
</field>
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<invalid-options xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>The other errors already mentioned for getting subscription options also apply to setting subscription options.</p>
|
|
<p>As noted, if a service supports subscription options, an entity MAY subscribe and provide the subscription options in the same stanza.</p>
|
|
<p>Note: The <options/> element MUST follow the <subscribe/> element and MUST NOT possess a 'node' attribute or 'jid' attribute, since the value of the <subscribe/> element's 'node' attribute specifies the desired NodeID and the value of the <subscribe/> element's 'jid' attribute specifies the subscriber's JID; if any of these rules are violated, the service MUST return a &badrequest; error.</p>
|
|
<example caption='Entity subscribes to node and sets configuration options'><![CDATA[
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='sub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe node='princely_musings' jid='francisco@denmark.lit'/>
|
|
<options>
|
|
<x xmlns='jabber:x:data'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
<field var='pubsub#deliver'><value>1</value></field>
|
|
<field var='pubsub#digest'><value>0</value></field>
|
|
<field var='pubsub#include_body'><value>false</value></field>
|
|
<field var='pubsub#show-values'>
|
|
<value>chat</value>
|
|
<value>online</value>
|
|
<value>away</value>
|
|
</field>
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Retrieve Items from a Node' anchor='subscriber-retrieve'>
|
|
<p>Implementations of pubsub that choose to persist items MAY allow entities to request existing items from a node (e.g., an entity may wish to do this after successfully subscribing in order to receive all the items in the publishing history for the node). The service MUST conform to the node's access model in determining whether to return items to the entity that requests them. Specifically:</p>
|
|
<ul>
|
|
<li><p>If the access model is "open", the service SHOULD allow any entity (whether or not it is subscribed) to retrieve items.</p></li>
|
|
<li><p>If the access model is "presence", the service SHOULD allow any entity that is subscribed to the owner's presence to retrieve items.</p></li>
|
|
<li><p>If the access model is "roster", the service SHOULD allow any entity that is subscribed to the owner's presence and contained in the relevant roster group(s) to retrieve items.</p></li>
|
|
<li><p>If the access model is "authorize" or "whitelist", the service MUST allow only subscribed entities to retrieve items.</p></li>
|
|
</ul>
|
|
<p>The only exception foreseen to the SHOULD requirements for the foregoing access models is the enforcement of local privacy and security policies as specified more fully in the <link url='#security'>Security Considerations</link> section of this document. (In addition, a service MUST always allow the node owner to retrieve items from a node and SHOULD always allow a publisher to do so.)</p>
|
|
<p>The subscriber may request all items by specifying only the Node ID without restrictions.</p>
|
|
<example caption='Subscriber requests all items'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>The service then SHOULD return all items published to the node, although it MAY truncate the result set if a large number of items has been published.</p>
|
|
<example caption='Service returns all items'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'>
|
|
<item id='368866411b877c30064a5f62b917cffe'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>The Uses of This World</title>
|
|
<summary>
|
|
O, that this too too solid flesh would melt
|
|
Thaw and resolve itself into a dew!
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32396</id>
|
|
<published>2003-12-12T17:47:23Z</published>
|
|
<updated>2003-12-12T17:47:23Z</updated>
|
|
</entry>
|
|
</item>
|
|
<item id='3300659945416e274474e469a1f0154c'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Ghostly Encounters</title>
|
|
<summary>
|
|
O all you host of heaven! O earth! what else?
|
|
And shall I couple hell? O, fie! Hold, hold, my heart;
|
|
And you, my sinews, grow not instant old,
|
|
But bear me stiffly up. Remember thee!
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32396</id>
|
|
<published>2003-12-12T23:21:34Z</published>
|
|
<updated>2003-12-12T23:21:34Z</updated>
|
|
</entry>
|
|
</item>
|
|
<item id='4e30f35051b7b8b42abe083742187228'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Alone</title>
|
|
<summary>
|
|
Now I am alone.
|
|
O, what a rogue and peasant slave am I!
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32396</id>
|
|
<published>2003-12-13T11:09:53Z</published>
|
|
<updated>2003-12-13T11:09:53Z</updated>
|
|
</entry>
|
|
</item>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>Even if the service or node does not support persistent items, it MAY return the last published item.</p>
|
|
<example caption='Service returns last published item'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>There are several reasons why the items retrieval request might fail:</p>
|
|
<ol>
|
|
<li>The requesting entity has multiple subscriptions to the node but does not specify a subscription ID.</li>
|
|
<li>The requesting entity is subscribed but specifies an invalid subscription ID.</li>
|
|
<li>The node does not return items to unsubscribed entities and the requesting entity is not subscribed.</li>
|
|
<li>The service or node does not support persistent items and does not return the last published item.</li>
|
|
<li>The service or node does not support item retrieval.</li>
|
|
<li>The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence.</li>
|
|
<li>The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups.</li>
|
|
<li>The node has an access model of "whitelist" and the requesting entity is not on the whitelist.</li>
|
|
<li>The service or node requires payment for item retrieval.</li>
|
|
<li>The requesting entity is blocked from retrieving items from the node (e.g., because having an affiliation of outcast).</li>
|
|
<li>The node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a &badrequest; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <subid-required/>.</p>
|
|
<example caption='Entity did not specify SubID'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<subid-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity is subscribed but specifies an invalid subscription ID, the service MUST return a ¬acceptable; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.</p>
|
|
<example caption='Entity specified invalid SubID'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<invalid-subid xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not return items to unsubscribed entities and the requesting entity is not subscribed (which includes having a pending subscription), the service MUST return a ¬authorized; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.</p>
|
|
<example caption='Entity is not subscribed'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<not-subscribed xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service or node does not support persistent items and does not return the last published item, the service MUST return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".</p>
|
|
<example caption='Persistent items not supported'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='persistent-items'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service or node does not support item retrieval (e.g., because the node is a collection node), the service MUST return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-items".</p>
|
|
<example caption='Item retrieval not supported'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='retrieve-items'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>For nodes with an access model of "presence", if the requesting entity is not subscribed to the owner's presence then the pubsub service MUST respond with a ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <presence-subscription-required/>.</p>
|
|
<example caption='Entity is not authorized to retrieve items (presence subscription required)'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<presence-subscription-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>For nodes with an access model of "roster", if the requesting entity is not in one of the authorized roster groups then the pubsub service MUST respond with a ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <not-in-roster-group/>.</p>
|
|
<example caption='Entity is not authorized to retrieve items (not in roster group)'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<not-in-roster-group xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <closed-node/>.</p>
|
|
<example caption='Node has whitelist access model'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<closed-node xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>Commercial deployments may wish to link subscribers to a database of paying customers. If the subscriber needs to provide payment in order to retrieve items from the node (e.g., if the subscriber is not in the customer database or the customer's account is not paid up), the service SHOULD return a &payment; error to the subscriber.</p>
|
|
<example caption='Payment is required to retrieve items'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<payment-required xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a &forbidden; error to the subscriber.</p>
|
|
<example caption='Requesting entity is blocked'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not exist, the service SHOULD return an ¬found; error to the subscriber.</p>
|
|
<example caption='Node does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>A service MAY allow entities to request the most recent N items by using the 'max_items' attribute. When max_items is used, implementations SHOULD return the N most recent (as opposed to the N oldest) items. (Note: A future version of this specification may recommend the use of &jep0059; instead of the 'max_items' attribute.)</p>
|
|
<example caption='Subscriber requests two most recent items'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='items2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings' max_items='2'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service returns two most recent items'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='items2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'>
|
|
<item id='4e30f35051b7b8b42abe083742187228'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Alone</title>
|
|
<summary>
|
|
Now I am alone.
|
|
O, what a rogue and peasant slave am I!
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32396</id>
|
|
<published>2003-12-13T11:09:53Z</published>
|
|
<updated>2003-12-13T11:09:53Z</updated>
|
|
</entry>
|
|
</item>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>The service MAY return event notifications without payloads (e.g., to conserve bandwidth). If so, the client MAY request a specific item (using the ItemID) in order to retrieve the payload. When an entity requests items by ItemID, implementations MUST allow multiple items to be specified in the request.</p>
|
|
<example caption='Subscriber requests specific items by ItemID'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='items3'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'>
|
|
<item id='368866411b877c30064a5f62b917cffe'/>
|
|
<item id='4e30f35051b7b8b42abe083742187228'/>
|
|
</items>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service sends requested item(s)'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
id='items3'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'>
|
|
<item id='368866411b877c30064a5f62b917cffe'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>The Uses of This World</title>
|
|
<summary>
|
|
O, that this too too solid flesh would melt
|
|
Thaw and resolve itself into a dew!
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32396</id>
|
|
<published>2003-12-12T17:47:23Z</published>
|
|
<updated>2003-12-12T17:47:23Z</updated>
|
|
</entry>
|
|
</item>
|
|
<item id='4e30f35051b7b8b42abe083742187228'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Alone</title>
|
|
<summary>
|
|
Now I am alone.
|
|
O, what a rogue and peasant slave am I!
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32396</id>
|
|
<published>2003-12-13T11:09:53Z</published>
|
|
<updated>2003-12-13T11:09:53Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If a subscription identifier is associated with a specific subscription, the service MUST require it so that it can generate different sets of items based on the subscription options associated with a specific subscription. Therefore the entity MUST include the 'subid' attribute with the items element when making the request; if it does not, the service MUST return a ¬acceptable; error, specifying a pubsub-specific error condition of <subid-required/>.</p>
|
|
<example caption='Subscriber sends request without SubID'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='items5'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='SubID required'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='items5'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<subid-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
|
|
</section1>
|
|
|
|
<section1 topic='Publisher Use Cases' anchor='publisher'>
|
|
<section2 topic='Publish an Item to a Node' anchor='publisher-publish'>
|
|
<p>Any entity which is allowed to publish items to a node (i.e., a publisher or an owner) may do so at any time by sending an IQ-set to the service containing a pubsub element with a <publish/> child; the <publish/> element MUST possess a 'node' attribute and depending on the node configuration MAY contain no &ITEM; elements, one &ITEM; element, or (for <link url='#impl-batch'>Batch Processing</link>) more than one &ITEM; element.</p>
|
|
<p>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 (as shown in the <link url='#intro-example'>Motivating Example</link> section of this document). 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.</p>
|
|
<example caption='Publisher publishes an item with an ItemID'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/blogbot'
|
|
to='pubsub.shakespeare.lit'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the pubsub service can successfully process the request, it MUST inform the publisher of success.</p>
|
|
<example caption='Service replies with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/blogbot'
|
|
id='publish1'/>
|
|
]]></example>
|
|
<p>If the pubsub service can successfully process the request, it 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).</p>
|
|
<p>Depending on the node configuration, the event notification either will or will not contain the payload, as shown in the following examples.</p>
|
|
<p>If the node is configured to include payloads, the subscribers will receive payloads with the event notifications.</p>
|
|
<example caption='Subscribers receive event notifications with payloads'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='horatio@denmark.lit' id='baz'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='marcellus@denmark.lit' id='fez'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Soliloquy</title>
|
|
<summary>
|
|
To be, or not to be: that is the question:
|
|
Whether 'tis nobler in the mind to suffer
|
|
The slings and arrows of outrageous fortune,
|
|
Or to take arms against a sea of troubles,
|
|
And by opposing end them?
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32397</id>
|
|
<published>2003-12-13T18:30:02Z</published>
|
|
<updated>2003-12-13T18:30:02Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
.
|
|
.
|
|
.
|
|
]]></example>
|
|
<p>If the node is configured to not include payloads, the subscribers will receive event notifications only. (If payloads are not included, subscribers may request the published item via the protocol defined in the <link url='#subscriber-retrieve'>Retrieve Items from a Node</link> section of this document.)</p>
|
|
<example caption='Subscribers receive event notifications only'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='horatio@denmark.lit' id='baz'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='marcellus@denmark.lit' id='fez'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
.
|
|
.
|
|
.
|
|
]]></example>
|
|
<p>If a single entity is subscribed to a node multiple times, the service SHOULD notate the event notification so that the entity can determine which subscription identifier(s) generated this event. If these notations are included, they MUST use the &jep0131; format and SHOULD be included after the event notification information (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='francisco@denmark.lit' id='foo'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</items>
|
|
</event>
|
|
<headers xmlns='http://jabber.org/protocol/shim'>
|
|
<header name='pubsub#subid'>123-abc</header>
|
|
<header name='pubsub#subid'>004-yyy</header>
|
|
</headers>
|
|
</message>
|
|
]]></example>
|
|
<p>There are several reasons why the publish request might fail:</p>
|
|
<ol>
|
|
<li>The requesting entity does not have sufficient privileges to publish.</li>
|
|
<li>The node does not support item publication.</li>
|
|
<li>The node does not exist.</li>
|
|
<li>The payload size exceeds a service-defined limit.</li>
|
|
<li>The item contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node.</li>
|
|
<li>The request does not match the node configuration.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>Note: If a publisher publishes an item with an Item ID and the ItemID matches that of an existing item, the pubsub service MUST NOT fail the publication but instead MUST overwrite the existing item and generate a new event notification (i.e., re-publication is equivalent to modification).</p>
|
|
<p>If the requesting entity does not have sufficient privileges to publish, the service MUST return a &forbidden; error.</p>
|
|
<example caption='Entity does not have sufficient privileges to publish to node'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... PAYLOAD ...
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not support item publication (because it is a <link url='#collections'>Collection Node</link>), the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "publish".</p>
|
|
<example caption='Node does not support item publication'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... PAYLOAD ...
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='publish'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity attempts to publish an item to a node that does not exist, the service MUST return an ¬found; error.</p>
|
|
<example caption='Entity attempts to publish to a non-existent node'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... PAYLOAD ...
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the payload size exceeds a service-defined limit, the service MUST return a ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <payload-too-big/>.</p>
|
|
<example caption='Entity attempts to publish very large payload'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... HUGE PAYLOAD ...
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<payload-too-big xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the &ITEM; element contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node, the service MUST bounce the request with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-payload/>.</p>
|
|
<example caption='Entity attempts to publish item with multiple payload elements or namespace does not match'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
... INVALID PAYLOAD ...
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<invalid-payload xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<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 <item-required/>.</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 <payload-required/>.</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 <item-forbidden/>.</li>
|
|
</ul>
|
|
<p>Examples of these errors are shown below.</p>
|
|
<example caption='Publisher attempts to publish to persistent node with no item'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<item-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Publisher attempts to publish to payload node with no payload'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</publish>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<payload-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Publisher attempts to publish to transient notification node with item'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</publish>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<item-forbidden xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>Finally, 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>
|
|
</section2>
|
|
|
|
<section2 topic='Delete an Item from a Node' anchor='publisher-delete'>
|
|
<p>A service SHOULD allow a publisher to delete an item once it has been published to a node that supports persistent items. To delete an item, the publisher sends a retract request as shown in the following examples. The <retract/> element MUST possess a 'node' attribute, MAY possess a 'notify' attribute, and SHOULD contain one &ITEM; element (but MAY contain more than one &ITEM; element for <link url='#impl-batch'>Batch Processing</link> of item retractions); the &ITEM; element MUST be empty and MUST possess an 'id' attribute.</p>
|
|
<example caption='Entity deletes an item from a node'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='retract1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<retract node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</retract>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service replies with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='retract1'/>
|
|
]]></example>
|
|
<p>There are several reasons why the item retraction request might fail:</p>
|
|
<ol>
|
|
<li>The publisher does not have sufficient privileges to delete the requested item.</li>
|
|
<li>The node or item does not exist.</li>
|
|
<li>The request does not specify a node.</li>
|
|
<li>The request does not include an &ITEM; element or the &ITEM; element does not specify an ItemID.</li>
|
|
<li>The node does not support persistent items.</li>
|
|
<li>The service does not support the deletion of items.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the requesting entity does not have sufficient privileges to delete the item, the service MUST return a &forbidden; error.</p>
|
|
<example caption='Requesting entity does not have sufficient privileges'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='retract1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<retract node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</retract>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node or item does not exist, the service MUST return an ¬found; error.</p>
|
|
<example caption='Non-existent node or item'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='retract1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<retract node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</retract>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the request does not specify a node, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <node-required/>.</p>
|
|
<example caption='Request does not specify a node'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='retract1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<retract/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<node-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the request does not include an &ITEM; element or the &ITEM; element does not specify an ItemID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <item-required/>.</p>
|
|
<example caption='Request does not specify an item'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='retract1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<retract node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<item-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not support persistent items (e.g., because it is a collection node or a transient node that does not deliver payloads), the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".</p>
|
|
<example caption='Node does not support persistent items'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='retract1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<retract node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</retract>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='persistent-items'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service does not support item deletion, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "delete-nodes".</p>
|
|
<example caption='Service does not support item deletion'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='retract1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<retract node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</retract>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='delete-nodes'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If none of the foregoing errors occurred, then the service MUST delete the item.</p>
|
|
<p>If none of the foregoing errors occurred and the <retract/> 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 <retract/> 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'>
|
|
<items node='princely_musings'>
|
|
<retract id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<retract id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
.
|
|
.
|
|
.
|
|
]]></example>
|
|
<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>
|
|
<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'>
|
|
<items node='princely_musings'>
|
|
<retract id='ae890ac52d0df67ed7cfdf51b644e901'/>
|
|
</items>
|
|
</event>
|
|
<headers xmlns='http://jabber.org/protocol/shim'>
|
|
<header name='pubsub#subid'>123-abc</header>
|
|
<header name='pubsub#subid'>004-yyy</header>
|
|
</headers>
|
|
</message>
|
|
]]></example>
|
|
</section2>
|
|
|
|
</section1>
|
|
|
|
<section1 topic='Owner Use Cases' anchor='owner'>
|
|
<section2 topic='Create a Node' anchor='owner-create'>
|
|
<section3 topic='General Considerations' anchor='owner-create-general'>
|
|
<p>A service SHOULD allow entities to create new nodes. However, a service MAY disallow creation of nodes based on the identity of the requesting entity, or MAY disallow node creation altogether (e.g., reserving that privilege to a service-wide administrator).</p>
|
|
<p>There are two ways to create a node:</p>
|
|
<ol>
|
|
<li>Create a node with default configuration for the specified node type.</li>
|
|
<li>Create and configure a node simultaneously.</li>
|
|
</ol>
|
|
<p>These methods, along with method-specific error conditions, are explained more fully in the following sections.</p>
|
|
<p>In addition to method-specific error conditions, there are several general reasons why the node creation request might fail:</p>
|
|
<ul>
|
|
<li>The service does not support node creation.</li>
|
|
<li>Only entities that are registered with the service are allowed to create nodes but the requesting entity is not registered.</li>
|
|
<li>The requesting entity does not have sufficient privileges to create nodes.</li>
|
|
<li>The requested NodeID already exists.</li>
|
|
<li>The request did not include a NodeID and "instant nodes" are not supported.</li>
|
|
</ul>
|
|
<p>These general error cases are described more fully below.</p>
|
|
<p>If the service does not support node creation, it MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "create-nodes".</p>
|
|
<example caption='Service does not support node creation'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='princely_musings'/>
|
|
<configure/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='create-nodes'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If only entities that are registered with the service may create nodes but the requesting entity has not yet registered, the service MUST respond with a ®istration; error.</p>
|
|
<example caption='Service requires registration'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='princely_musings'/>
|
|
<configure/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<registration-required xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity does not have sufficient privileges to create nodes, the service MUST respond with a &forbidden; error.</p>
|
|
<example caption='Requesting entity is prohibited from creating nodes'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='princely_musings'/>
|
|
<configure/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requested NodeID already exists, the service MUST respond with a &conflict; error.</p>
|
|
<example caption='NodeID already exists'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='princely_musings'/>
|
|
<configure/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node creator does not specify a NodeID but the service does not support instant nodes, the service MUST return a ¬acceptable; error, specifying a pubsub-specific error condition of <nodeid-required/>.</p>
|
|
<example caption='Service does not support instant nodes'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create/>
|
|
<configure/>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<nodeid-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node creator does not specify a NodeID but the service supports instant nodes, the service SHOULD generate a NodeID that is unique within the context of the service on behalf of the node creator.</p>
|
|
<example caption='Entity requests an instant node'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='create2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create/>
|
|
<configure/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no error occurs, the pubsub service SHOULD create the node, generate a NodeID that is unique within the context of that service, and inform the user of success (including the NodeID in the response).</p>
|
|
<example caption='Service replies with success and generated NodeID'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='25e3d37dabbab9541f7523321421edc5bfeb2dae'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>Note: When a service successfully creates a node on behalf of the requesting entity, it MUST return an IQ result. If the node creation request did not specify a NodeID and the service supports creation of instant nodes, the service MUST specify the created NodeID in the IQ result. Similarly, if the node creation request specified a NodeID but the service modified the NodeID before creating the node as described in the <link url='#collections'>Collection Nodes</link> section of this document, the service MUST also specify the modified node in the IQ result. In all other cases, the service MUST NOT specify the NodeID in the IQ result (since the node creator can determine which node was created by tracking the 'id' attribute that it specified for the IQ-set).</p>
|
|
</section3>
|
|
<section3 topic='Create a Node With Default Configuration' anchor='owner-create-default'>
|
|
<p>As explained above, each node type has its own default configuration. By asking the service to create a node with default configuration, the node creator accepts the default configuration. If the service allows node configuration, the owner may reconfigure the node after creating the node (as described in the <link url='#owner-configure'>Configure a Node</link> section of this document). In addition, a service MAY allow entities to determine the default configuration options for a given node type before creating a node (as described in the <link url='#owner-default'>Request Default Configurations</link> section of this document).</p>
|
|
<p>In order to create a node with default configuration, the node creator MUST include an empty <configure/> child element in the creation request. The node creator MAY specify values for the 'pubsub#node_type' and 'pubsub#access_model' configuration fields or MAY accept the defaults, which are "leaf" for the 'pubsub#node_type' field and the value represented by the 'pubsub#access_model' field (i.e., "authorize", "open", "presence", "roster", or "whitelist").</p>
|
|
<p>In the following example, the node creator requests a leaf node (the default type) with an open access model (assumed to be the default type for this service).</p>
|
|
<example caption='Entity requests leaf node with (default) open access model'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='create1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='princely_musings'/>
|
|
<configure/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>In order to request an access model other than the default for the service, the node creator MUST include a Data Form in the node creation request that specifies a non-default value for the 'pubsub#node_type' field.</p>
|
|
<example caption='Entity requests leaf node with non-default access model'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='create2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='princely_musings'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#access_model'><value>whitelist</value></field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the access model is supported and none of the general or method-specific errors has occurred, the service SHOULD create the node and inform the requesting entity of success.</p>
|
|
<example caption='Service informs requesting entity of success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create1'/>
|
|
]]></example>
|
|
<p>If service does not support the specified access model, it MUST return a ¬acceptable; error, specifying a pubsub-specific error condition of <unsupported-access-model/>.</p>
|
|
<example caption='Service does not support specified access model'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='princely_musings'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#access_model'><value>whitelist</value></field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported-access-model xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>(For error handling if the service does not support the specified node type, see the <link url='#collections'>Collection Node</link> section of this document.)</p>
|
|
</section3>
|
|
<section3 topic='Create and Configure a Node' anchor='owner-create-and-configure'>
|
|
<p>If an implementation allows node configuration (see the <link url='#owner-configure'>Configure a Node</link> section of this document), it SHOULD allow node creation requests to contain the desired node configuration in the node creation request.</p>
|
|
<p>Note: The <configure/> element MUST follow the <create/> element and MUST NOT possess a 'node' attribute, since the value of the <create/> element's 'node' attribute specifies the desired NodeID; if any of these rules are violated, the service MUST return a &badrequest; error.</p>
|
|
<example caption='Entity requests a new node with non-default configuration.'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='create1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='princely_musings'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#title'><value>Princely Musings (Atom)</value></field>
|
|
<field var='pubsub#deliver_notifications'><value>1</value></field>
|
|
<field var='pubsub#deliver_payloads'><value>1</value></field>
|
|
<field var='pubsub#persist_items'><value>1</value></field>
|
|
<field var='pubsub#max_items'><value>10</value></field>
|
|
<field var='pubsub#access_model'><value>open</value></field>
|
|
<field var='pubsub#publish_model'><value>publishers</value></field>
|
|
<field var='pubsub#send_last_published_item'><value>never</value></field>
|
|
<field var='pubsub#presence_based_delivery'><value>false</value></field>
|
|
<field var='pubsub#notify_config'><value>0</value></field>
|
|
<field var='pubsub#notify_delete'><value>0</value></field>
|
|
<field var='pubsub#notify_retract'><value>0</value></field>
|
|
<field var='pubsub#max_payload_size'><value>1028</value></field>
|
|
<field var='pubsub#type'><value>http://www.w3.org/2005/Atom</value></field>
|
|
<field var='pubsub#body_xslt'>
|
|
<value>http://jabxslt.jabberstudio.org/atom_body.xslt</value>
|
|
</field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service replies with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='create1'/>
|
|
]]></example>
|
|
<p>If a service supports this "create-and-configure" feature, it MUST advertise that fact by returning a feature of "http://jabber.org/protocol/pubsub#create-and-configure" in response to service discovery information requests. If the create-and-configure option is not supported but the requesting entity sends such a request anyway, the service SHOULD ignore the configuration part of the request and proceed as if it had not been included.</p>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic='Configure a Node' anchor='owner-configure'>
|
|
<p>After creating a new node, the node owner may want to modify the node configuration. The process for doing so is shown below.</p>
|
|
<example caption='Owner requests configuration form'><![CDATA[
|
|
<iq type='get'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>Note: The following example shows some of the possible configuration options that MAY be provided. If an implementation implements these features using the <strong>Data Forms</strong> protocol, that implementation MUST use the fields that are registered with the Jabber Registrar in association with the 'http://jabber.org/protocol/pubsub' namespace (a preliminary representation of those field variables is shown below and in the <link url='#registrar-formtypes-config'>pubsub#node_config FORM_TYPE</link> section of this document, but MUST NOT be construed as canonical, since the Jabber Registrar may standardize additional fields at a later date without changes to this document). An implementation MAY choose to specify different labels, values, and even field types, but MUST conform to the defined variable naming scheme.</p>
|
|
<example caption='Service responds with configuration form'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#title' type='text-single'
|
|
label='A friendly name for the node'/>
|
|
<field var='pubsub#deliver_notifications' type='boolean'
|
|
label='Whether to deliver event notifications'>
|
|
<value>true</value>
|
|
</field>
|
|
<field var='pubsub#deliver_payloads' type='boolean'
|
|
label='Whether to deliver payloads with event notifications'>
|
|
<value>true</value>
|
|
</field>
|
|
<field var='pubsub#notify_config' type='boolean'
|
|
label='Notify subscribers when the node configuration changes'>
|
|
<value>0</value>
|
|
</field>
|
|
<field var='pubsub#notify_delete' type='boolean'
|
|
label='Notify subscribers when the node is deleted'>
|
|
<value>false</value>
|
|
</field>
|
|
<field var='pubsub#notify_retract' type='boolean'
|
|
label='Notify subscribers when items are removed from the node'>
|
|
<value>false</value>
|
|
</field>
|
|
<field var='pubsub#persist_items' type='boolean'
|
|
label='Persist items to storage'>
|
|
<value>1</value>
|
|
</field>
|
|
<field var='pubsub#max_items' type='text-single'
|
|
label='Max # of items to persist'>
|
|
<value>10</value>
|
|
</field>
|
|
<field var='pubsub#subscribe' type='boolean'
|
|
label='Whether to allow subscriptions'>
|
|
<value>1</value>
|
|
</field>
|
|
<field var='pubsub#access_model' type='list-single'
|
|
label='Specify the subscriber model'>
|
|
<option><value>authorize</value></option>
|
|
<option><value>open</value></option>
|
|
<option><value>presence</value></option>
|
|
<option><value>roster</value></option>
|
|
<option><value>whitelist</value></option>
|
|
<value>open</value>
|
|
</field>
|
|
<field var='pubsub#roster_groups_allowed' type='list-multi'
|
|
label='Roster groups allowed to subscribe'>
|
|
<option><value>friends</value></option>
|
|
<option><value>courtiers</value></option>
|
|
<option><value>servants</value></option>
|
|
<option><value>enemies</value></option>
|
|
</field>
|
|
<field var='pubsub#publish_model' type='list-single'
|
|
label='Specify the publisher model'>
|
|
<option><value>publishers</value></option>
|
|
<option><value>subscribers</value></option>
|
|
<option><value>open</value></option>
|
|
<value>publishers</value>
|
|
</field>
|
|
<field var='pubsub#max_payload_size' type='text-single'
|
|
label='Max Payload size in bytes'>
|
|
<value>1028</value>
|
|
</field>
|
|
<field var='pubsub#send_last_published_item' type='list-single'
|
|
label='Deliver notifications only to available users'>
|
|
<option label='Never'><value>never</value></option>
|
|
<option label='When a new subscription is processed'><value>on_sub</value></option>
|
|
<option label='When a new subscription is processed and whenever a subscriber comes online'>
|
|
<value>on_sub_and_presence</value>
|
|
</option>
|
|
<value>never</value>
|
|
</field>
|
|
<field var='pubsub#presence_based_delivery' type='boolean'
|
|
label='Deliver notifications only to available users'>
|
|
<value>0</value>
|
|
</field>
|
|
<field var='pubsub#type' type='text-single'
|
|
label='Specify the type of payload data to be provided at this node'>
|
|
<value>http://www.w3.org/2005/Atom</value>
|
|
</field>
|
|
<field var='pubsub#dataform_xslt' type='text-single'
|
|
label='Payload XSLT'/>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>There are several reasons why the node configuration request might fail:</p>
|
|
<ol>
|
|
<li>The service does not support node configuration.</li>
|
|
<li>The requesting entity does not have sufficient privileges to configure the node.</li>
|
|
<li>The request did not specify a node.</li>
|
|
<li>The node has no configuration options.</li>
|
|
<li>The specified node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the service does not support node configuration, the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "config-node".</p>
|
|
<example caption='Service does not support node configuration'><![CDATA[
|
|
<iq type='error'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='config-node'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity does not have sufficient privileges to configure the node, the service MUST respond with a &forbidden; error.</p>
|
|
<example caption='Requesting entity is prohibited from configuring this node'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the request did not specify a node, the service SHOULD return a &badrequest; error. It is possible that by not including a NodeID, the requesting entity is asking to configure the root node; however, if the requesting entity is not a service-level admin, it makes sense to return &badrequest; instead of &forbidden;.</p>
|
|
<example caption='Request did not specify a node'><![CDATA[
|
|
<iq type='error'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<nodeid-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no configuration options are available (e.g., because node configuration is "locked down"), the service MUST return a ¬allowed; error to the owner.</p>
|
|
<example caption='Node has no configuration options'><![CDATA[
|
|
<iq type='error'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not exist, the service MUST return an ¬found; error.</p>
|
|
<example caption='Node does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>After receiving the configuration form, the owner SHOULD submit a completed configuration form.</p>
|
|
<example caption='Owner submits node configuration form'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='config2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#title'><value>Princely Musings (Atom)</value></field>
|
|
<field var='pubsub#deliver_notifications'><value>1</value></field>
|
|
<field var='pubsub#deliver_payloads'><value>1</value></field>
|
|
<field var='pubsub#persist_items'><value>1</value></field>
|
|
<field var='pubsub#max_items'><value>10</value></field>
|
|
<field var='pubsub#access_model'><value>open</value></field>
|
|
<field var='pubsub#publish_model'><value>publishers</value></field>
|
|
<field var='pubsub#send_last_published_item'><value>never</value></field>
|
|
<field var='pubsub#presence_based_delivery'><value>false</value></field>
|
|
<field var='pubsub#notify_config'><value>0</value></field>
|
|
<field var='pubsub#notify_delete'><value>0</value></field>
|
|
<field var='pubsub#notify_retract'><value>0</value></field>
|
|
<field var='pubsub#max_payload_size'><value>1028</value></field>
|
|
<field var='pubsub#type'><value>http://www.w3.org/2005/Atom</value></field>
|
|
<field var='pubsub#body_xslt'>
|
|
<value>http://jabxslt.jabberstudio.org/atom_body.xslt</value>
|
|
</field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service replies with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='config2'/>
|
|
]]></example>
|
|
<p>Alternatively, the owner MAY cancel the configuration process, in which case the existing configuration MUST be applied.</p>
|
|
<example caption='Owner cancels configuration process'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='config2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'>
|
|
<x xmlns='jabber:x:data' type='cancel'/>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<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 ¬acceptable; error to the owner.</p>
|
|
<example caption='Configuration change cannot be processed'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='config2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<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 <link url='#collection'>Collection Nodes</link>.) If the node configuration is set to event notifications only, the notification MUST consist of an empty <configuration/> element whose 'node' attribute is set to the NodeID of the node; if the node configuration is set to full payloads, the <configuration/> 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'>
|
|
<configuration node='princely_musings'/>
|
|
</event>
|
|
</message>
|
|
]]></example>
|
|
<example caption='Service sends configuration change notification (full payload)'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<configuration node='princely_musings'>
|
|
<x xmlns='jabber:x:data' type='result'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#title'><value>Princely Musings (Atom)</value></field>
|
|
<field var='pubsub#deliver_notifications'><value>1</value></field>
|
|
<field var='pubsub#deliver_payloads'><value>1</value></field>
|
|
<field var='pubsub#notify_config'><value>0</value></field>
|
|
<field var='pubsub#notify_delete'><value>0</value></field>
|
|
<field var='pubsub#notify_retract'><value>0</value></field>
|
|
<field var='pubsub#persist_items'><value>1</value></field>
|
|
<field var='pubsub#max_items'><value>10</value></field>
|
|
<field var='pubsub#subscribe'><value>1</value></field>
|
|
<field var='pubsub#access_model'><value>open</value></field>
|
|
<field var='pubsub#publish_model'><value>publishers</value></field>
|
|
<field var='pubsub#max_payload_size'><value>9216</value></field>
|
|
<field var='pubsub#send_last_published_item'><value>never</value></field>
|
|
<field var='pubsub#presence_based_delivery'><value>0</value></field>
|
|
<field var='pubsub#type'><value>http://www.w3.org/2005/Atom</value></field>
|
|
<field var='pubsub#body_xslt'>
|
|
<value>http://jabxslt.jabberstudio.org/atom_body.xslt</value>
|
|
</field>
|
|
</x>
|
|
</configuration>
|
|
</event>
|
|
</message>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Request Default Configuration Options' anchor='owner-default'>
|
|
<p>A service MAY allow entities to determine the default node configuration for new nodes created on the service, in order to help entities determine whether they want to perform create-and-configure as previously described. To get the options, the entity MUST send an empty <default/> element to the service with no NodeID; in response, the service SHOULD return the default node options.</p>
|
|
<example caption='Entity requests default configuration options'><![CDATA[
|
|
<iq type='get'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='def1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<default/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with default configuration options'><![CDATA[
|
|
<iq type='result'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
id='def1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<default>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#title' type='text-single'
|
|
label='A friendly name for the node'/>
|
|
<field var='pubsub#deliver_notifications' type='boolean'
|
|
label='Deliver event notifications'>
|
|
<value>true</value>
|
|
</field>
|
|
<field var='pubsub#deliver_payloads' type='boolean'
|
|
label='Deliver payloads with event notifications'>
|
|
<value>1</value>
|
|
</field>
|
|
<field var='pubsub#notify_config' type='boolean'
|
|
label='Notify subscribers when the node configuration changes'>
|
|
<value>0</value>
|
|
</field>
|
|
<field var='pubsub#notify_delete' type='boolean'
|
|
label='Notify subscribers when the node is deleted'>
|
|
<value>0</value>
|
|
</field>
|
|
<field var='pubsub#notify_retract' type='boolean'
|
|
label='Notify subscribers when items are removed from the node'>
|
|
<value>0</value>
|
|
</field>
|
|
<field var='pubsub#persist_items' type='boolean'
|
|
label='Persist items to storage'>
|
|
<value>1</value>
|
|
</field>
|
|
<field var='pubsub#max_items' type='text-single'
|
|
label='Max # of items to persist'>
|
|
<value>10</value>
|
|
</field>
|
|
<field var='pubsub#subscribe' type='boolean'
|
|
label='Whether to allow subscriptions'>
|
|
<value>1</value>
|
|
</field>
|
|
<field var='pubsub#access_model' type='list-single'
|
|
label='Specify the subscriber model'>
|
|
<option><value>authorize</value></option>
|
|
<option><value>open</value></option>
|
|
<option><value>presence</value></option>
|
|
<option><value>roster</value></option>
|
|
<option><value>whitelist</value></option>
|
|
<value>open</value>
|
|
</field>
|
|
<field var='pubsub#roster_groups_allowed' type='list-multi'
|
|
label='Roster groups allowed to subscribe'>
|
|
<option><value>friends</value></option>
|
|
<option><value>courtiers</value></option>
|
|
<option><value>servants</value></option>
|
|
<option><value>enemies</value></option>
|
|
</field>
|
|
<field var='pubsub#publish_model' type='list-single'
|
|
label='Specify the publisher model'>
|
|
<option><value>publishers</value></option>
|
|
<option><value>subscribers</value></option>
|
|
<option><value>open</value></option>
|
|
<value>publishers</value>
|
|
</field>
|
|
<field var='pubsub#max_payload_size' type='text-single'
|
|
label='Max payload size in bytes'>
|
|
<value>9216</value>
|
|
</field>
|
|
<field var='pubsub#send_last_published_item' type='list-single'
|
|
label='Deliver notifications only to available users'>
|
|
label='When to send the last published item'>
|
|
<option label='Never'><value>never</value></option>
|
|
<option label='When a new subscription is processed'><value>on_sub</value></option>
|
|
<option label='When a new subscription is processed and whenever a subscriber comes online'>
|
|
<value>on_sub_and_presence</value>
|
|
</option>
|
|
<value>never</value>
|
|
</field>
|
|
<field var='pubsub#presence_based_delivery' type='boolean'
|
|
label='Deliver notifications only to available users'>
|
|
<value>0</value>
|
|
</field>
|
|
</x>
|
|
</default>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>There are several reasons why the default node configuration options request might fail:</p>
|
|
<ol>
|
|
<li>The service does not support node configuration.</li>
|
|
<li>The service does not support retrieval of default node configuration.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the service does not support node configuration, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "config-node".</p>
|
|
<example caption='Service does not support node configuration'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='def1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<default/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='config-node'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service does not support retrieval of default node configuration options, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-default".</p>
|
|
<example caption='Service does not support retrieval of default configuration options'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='def1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<default/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='retrieve-default'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>The default configuration options may be different for a collection node vs. a leaf node. In order to specifically request the default configuration options for collection nodes, an entity MUST include a Data Form with a 'pubsub#node_type' field whose value is "collection" in the request (since the default value for the 'pubsub#node_type' field is "leaf").</p>
|
|
<example caption='Entity requests default configuration options for collection nodes'><![CDATA[
|
|
<iq type='get'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
id='def2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<default>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#node_type'><value>collection</value></field>
|
|
</x>
|
|
</default>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service does not support collection nodes, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".</p>
|
|
<example caption='Service does not support collection nodes'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='def2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<default>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#node_type'><value>collection</value></field>
|
|
</x>
|
|
</default>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='collections'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Delete a Node' anchor='owner-delete'>
|
|
<p>If a service supports node creation, it MUST support node deletion. If an implementation persists items, it MUST remove all items from persistent storage before the node itself is deleted.</p>
|
|
<p>In order to delete a node, a node owner MUST send a node deletion request, consisting of a <delete/> element whose 'node' attribute specifies the NodeID of the node to be deleted.</p>
|
|
<example caption='Owner deletes a node'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='delete1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<delete node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no error occurs, the service MUST inform the owner of success.</p>
|
|
<example caption='Service replies with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
id='delete1'/>
|
|
]]></example>
|
|
<p>In addition, the service MUST also send notification of node deletion to all subscribers (which SHOULD include pending and unconfigured subscriptions).</p>
|
|
<example caption='Subscribers are notified of node deletion'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<delete node='princely_musings'/>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<delete node='princely_musings'/>
|
|
</event>
|
|
</message>
|
|
|
|
.
|
|
.
|
|
.
|
|
]]></example>
|
|
<p>There are several reasons why the node deletion request might fail:</p>
|
|
<ol>
|
|
<li>The requesting entity does not have sufficient privileges to delete the node.</li>
|
|
<li>The node is the root collection node, which cannot be deleted.</li>
|
|
<li>The specified node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the requesting entity does not have sufficient privileges to delete the node (e.g., is not an owner), the service MUST return a &forbidden; error.</p>
|
|
<example caption='Entity is not an owner'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='delete1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<delete node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity attempts to delete the root collection node, the service MUST return a ¬allowed; error.</p>
|
|
<example caption='Node is the root'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='delete1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<delete/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity attempts to delete a node that does not exist, the service MUST return an ¬found; error.</p>
|
|
<example caption='Owner attempts to delete a non-existent node'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='delete1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<delete node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the deleted node is a <link url='#collections'>Collection Node</link>, the implementation MAY associate the "orphaned" leaf nodes with the root collection node or associate them with no collection node.</p>
|
|
</section2>
|
|
<section2 topic='Purge All Node Items' anchor='owner-purge'>
|
|
<p>If a service persists published items, it MAY enable node owners to purge the node of all published items (thus removing all items from the persistent store, with the exception of the last published item, which MAY be cached). In order to purge a node of all items, a node owner MUST send a node purge request, consisting of a <purge/> element whose 'node' attribute specifies the NodeID of the node to be purged.</p>
|
|
<example caption='Owner purges all items from a node'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<purge node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no error occurs, the service MUST purge the node and inform the owner of success.</p>
|
|
<example caption='Service replies with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
id='purge1'/>
|
|
]]></example>
|
|
<p>If the node or service has been configured to notify subscribers on deletion of items, a purge request MUST NOT result in sending the same notifications as are sent when deleting items (since purging a node with many persisted items could result in a large number of notifications); instead, the node MUST send a single notification to each subscriber, containing an empty <purge/> child element.</p>
|
|
<example caption='Subscribers are notified of node purge'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<purge node='princely_musings'/>
|
|
</event>
|
|
</message>
|
|
|
|
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<purge node='princely_musings'/>
|
|
</event>
|
|
</message>
|
|
|
|
.
|
|
.
|
|
.
|
|
]]></example>
|
|
<p>There are several reasons why the node purge request might fail:</p>
|
|
<ol>
|
|
<li>The node or service does not support node purging.</li>
|
|
<li>The requesting entity does not have sufficient privileges to purge the node.</li>
|
|
<li>The node is not configured to persist items.</li>
|
|
<li>The specified node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the node or service does not support node purging, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "purge-nodes".</p>
|
|
<example caption='Service does not support node purging'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<purge node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='purge-nodes'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity does not have sufficient privileges to purge the node (e.g., because it is not a node owner), the service MUST return a &forbidden; error.</p>
|
|
<example caption='Entity is not an owner'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<purge node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service or node does not persist items (e.g., because the node is a collection node), it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".</p>
|
|
<example caption='Node is not configured for persistent items'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<purge node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='persistent-items'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not exist, the service MUST return an ¬found; error.</p>
|
|
<example caption='Node does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<purge node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic='Manage Subscription Requests' anchor='owner-subreq'>
|
|
<p>A service MAY send subscription approval requests to the node owner(s) at any time. An approval request consists of a message stanza containing a Data Form scoped by the "http://jabber.org/protocol/pubsub#subscribe_authorization" FORM_TYPE. The form MUST contain a boolean field that has a 'var' attribute of "pubsub#allow", which is the field that designates whether or not to allow the subscription request. The form SHOULD include fields that specify the node identifier, the subscription id (if applicable), and the JID of the pending subscriber. The message MAY include a &BODY; element that contains natural-language text explaining that the message contains a pending subscription form.</p>
|
|
<example caption='Service sends authorization request to node owner'><![CDATA[
|
|
<message to='hamlet@denmark.lit' from='pubsub.shakespeare.lit' id='approve1'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<title>PubSub subscriber request</title>
|
|
<instructions>
|
|
To approve this entity's subscription request,
|
|
click the OK button. To deny the request, click the
|
|
cancel button.
|
|
</instructions>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_authorization</value>
|
|
</field>
|
|
<field var='pubsub#subid' type='hidden'><value>123-abc</value></field>
|
|
<field var='pubsub#node' type='text-single' label='Node ID'>
|
|
<value>princely_musings</value>
|
|
</field>
|
|
<field var='pusub#subscriber_jid' type='jid-single' label='Subscriber Address'>
|
|
<value>horatio@denmark.lit</value>
|
|
</field>
|
|
<field var='pubsub#allow' type='boolean'
|
|
label='Allow this JID to subscribe to this pubsub node?'>
|
|
<value>false</value>
|
|
</field>
|
|
</x>
|
|
</message>
|
|
]]></example>
|
|
<p>In order to approve the request, the owner shall submit the form and set the "pubsub#allow" field to a value of "1" or "true"; for tracking purposes the message MUST reflect the 'id' attribute originally provided.</p>
|
|
<example caption='Owner approves subscription request'><![CDATA[
|
|
<message from='hamlet@denmark.lit/elsinore' to='pubsub.shakespeare.lit' id='approve1'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_authorization</value>
|
|
</field>
|
|
<field var='pubsub#subid'>
|
|
<value>123-abc</value>
|
|
</field>
|
|
<field var='pubsub#node'>
|
|
<value>princely_musings</value>
|
|
</field>
|
|
<field var='pubsub#subscriber_jid'>
|
|
<value>horatio@denmark.lit</value>
|
|
</field>
|
|
<field var='pubsub#allow'>
|
|
<value>true</value>
|
|
</field>
|
|
</x>
|
|
</message>
|
|
]]></example>
|
|
<p>The service then SHOULD send notification to the approved subscriber (see the <link url='#impl-subchange'>Notification of Subscription State Changes</link> section of this document).</p>
|
|
<example caption='Subscription approval notification'><![CDATA[
|
|
<message
|
|
from='pubsub.shakespeare.lit'
|
|
to='horatio@denmark.lit'
|
|
id='approvalnotify1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription node='princely_musings' jid='horatio@denmark.lit' subscription='subscribed'/>
|
|
</pubsub>
|
|
</message>
|
|
]]></example>
|
|
<p>In order to deny the request, the owner shall submit the form and set the "pubsub#allow" field to a value of "0" or "false"; as above, the message MUST reflect the 'id' attribute originally provided.</p>
|
|
<example caption='Owner denies subscription request'><![CDATA[
|
|
<message from='hamlet@denmark.lit/elsinore' to='pubsub.shakespeare.lit' id='approve1'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_authorization</value>
|
|
</field>
|
|
<field var='pubsub#subid'>
|
|
<value>123-abc</value>
|
|
</field>
|
|
<field var='pubsub#node'>
|
|
<value>princely_musings</value>
|
|
</field>
|
|
<field var='pubsub#subscriber_jid'>
|
|
<value>horatio@denmark.lit</value>
|
|
</field>
|
|
<field var='pubsub#allow'>
|
|
<value>false</value>
|
|
</field>
|
|
</x>
|
|
</message>
|
|
]]></example>
|
|
<p>The service then SHOULD send notification to the denied subscriber (see the <link url='#impl-subchange'>Notification of Subscription State Changes</link> section of this document).</p>
|
|
<example caption='Subscription cancellation / denial notification'><![CDATA[
|
|
<message
|
|
from='pubsub.shakespeare.lit'
|
|
to='horatio@denmark.lit'
|
|
id='unsubnotify1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription node='princely_musings' jid='horatio@denmark.lit' subscription='none'/>
|
|
</pubsub>
|
|
</message>
|
|
]]></example>
|
|
<p>In order to cancel the form submission, the owner shall reply with the form's 'type' attribute set to "cancel".</p>
|
|
<example caption='Owner cancels form submission'><![CDATA[
|
|
<message from='hamlet@denmark.lit/elsinore' to='pubsub.shakespeare.lit' id='approve1'>
|
|
<x xmlns='jabber:x:data' type='cancel'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_authorization</value>
|
|
</field>
|
|
</x>
|
|
</message>
|
|
]]></example>
|
|
<p>The service MUST check the "pubsub#allow" field to see if the subscription should be allowed or denied. If the owner cancels the Data Form, then the subscription request MUST remain in the pending state.</p>
|
|
<section3 topic='Request All Pending Subscription Requests' anchor='owner-subreq-all'>
|
|
<p>A service MAY allow owners to request all the current pending subscription requests for all of their nodes at the service. Implementations MUST use the &jep0050; protocol to provide this functionality. The command name ('node' attribute of the command element) MUST have a value of "http://jabber.org/protocol/pubsub#get-pending".</p>
|
|
<example caption='Owner requests pending subscription requests'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='pending1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='http://jabber.org/protocol/pubsub#get-pending'
|
|
action='execute'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no error occurs, the service SHOULD return a data form for managing subscription requests, which MUST contain a single field with a 'var' attribute value of "node" whose <option/> elements specify the nodes for which the requesting entity has subscription approval privileges (as an optimization, the service MAY specify only the nodes that have subscription requests pending).</p>
|
|
<example caption='Service responds with data form to be populated'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='pending1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
sessionid='pubsub-get-pending:20031021T150901Z-600'
|
|
node='http://jabber.org/protocol/pubsub#get-pending'
|
|
status='executing'
|
|
action='execute'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field type='list-single' var='pubsub#node'>
|
|
<option><value>princely_musings</value></option>
|
|
<option><value>news_from_elsinore</value></option>
|
|
</field>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<p>There are several reasons why the pending subscription approval request might fail:</p>
|
|
<ol>
|
|
<li>The service does not support the ad-hoc commands protocol.</li>
|
|
<li>The service supports ad-hoc commands but does not support the "get-pending" feature.</li>
|
|
<li>The requesting entity does not have sufficient privileges to approve subscription requests.</li>
|
|
<li>The specified node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the service does not support the ad-hoc commands protocol, it MUST respond with a &unavailable; error.</p>
|
|
<example caption='Service responds with node not found'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='pending1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='http://jabber.org/protocol/pubsub#get-pending'
|
|
action='execute'/>
|
|
<error type='cancel'>
|
|
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service does not support the "get-pending" feature, it MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "get-pending".</p>
|
|
<example caption='Service responds with node not found'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='pending1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='http://jabber.org/protocol/pubsub#get-pending'
|
|
action='execute'/>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='get-pending'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity does not have sufficient privileges to approve subscription requests, the service MUST respond with a &forbidden; error.</p>
|
|
<example caption='Entity does not have sufficient privileges to approve subscription requests'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='pending1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='http://jabber.org/protocol/pubsub#get-pending'
|
|
action='execute'/>
|
|
<error type='cancel'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requested node does not exist, the service MUST respond with an ¬found; error.</p>
|
|
<example caption='Service responds with node not found'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='pending1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='http://jabber.org/protocol/pubsub#get-pending'
|
|
action='execute'/>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>Upon receiving the data form for managing subscription requests, the owner then MAY request pending subscription approval requests for a given node.</p>
|
|
<example caption='Owner requests all pending subscription requests for a node'><![CDATA[
|
|
<iq type='set' to='pubsub.shakespeare.lit' id='pending2'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
sessionid='pubsub-get-pending:20031021T150901Z-600'
|
|
node='http://jabber.org/protocol/pubsub#get-pending'
|
|
action='execute'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='pubsub#node'>
|
|
<value>princely_musings</value>
|
|
</field>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no error occurs, the service shall respond with success.</p>
|
|
<example caption='Service responds with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='pending2'/>
|
|
]]></example>
|
|
<p>The service shall then send one subscription approval message for each pending subscription request, as shown above for a single pending subscription request.</p>
|
|
<p>Note: A service SHOULD conform to its affiliation policies in maintaining the list of pending subscriptions. In particular, if the affiliation of an entity with a pending subscription is modified to owner or publisher, the service SHOULD automatically approve the subscription request and remove the entity's previous request from the pending list. Similarly, if the affiliation of an entity with a pending subscription is modified to outcast, the service SHOULD automatically reject the subscription request and remove the entity's previous request from the pending list.</p>
|
|
<p>If an entity's subscription request is denied, the service SHOULD send a &MESSAGE; to the entity, where the message conforms to the format described in the <link url='#impl-unsub'>Notification of Subscription Denial or Cancellation</link> section of this document.</p>
|
|
</section3>
|
|
</section2>
|
|
|
|
<section2 topic='Manage Subscriptions' anchor='owner-subscriptions'>
|
|
<p>A service MAY allow a node owner to edit the list of subscriptions associated with a given node and to set subscriptions for new entities (for nodes of type "whitelist", this enables the node owner to add subscribers); if so, it MUST advertise support for the "pubsub#manage-subscriptions" feature.</p>
|
|
<p>In order to request a list of all subscriptions, a node owner MUST send a subscriptions request, consisting of a <subscriptions/> element whose 'node' attribute specifies the NodeID of the relevant node.</p>
|
|
<example caption='Owner requests all subscriptions'><![CDATA[
|
|
<iq type='get'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='subman1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<subscriptions node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no error occurs, the service MUST return the list of subscriptions for entities whose subscription state is "subscribed" or "unconfigured" (it MUST NOT return entities whose subscription state is "none" and SHOULD NOT return entities whose subscription state is "pending"). The result MAY specify multiple <subscription/> elements for the same entity (JID), but each element MUST possess a distinct value of the 'subid' attribute (as shown below).</p>
|
|
<example caption='Service returns list of subscriptions'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='subman1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<subscriptions node='princely_musings'>
|
|
<subscription jid='hamlet@denmark.lit' subscription='subscribed'/>
|
|
<subscription jid='polonius@denmark.lit' subscription='unconfigured'/>
|
|
<subscription jid='bernardo@denmark.lit' subscription='subscribed' subid='123-abc'/>
|
|
<subscription jid='bernardo@denmark.lit' subscription='subscribed' subid='004-yyy'/>
|
|
</subscriptions>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>There are several reasons why the manage subscriptions request might fail:</p>
|
|
<ol>
|
|
<li>The service does not support subscription management.</li>
|
|
<li>The requesting entity does not have sufficient privileges to manage subscriptions.</li>
|
|
<li>The specified node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If an implementation does not support subscription management, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "manage-subscriptions".</p>
|
|
<example caption='Node or service does not support subscription management'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<subscriptions node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='manage-subscriptions'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p>
|
|
<example caption='Entity is not an owner'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='subman1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<subscriptions node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not exist, the service MUST return an ¬found; error.</p>
|
|
<example caption='Node does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<subscriptions node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>Upon receiving the subscriptions list, the node owner MAY modify subscription states. The owner MUST send only modified subscription states (i.e., a "delta"), not the complete list. (Note: If the 'subscription' attribute is not specified in a modification request, then the value MUST NOT be changed.)</p>
|
|
<example caption='Owner modifies subscriptions'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='subman2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<subscriptions node='princely_musings'/>
|
|
<subscription jid='bard@shakespeare.lit' subscription='subscribed'/>
|
|
</subscriptions>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
id='subman2'/>
|
|
]]></example>
|
|
<p>In order to remove an entity from the subscriptions list, the owner MUST set the value of the 'subscription' attribute to "none" and the service MUST remove that entity from the subscriptions list and not return it in response to future list requests.</p>
|
|
<p>The owner MAY change multiple subscriptions in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be ¬acceptable;) with the invalid entries, where the subscription returned is the original, un-altered subscription.</p>
|
|
<example caption='Owner sets subscription for multiple entities'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='subman3'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<subscriptions node='princely_musings'>
|
|
<subscription jid='polonius@denmark.lit' subscription='none'/>
|
|
<subscription jid='bard@shakespeare.lit' subscription='subscribed'/>
|
|
</subscriptions>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with an error'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='subman3'/>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<subscriptions node='princely_musings'>
|
|
<subscription jid='bard@shakespeare.lit' subscription='subscribed'/>
|
|
</subscriptions>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If errors occur during a modification request for multiple entities, the pubsub service MUST return any <subscription/> element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'subscription' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MAY specify multiple <subscription/> elements for the same entity, but each element MUST possess a distinct value of the 'subid' attribute.</p>
|
|
<p>An implementation SHOULD send notification to an entity whose subscription has changed (see the <link url='#impl-subchange'>Notification of Subscription State Changes</link> section of this document).</p>
|
|
<example caption='Service sends notification of subscription change'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='polonius@denmark.lit'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription node='princely_musings' jid='polonius@denmark.lit' subscription='none'/>
|
|
</pubsub>
|
|
</message>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic='Manage Affiliations' anchor='owner-affiliations'>
|
|
<p>A service MAY allow a node owner to edit the affiliations of entities associated with a given node and to set affiliations for new entities; if so, it MUST advertise support for the "pubsub#modify-affiliations" feature.</p>
|
|
<p>In order to request a list of all affiliated entities, a node owner MUST send an affiliations request, consisting of an <affiliations/> element whose 'node' attribute specifies the NodeID of the relevant node.</p>
|
|
<example caption='Owner requests all affiliated entities'><![CDATA[
|
|
<iq type='get'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='ent1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<affiliations node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no error occurs, the service MUST return the list of entities whose affiliation is "owner", "publisher", or "outcast" (it MUST NOT return entities whose affiliation is "none").</p>
|
|
<example caption='Service returns list of affiliated entities'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='ent1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<affiliations node='princely_musings'>
|
|
<affiliation jid='hamlet@denmark.lit' affiliation='owner'/>
|
|
<affiliation jid='polonius@denmark.lit' affiliation='outcast'/>
|
|
</affiliations>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>There are several reasons why the affiliated entities request might fail:</p>
|
|
<ol>
|
|
<li>The service does not support modification of affiliations.</li>
|
|
<li>The requesting entity does not have sufficient privileges to modify affiliations.</li>
|
|
<li>The specified node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "modify-affiliations".</p>
|
|
<example caption='Node or service does not support affiliation management'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<affiliations node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='modify-affiliations'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p>
|
|
<example caption='Entity is not an owner'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='ent1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<affiliations node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the node does not exist, the service MUST return an ¬found; error.</p>
|
|
<example caption='Node does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
id='purge1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<affiliations node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>Upon receiving the affiliations list, the node owner MAY modify affiliations. The owner MUST send only modified affiliations (i.e., a "delta"), not the complete list. (Note: If the 'affiliation' attribute is not specified in a modification request, then the value MUST NOT be changed.)</p>
|
|
<example caption='Owner modifies affiliations'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='ent2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<affiliations node='princely_musings'/>
|
|
<affiliation jid='hamlet@denmark.lit' affiliation='owner'/>
|
|
<affiliation jid='polonius@denmark.lit' affiliation='none'/>
|
|
<affiliation jid='bard@shakespeare.lit' affiliation='publisher'/>
|
|
</affiliations>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
id='ent2'/>
|
|
]]></example>
|
|
<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>
|
|
<p>The owner MAY change multiple affiliations in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be ¬acceptable;) with the invalid entries, where the affiliation returned is the original, un-altered affiliation.</p>
|
|
<p>The following example shows an entity attempting to make the owner something other than an affiliation of "owner", an action which MUST NOT be allowed if there is only one owner.</p>
|
|
<example caption='Owner sets affiliation for multiple entities'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='ent3'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<affiliations node='princely_musings'>
|
|
<affiliation jid='hamlet@denmark.lit' affiliation='none'/>
|
|
<affiliation jid='polonius@denmark.lit' affiliation='none'/>
|
|
<affiliation jid='bard@shakespeare.lit' affiliation='publisher'/>
|
|
</affiliations>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with an error'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='ent3'/>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<affiliations node='princely_musings'>
|
|
<affiliation jid='hamlet@denmark.lit' affiliation='owner'/>
|
|
</affiliations>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>The state chart at the beginning of this document is a MUST-IMPLEMENT set of rules for checking possible state transitions. Implementations MAY enforce other (more strict) rules. If errors occur during a modification request for multiple entities, the pubsub service MUST return any <affiliation/> element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'affiliation' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MUST NOT specify multiple <affiliation/> elements for the same entity; otherwise the service MUST return a &badrequest; error.</p>
|
|
<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>
|
|
<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'>
|
|
<affiliations node='princely_musings'>
|
|
<affilation jid='polonius@denmark.lit' affiliation='none'/>
|
|
</affiliations>
|
|
</pubsub>
|
|
</message>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Collection Nodes' anchor='collections'>
|
|
|
|
<p>A pubsub service MAY support collection nodes as well as leaf nodes. Collections enable nodes to be grouped together in any way, including hierarchies and directed acyclic graphs. Collections MUST contain only leaf nodes and/or other collections. Collections MUST NOT contain published items, since only leaf nodes are allowed to contain items (therefore a collection MUST NOT support the "publish" feature or related features such as "persistent-items"). If collections are supported, a service MUST advertise that fact in its "disco#info" responses by including a feature of "pubsub#collections" and MUST support service discovery of child nodes as described in the <link url='#entity-nodes'>Discover Nodes</link> section of this document.</p>
|
|
|
|
<section2 topic='Subscribe to a Collection Node' anchor='collections-subscribe'>
|
|
<p>A service that implements collection nodes SHOULD allow entities to subscribe to collection nodes (subject to access models and local security policies).</p>
|
|
<p>In addition to the subscription configuration options already defined, there are two subscription configuration options specific to collection nodes:</p>
|
|
<ul>
|
|
<li>
|
|
<p><strong>pubsub#subscription_type</strong></p>
|
|
<p>This subscription option enables the subscriber to subscribe either to items or to nodes.</p>
|
|
<p>If the subscription type is "items", the subscriber shall be notified whenever any node contained in the collection generates a notification (e.g., when an item is published or deleted), as modified by the value of the "pubsub#subscription_depth" option.</p>
|
|
<p>If the subscription type is "nodes", the subscriber shall be notified whenever a new node is added to the collection, as modified by the value of the "pubsub#subscription_depth" option.</p>
|
|
<p>The default value of this subscription option MUST be "nodes".</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>pubsub#subscription_depth</strong></p>
|
|
<p>This subscription option enables the subscriber to specify whether it wants to receive notifications only from first-level children of the collection (a value of "1") or from all descendents (a value of "all").</p>
|
|
<p>For subscriptions of type "items", this enables the subscriber to be informed only when an item is published to a leaf node that is a direct child of the collection node to which it has subscribed, or to be informed whenever an item is published to any leaf node in the "tree" that begins at the level of the collection to which it has subscribed.</p>
|
|
<p>For subscriptions of type "nodes", this enables the subscriber to be informed only when a new node is added in the specific collection to which it has subscribed, or to be informed whenever a node is added anywhere in the "tree" that begins at the level of the collection to which it has subscribed.</p>
|
|
<p>The default value of this subscription option MUST be "1".</p>
|
|
</li>
|
|
</ul>
|
|
<p>In order to subscribe to a collection node, an entity MUST send a subscription request to the node; the subscription request MAY include subscription options, but this is not strictly necessary (especially if the entity does not wish to override the default settings for the "pubsub#subscription_type" and "pubsub#subscription_depth" options).</p>
|
|
<example caption='Entity subscribes to a collection node (no configuration)'><![CDATA[
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='collsub1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe jid='francisco@denmark.lit'
|
|
node='blogs'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>The subscriber will now receive notification of new first-level nodes created within the "blogs" collection.</p>
|
|
<example caption='Entity subscribes to a collection node (with configuration)'><![CDATA[
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='collsub2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe jid='francisco@denmark.lit'
|
|
node='blogs'/>
|
|
<options>
|
|
<x xmlns='jabber:x:data'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
<field var='pubsub#subscription_type'>
|
|
<value>items</value>
|
|
</field>
|
|
<field var='pubsub#subscription_depth'>
|
|
<value>all</value>
|
|
</field>
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>The subscriber will now receive item notifications from nodes at any depth within the "blogs" collection.</p>
|
|
<p>Depending on the nature of the node "tree", a subscription type of "items" and depth of "all" may result in an extremely large number of notifications. Therefore, a service MAY disallow such a combination of subscription options, in which case it MUST return a ¬allowed; error to the requesting entity.</p>
|
|
<p>A service MAY allow an entity to subscribe to a collection node in two ways, once with a subscription of type "nodes" (to receive notification of any new nodes added to the collection or the entire tree) and once with a subscription of type "items" (to receive all items published within the tree). However, a service SHOULD NOT allow an entity to subscribe twice to a collection node (once with a subscription depth of "1" and once with a subscription depth of "all") for the same subscription type, since two such subscriptions are unnecessary (a depth of "all" includes by definition a depth of "1"); in this case the service SHOULD return a &conflict; error to the requesting entity.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Root Collection Node' anchor='collections-root'>
|
|
<p>A service that implements collections SHOULD support a root collection. The root collection shall be identified by the lack of a node identifier (i.e., the address of the pubsub service itself, such as "pubsub.shakespeare.lit").</p>
|
|
<p>Subscribing to this node with a subscription of type "nodes" and a depth of "1" enables an entity to be notified whenever a new first-level node is created at the pubsub service. Subscribing to this node with a subscription of type "nodes" and a depth of "all" enables an entity to be notified whenever a new node is created anywhere at the pubsub service.</p>
|
|
<example caption='Entity subscribes to the root collection node'><![CDATA[
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='root1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>In order to send notification of new nodes, the service shall send an event that contains a <collection/> element that in turns contains a <node/> element whose 'id' attribute specifies the NodeID of the new node.</p>
|
|
<example caption='Notification of new node'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit'
|
|
id='newnode1'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<collection>
|
|
<node id='new-node-id'>
|
|
</collection>
|
|
</event>
|
|
</message>
|
|
]]></example>
|
|
<p>The notification event MAY also include the node meta-data, formatted using the <strong>Data Forms</strong> protocol.</p>
|
|
<example caption='Notification of new node'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit'
|
|
id='newnode2'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<collection>
|
|
<node id='new-node-id'>
|
|
<x xmlns='jabber:x:data' type='result'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#meta-data</value>
|
|
</field>
|
|
<field var='pubsub#creation_date'><var>2003-07-29T22:56Z</var></field>
|
|
<field var='pubsub#creator'><var>hamlet@denmark.lit</var></field>
|
|
<field var='pubsub#description'><var>Atom feed for my blog.</var></field>
|
|
<field var='pubsub#language'><var>en</var></field>
|
|
<field var='pubsub#contact'><value>bard@shakespeare.lit</value></field>
|
|
<field var='pubsub#owner'><value>hamlet@denmark.lit</value></field>
|
|
<field var='pubsub#title'><var>Princely Musings (Atom).</var></field>
|
|
<field var='pubsub#type'><value>http://www.w3.org/2005/Atom</value></field>
|
|
</x>
|
|
</node>
|
|
</collection>
|
|
</event>
|
|
</message>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic='Create a New Collection Node' anchor='collections-createnode'>
|
|
<p>To create a new collection node, the requesting entity MUST include a Data Form containing a 'pubsub#node_type' field whose <value/> is "collection".</p>
|
|
<example caption='Entity requests a new collection node'><![CDATA[
|
|
<iq type='set'
|
|
from='bard@shakespeare.lit/globe'
|
|
to='pubsub.shakespeare.lit'
|
|
id='create3'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='announcements'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
<field var='pubsub#node_type'><value>collection</value></field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service responds with success'><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='bard@shakespeare.lit/globe'
|
|
id='create3'/>
|
|
]]></example>
|
|
<p>In addition to the errors already defined for leaf node creation, there are several reasons why the collection node creation request might fail:</p>
|
|
<ol>
|
|
<li>The service does not support collection nodes.</li>
|
|
<li>The service does not support creation of collection nodes.</li>
|
|
<li>The requesting entity does not have sufficient privileges to create collection nodes.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>If the service does not support collection nodes, it MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".</p>
|
|
<example caption='Service does not support collection nodes'><![CDATA[
|
|
<iq type='error'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
feature='collections'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the service supports collection nodes but does not allow new collection nodes to be created, it MUST respond with a ¬allowed; error.</p>
|
|
<example caption='Service does not allow creation of collection nodes'><![CDATA[
|
|
<iq type='error'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity has insufficient privileges to create new collections, the service MUST respond with a &forbidden; error.</p>
|
|
<example caption='Requesting entity has insufficient privileges to create collection nodes'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='hamlet@denmark.lit/elsinore'
|
|
id='config1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'/>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>A service MAY offer some node configuration options that are specific to collection nodes and not provided in configuration forms related to leaf nodes. The following are RECOMMENDED:</p>
|
|
<ul>
|
|
<li>pubsub#children_association_policy -- the policy regarding who may associate child nodes with the collection (values: all, owner, whitelist).</li>
|
|
<li>pubsub#children_association_whitelist -- the whitelist of entities that may associate child nodes with the collection.</li>
|
|
<li>pubsub#children_max -- the maximum number of child nodes that may be associated with a collection.</li>
|
|
</ul>
|
|
</section2>
|
|
|
|
<section2 topic='Create a Node Associated with a Collection' anchor='collections-createassociated'>
|
|
<p>To create a new node and associate it with an existing collection, the node configuration protocol MUST be used in the node creation request (see the <link url='#owner-create-and-configure'>Create and Configure a Node</link> section of this document). In order to specify the associated collection(s), the form MUST include a 'pubsub#collection' field.</p>
|
|
<p>Note: Inclusion of the node configuration form is not necessary if the node is being created as a first-level child of the root collection node, since every such child is automatically affiliated with the root collection node (if any).</p>
|
|
<p>Note: For the protocol used to associate an existing node with a collection, refer to the <link url='#collections-associate'>Associate an Existing Node with a Collection</link> section of this document.</p>
|
|
<example caption='Entity creates a new node associated with a collection'><![CDATA[
|
|
<iq type='set'
|
|
from='bard@shakespeare.lit/globe'
|
|
to='pubsub.shakespeare.lit'
|
|
id='create4'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='plays'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='pubsub#collection'><value>announcements</value></field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>The service then creates the node and associates it with the collection.</p>
|
|
<p>Note: If the node is a collection node and the requesting entity wishes to request the default configuration, the requesting entity MUST include <em>only</em> the "pubsub#collection" and "pubsub#node_type" fields in the configuration form.</p>
|
|
<p>There are several reasons why the request might fail:</p>
|
|
<ol>
|
|
<li>The request specified more than one collection node, but the service allows a node to be associated with only one collection node.</li>
|
|
<li>The requesting entity does not have sufficient privileges to associate a node with the specified collection node.</li>
|
|
<li>No additional nodes can be associated with the collection node.</li>
|
|
<li>The specified collection node is actually a leaf node.</li>
|
|
<li>The specified collection node does not exist.</li>
|
|
</ol>
|
|
<p>These error cases are described more fully below.</p>
|
|
<p>An implementation MAY allow a node to be associated with more than one collection node and therefore MAY specify a type of "text-multi" for the "pubsub#collection" field. However, in order to reduce the complexity of implementation, it is RECOMMENDED to allow only one parent collection node for each node and therefore it is RECOMMENDED to specify a type of "text-single" for the "pubsub#collection" field. If a service supports associating a node with multiple collections, it MUST advertise support for the "multi-collection" feature (if that feature is not advertised, entities SHOULD assume that the service allows a node to be associated with only one collection). If the request specifies more than one collection node but the service allows a node to be associated with only one collection node, the service MUST return a &badrequest; error.</p>
|
|
<example caption='Too many collection nodes'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='bard@shakespeare.lit/globe'
|
|
id='create4'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='plays'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='pubsub#collection'>
|
|
<value>announcements</value>
|
|
<value>news</value>
|
|
</field>
|
|
<field var='pubsub#node_type'>
|
|
<value>collection</value>
|
|
</field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
<error type='modify'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the requesting entity does not have sufficient privileges to associate a node with the specified collection node, the service MUST return a &forbidden; error.</p>
|
|
<example caption='Insufficient privileges'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='bard@shakespeare.lit/globe'
|
|
id='create4'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='plays'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='pubsub#collection'><value>announcements</value></field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
<error type='auth'>
|
|
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If no additional nodes can be associated with the collection node because a configurable limit of associated nodes has been reached, the service MUST return a &conflict; error, which SHOULD also include a pubsub-specific error condition of <max-nodes-exceeded/>.</p>
|
|
<example caption='Associated node limit reached'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='bard@shakespeare.lit/globe'
|
|
id='create4'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='plays'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='pubsub#collection'><value>announcements</value></field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<max-nodes-exceeded xmlns='http://jabber.org/protocol/pubsub#errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the specified collection node is actually a leaf node, the service MUST return an ¬allowed; error.</p>
|
|
<example caption='Collection node is actually a leaf node'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='bard@shakespeare.lit/globe'
|
|
id='create4'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='plays'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='pubsub#collection'><value>announcements</value></field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the specified collection node does not exist, the service MUST return an ¬found; error.</p>
|
|
<example caption='No such collection node'><![CDATA[
|
|
<iq type='error'
|
|
from='pubsub.shakespeare.lit'
|
|
to='bard@shakespeare.lit/globe'
|
|
id='create4'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<create node='plays'/>
|
|
<configure>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='pubsub#collection'><value>announcements</value></field>
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
<error type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic='Associate an Existing Node with a Collection' anchor='collections-associate'>
|
|
<p>Although a node can be associated with a collection when it is created (as described above), it can also be associated with a collection after it has been created. This can be done in two ways:</p>
|
|
<ul>
|
|
<li>By modifying the node's "pubsub#collection" configuration field.</li>
|
|
<li>By modifying the collection node's "pubsub#children" configuration field.</li>
|
|
</ul>
|
|
<p>These methods are described below.</p>
|
|
<p>In order to modify the (child) node's "pubsub#collection" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:</p>
|
|
<example caption='Node owner modifies node configuration'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='associate1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
...
|
|
<field var='pubsub#collection'><value>blogs</value></field>
|
|
...
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>In order to modify the (parent) node's "pubsub#children" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:</p>
|
|
<example caption='Node owner modifies node configuration'><![CDATA[
|
|
<iq type='set'
|
|
from='bard@shakespeare.lit/globe'
|
|
to='pubsub.shakespeare.lit'
|
|
id='associate2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='blogs'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
...
|
|
<field var='pubsub#children'>
|
|
<value>princely_musings</value>
|
|
<value>kingly_ravings</value>
|
|
<value>starcrossed_stories</value>
|
|
<value>moorish_meanderings</value>
|
|
</field>
|
|
...
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic='Disassociate a Node from a Collection' anchor='collections-disassociate'>
|
|
<p>A node can be disassociated from a collection after it has been associated (whether at creation time or afterward). This can be done in two ways:</p>
|
|
<ul>
|
|
<li>By modifying the node's "pubsub#collection" configuration field.</li>
|
|
<li>By modifying the collection node's "pubsub#children" configuration field.</li>
|
|
</ul>
|
|
<p>These methods are described below.</p>
|
|
<p>In order to modify the (child) node's "pubsub#collection" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:</p>
|
|
<example caption='Node owner modifies node configuration'><![CDATA[
|
|
<iq type='set'
|
|
from='hamlet@denmark.lit/elsinore'
|
|
to='pubsub.shakespeare.lit'
|
|
id='associate1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='princely_musings'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
...
|
|
<field var='pubsub#collection'><value></value></field>
|
|
...
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>Note: To disassociate the node from all collection nodes, the node owner MUST submit an empty <value/> element within the 'pubsub#collection' field as shown in the foregoing example.</p>
|
|
<p>In order to modify the (parent) node's "pubsub#children" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:</p>
|
|
<example caption='Node owner modifies node configuration'><![CDATA[
|
|
<iq type='set'
|
|
from='bard@shakespeare.lit/globe'
|
|
to='pubsub.shakespeare.lit'
|
|
id='associate2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
|
|
<configure node='blogs'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#node_config</value>
|
|
</field>
|
|
...
|
|
<field var='pubsub#children'>
|
|
<value>kingly_ravings</value>
|
|
<value>starcrossed_stories</value>
|
|
<value>moorish_meanderings</value>
|
|
</field>
|
|
...
|
|
</x>
|
|
</configure>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>If a node is disassociated from a collection node and a new association is not formed, the implementation MAY associate the node with the root collection node or associate it with no collection node.</p>
|
|
<p>Note: The combination of associating and disassociating a node with a collection can be used to move a node from one collection to another.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Generating Publish Notifications for Collections' anchor='collections-notify'>
|
|
<p>If an item is published to a node which is also included by a collection, and an entity is subscribed to that collection with a subscription type of "items", then the notifications generated by the service MUST contain additional information. The &ITEMS; element contained in the notification message MUST specify the node identifier of the node that generated the notification (not the collection) and the &ITEM; element MUST contain a SHIM header that specifies the node identifier of the collection.</p>
|
|
<example caption='Subscribers receive notifications from a collection'><![CDATA[
|
|
<message to='francisco@denmark.lit' from='pubsub.shakespeare.lit'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
...
|
|
<headers xmlns='http://jabber.org/protocol/shim'>
|
|
<header name='pubsub#collection'>blogs</header>
|
|
</headers>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
|
|
<message to='bernardo@denmark.lit' from='pubsub.shakespeare.lit'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
|
...
|
|
<headers xmlns='http://jabber.org/protocol/shim'>
|
|
<header name='pubsub#collection'>blogs</header>
|
|
</headers>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
.
|
|
.
|
|
.
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Feature Summary' anchor='features'>
|
|
<p>This section summarizes the features described herein, specifies the appropriate requirements level for each feature (REQUIRED, RECOMMENDED, or OPTIONAL), and provides cross-references to the section of this document in which each feature is described.</p>
|
|
<p>Note: The feature names are all of the form "http://jabber.org/protocol/pubsub#name", where "name" is the text specified in the first column below.</p>
|
|
<table caption='Service Discovery Features'>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Description</th>
|
|
<th>Support</th>
|
|
<th>Section</th>
|
|
</tr>
|
|
<tr>
|
|
<td>collections</td>
|
|
<td>Collection nodes are supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#collections'>Collection Nodes</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>config-node</td>
|
|
<td>Configuration of node options is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#owner-configure'>Configure a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>create-and-configure</td>
|
|
<td>Simultaneous creation and configuration of nodes is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#owner-create-and-configure'>Create and Configure a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>create-nodes</td>
|
|
<td>Creation of nodes is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#owner-create'>Create a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>delete-any</td>
|
|
<td>Any publisher may delete an item (not only the originating publisher).</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#publisher-delete'>Delete an Item from a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>delete-nodes</td>
|
|
<td>Deletion of nodes is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#owner-delete'>Delete a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>get-pending</td>
|
|
<td>Retrieval of pending subscription approvals is supported.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#owner-subreq'>Manage Subscription Requests</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>instant-nodes</td>
|
|
<td>Creation of instant nodes is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#owner-create'>Create a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>item-ids</td>
|
|
<td>Publishers may specify item identifiers.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>leased-subscription</td>
|
|
<td>Time-based subscriptions are supported.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#impl-leases'>Time-Based Subscriptions (Leases)</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>manage-subscriptions</td>
|
|
<td>Node owners may manage subscriptions.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#owner-subscriptions'>Manage Subscribers</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>meta-data</td>
|
|
<td>Node meta-data is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>modify-affiliations</td>
|
|
<td>Node owners may modify affiliations.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#owner-affiliations'>Manage Affiliations</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>multi-collection</td>
|
|
<td>A single leaf node may be associated with multiple collections.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#collections-createassociated'>Create a Node Associated with a Collection</link> and <link url='#collections-associate'>Associate an Existing Node with a Collection</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>multi-subscribe</td>
|
|
<td>A single entity may subscribe to a node multiple times.</td>
|
|
<td>OPTIONAL</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>outcast-affiliation</td>
|
|
<td>The outcast affiliation is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#affiliations'>Affiliations</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>persistent-items</td>
|
|
<td>Persistent items are supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>presence-notifications</td>
|
|
<td>Presence-based delivery of event notifications is supported.</td>
|
|
<td>OPTIONAL</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>publish</td>
|
|
<td>Publishing items is supported (note: not valid for collection nodes).</td>
|
|
<td>REQUIRED</td>
|
|
<td><link url='#publisher-publish'>Publish an Item to a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>publisher-affiliation</td>
|
|
<td>The publisher affiliation is supported.</td>
|
|
<td>OPTIONAL</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td>purge-nodes</td>
|
|
<td>Purging of nodes is supported.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#owner-purge'>Purge All Node Items</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>retract-items</td>
|
|
<td>Item retraction is supported.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#publisher-delete'>Delete an Item from a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>retrieve-affiliations</td>
|
|
<td>Retrieval of current affiliations is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#publisher-affiliations'>Retrieve Affiliations</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>retrieve-default</td>
|
|
<td>Retrieval of default node configuration is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#owner-default'>Request Default Configuration Options</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>retrieve-items</td>
|
|
<td>Item retrieval is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#subscriber-retrieve'>Retrieve Items from a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>retrieve-subscriptions</td>
|
|
<td>Retrieval of current subscriptions is supported.</td>
|
|
<td>RECOMMENDED</td>
|
|
<td><link url='#subscriber-subscriptions'>Retrieve Subscriptions</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>subscribe</td>
|
|
<td>Subscribing and unsubscribing are supported.</td>
|
|
<td>REQUIRED</td>
|
|
<td><link url='#subscriber-subscribe'>Subscribe to a Node</link> and <link url='#subscriber-unsubscribe'>Unsubscribe from a Node</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>subscription-options</td>
|
|
<td>Configuration of subscription options is supported.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#subscriber-configure'>Configure Subscription Options</link></td>
|
|
</tr>
|
|
<tr>
|
|
<td>subscription-notifications</td>
|
|
<td>Notification of subscription state changes is supported.</td>
|
|
<td>OPTIONAL</td>
|
|
<td><link url='#impl-subchange'>Notification of Subscription State Changes</link></td>
|
|
</tr>
|
|
</table>
|
|
</section1>
|
|
|
|
<section1 topic='Error Conditions' anchor='errors'>
|
|
<table caption='Error conditions and typical causes'>
|
|
<tr>
|
|
<th>Condition</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>&conflict;</td>
|
|
<td>The node already exists.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&feature;</td>
|
|
<td>The operation being attempted on a node (or the system) has failed because the service or node does not support the operation; the error SHOULD also specify which feature is unsupported.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&forbidden;</td>
|
|
<td>An entity does not have sufficient privileges to perform the action, is requesting an operation for another Jabber ID (e.g., francisco@denmark.lit attempts to subscribe bernardo@denmark.lit to a node), or the requesting entity has an affiliation of "outcast".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>¬found;</td>
|
|
<td>The node or item specified for some operation does not exist.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>¬allowed;</td>
|
|
<td>An entity has attempted to perform an action which the service implements; however the service-wide admin or the node owner has disabled the action for that service or node.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>¬authorized;</td>
|
|
<td>An entity has attempted to subscribe to or retrieve items from a node but is not authorized to see the account owner's presence, is not in the appropriate roster group, or is not on the whitelist for subscriptions.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&payment;</td>
|
|
<td>Subscriptions and item retrieval are based on some kind payment service. Payments would be done out-of-band using some agreed-upon method (not defined herein).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>®istration;</td>
|
|
<td>Entities are required to register before node creation is allowed.</td>
|
|
</tr>
|
|
</table>
|
|
<p>Note: Refer to &jep0086; for more information regarding error syntax.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Implementation Notes' anchor='impl'>
|
|
|
|
<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>
|
|
|
|
<section2 topic='Handling Notification-Related Errors' anchor='impl-bounce'>
|
|
<p>As noted above, a pubsub service SHOULD ensure that the &MESSAGE; stanza for each event notification it generates possesses an 'id' attribute with a unique value. (This notification ID is not to be confused with either the node ID or the item ID.) This ID MUST be unique within the context of the pubsub service in order to ensure proper tracking of any delivery-related errors.</p>
|
|
<p>Exactly how a service shall handle delivery-related errors is a matter of implementation. In general, such handling is effectively similar to the bounce processing performed by other message delivery systems, such as mail transfer agents and mailing list software. The following are some suggested guidelines regarding the handling of XMPP-specific error conditions in relation to pubsub event notifications (see <cite>RFC 3920</cite> and <cite>JEP-0086</cite> regarding XMPP error condition semantics):</p>
|
|
<ul>
|
|
<li>If the XMPP error is of type "cancel" (e.g., ¬found;), or the error condition is &gone;, the pubsub service SHOULD terminate the subscription of the entity to that node and MAY terminate the subscription of that entity to all nodes hosted at the service.</li>
|
|
<li>If the XMPP error is of type "auth" (e.g., ®istration;) or "wait" (e.g., &timeout;), or the error condition is &badrequest;, &redirect;, or ¬acceptable;, the pubsub service SHOULD increment a bounce counter for that entity and MAY attempt to resend the event notification after some configurable amount of time. The service MAY terminate the subscription of the entity to that node if the bounce counter has reached some configurable limit.</li>
|
|
</ul>
|
|
</section2>
|
|
|
|
<section2 topic='Presence-Based Delivery of Events' anchor='impl-presence'>
|
|
<p>Implementations of pubsub MAY deliver event notifications only when the subscriber is online. In these cases, the option may be a node configuration option as shown in the examples above. To facilitate this, the pubsub service needs to subscribe to the subscriber's presence and check the subscriber's current presence information before sending any event notifications (as described in <cite>RFC 3921</cite>). Presence subscriptions MUST be based on the subscribed JID.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Not Routing Events to Offline Storage' anchor='impl-offline'>
|
|
<p>Sending events to users of existing Jabber servers may force event notifications to be routed to offline storage for later delivery (as described in &jep0160;). This may not always be desirable. The possible ways of preventing this behavior include:</p>
|
|
<ul>
|
|
<li>Use presence-based subscription options as described above.</li>
|
|
<li>Use delivery semantics as defined by &jep0079;.</li>
|
|
<li>Specify a message type of "headline", which in most existing server implementations will prevent offline storage.</li>
|
|
</ul>
|
|
</section2>
|
|
|
|
<section2 topic='Including a Message Body' anchor='impl-body'>
|
|
<p>If a service understands the semantics for a particular payload type and an entity's subscription is so configured (via the "pubsub#include_body" option), the service SHOULD include an appropriate XMPP &BODY; child element along with the payloads it sends in event notifications for a given node, where the body's XML character data summarizes or represents the information contained in the payload (this enables clients that do not understand the payload format to present the appropriate information to an end user). For example, the Atom <summary/> element (see <cite>RFC 4287</cite>) could be mapped to the XMPP &BODY; element. A service MUST NOT provide the "pubsub#include_body" subscription option for a node if it does not have a defined way to transform part or all of the payload format into a sensible message body. A node owner MAY define an XSLT for transforming the payload format into a message body, via the "pubsub#body_xslt" node configuration option.</p>
|
|
<p>If the service does not understand the semantics for a particular payload type, it MAY include a <body/> child whose XML character data informs the subscriber that the message contains an event notification (e.g., text such as "This message contains an event notification" would be appropriate).</p>
|
|
</section2>
|
|
|
|
<section2 topic='Node ID and Item ID Uniqueness' anchor='impl-uniqueness'>
|
|
<p>NodeIDs MUST be treated as unique identifiers within the context of a particular pubsub service.</p>
|
|
<p>If item identifiers are used, they MUST be treated as unique within the scope of the node. The combination of the NodeID + ItemID MUST be unique within a given service, and MUST specify a single published item at a single node.</p>
|
|
<p>If a publisher publishes an item and the ItemID matches that of an existing item, the pubsub service MUST overwrite the existing item and generate a new event notification.</p>
|
|
<p>Because it is possible for a node's configuration to change such that ItemIDs are required (e.g., a change from transient to persistent), a service SHOULD use ItemIDs for internal tracking purposes even if it does not include them with the notifications it generates prior to the configuration change.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Item Caching' anchor='impl-caching'>
|
|
<p>A service MAY cache the last item published to a node, even if the node is configured for transient publication (i.e., configured to not persist items). The last published item SHOULD be sent to new subscribers upon successful processing of a subscription request or approval by a node owner.</p>
|
|
<p>Note: If a publisher requests <link url='#impl-batch'>Batch Processing</link> of item publications, the concept of "last published item" is undefined; therefore, if information coherence is needed, a publisher SHOULD publish items in separate requests rather than in batch mode.</p>
|
|
<p>Note: Particular profiles of the generic publish-subscribe protocol MAY define more stringent requirements regarding the "cache-last-item" feature.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Batch Processing' anchor='impl-batch'>
|
|
<p>A publisher MAY include multiple &ITEM; elements in a publish request and MAY include multiple &ITEM; elements in a retract request. This results in "batch processing" of publications or retractions. If the service cannot process any one of the items to be published or retracted, the entire batch MUST fail. Also note that batch publication renders the concept of "last published item" problematic; therefore, if information coherence is needed, a publisher SHOULD publish items in separate requests rather than in batch mode.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Auto-Subscribing Owners and Publishers' anchor='impl-autosubscribe'>
|
|
<p>A service MUST allow owners and publishers to subscribe to a node, and to retrieve items from a node even if they are not subscribed. A service MAY auto-subscribe owners and publishers if they are not already subscribed, in which case it SHOULD generate a subscription ID if necessary for the subscription and SHOULD send a notification of successful subscription as described in the <link url='#impl-subchange'>Notification of Subscription State Changes</link> section of this document.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Authorizing Subscription Requests (Pending Subscribers)' anchor='impl-authorize'>
|
|
<p>How subscription requests are sent to node owners is a matter of implementation. Possibilities include:</p>
|
|
<ul>
|
|
<li>Send requests to all owners (these may be placed in offline storage as described in <cite>JEP-0160</cite>) and first approval wins.</li>
|
|
<li>The service could subscribe to owner presence, and send only to the owners that are online.</li>
|
|
<li>All owners vote on the new subscriber.</li>
|
|
<li>Any owner is allowed to veto the subscriber.</li>
|
|
</ul>
|
|
<p>An implementation MAY use any of these methods, or some other method not defined herein.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Notification of Subscription State Changes' anchor='impl-subchange'>
|
|
<p>Various actions and events may result in changes to a subscription state:</p>
|
|
<ul>
|
|
<li><p>Approval or denial of a subscription request as described in the <link url='#owner-subreq'>Manage Subscription Requests</link> use case</p></li>
|
|
<li><p>Cancellation of an existing subscription, for which many "triggers" are possible:</p>
|
|
<ul>
|
|
<li>The entity simply unsubscribes from the node</li>
|
|
<li>The node is of type "presence" and the underlying presence subscription is cancelled</li>
|
|
<li>The node is of type "roster" and the entity is moved to an unauthorized roster group</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>When a subscription state change occurs, a service SHOULD send a message to the (new, former, or denied) subscriber informing it of the change, where the message contains an <event/> element with a single <subscription/> child that specifies the node, JID, and subscription state. The notification MAY contain a &BODY; element specifying natural-language text regarding the subscription change. Examples are shown below.</p>
|
|
<example caption='Subscription approval notification'><![CDATA[
|
|
<message
|
|
from='pubsub.shakespeare.lit'
|
|
to='horatio@denmark.lit'
|
|
id='approvalnotify1'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<subscription node='princely_musings' jid='horatio@denmark.lit' subscription='subscribed'/>
|
|
</event>
|
|
</message>
|
|
]]></example>
|
|
<example caption='Subscription cancellation / denial notification'><![CDATA[
|
|
<message
|
|
from='pubsub.shakespeare.lit'
|
|
to='horatio@denmark.lit'
|
|
id='unsubnotify1'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<subscription node='princely_musings' jid='horatio@denmark.lit' subscription='none'/>
|
|
</event>
|
|
</message>
|
|
]]></example>
|
|
<p>If the service has knowledge of the (former or denied) subscriber's presence, it SHOULD send the message to all of the subscriber's resources; if not, it MUST send the message to the subscriber's affiliated JID.</p>
|
|
<p>If a service or node supports this feature, it MUST return a feature of "subscription-notifications" in its response to service discovery information requests.</p>
|
|
</section2>
|
|
|
|
<section2 topic='NodeID Semantics' anchor='impl-semantics'>
|
|
<p>NodeIDs MAY have semantic meaning in particular profiles, implementations, or deployments of pubsub. However, it is STRONGLY RECOMMENDED that such semantic meaning not be used to encapsulate the hierarchical structure of nodes; instead, node hierarchy SHOULD be encapsulated using collections and their associated child nodes.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Multiple Node Discovery' anchor='impl-multiple'>
|
|
<p>A user may publish information that adheres to a certain profile at multiple pubsub nodes, and a potential subscriber may want to discover all of these pubsub nodes. The user may make a list of pubsub nodes publicly available for querying even when the user is offline by using the Service Discovery mechanism for "publishing" items (see Section 4 of <cite>JEP-0030</cite>). The potential subscriber may then send a "disco#items" request to the user's bare JID (<user@host>), including the 'node' attribute set to the value of the namespace to which the desired information adheres. The user's server then returns a list of pubsub nodes that meet that criterion (with each pubsub node being a separate Service Discovery item). Here is an example.</p>
|
|
<example caption='Discovering multiple nodes'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='hamlet@denmark.lit'
|
|
id='multi-1'/>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='http://www.w3.org/2005/Atom'/>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='hamlet@denmark.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='multi-1'/>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='http://www.w3.org/2005/Atom'>
|
|
<item jid='pubsub.shakespeare.lit'
|
|
node='princely_musings'
|
|
name='Princely Musings (Atom)'/>
|
|
<item jid='thepub.denmark.lit'
|
|
node='feed-o-rama'
|
|
name='Backup feed'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>Alternatively, a user may be registered with a server that offers personal eventing services, in which case the user will have one node per namespace as described in <cite>JEP-0163</cite>.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Inclusion of SHIM Headers' anchor='impl-shim'>
|
|
<p>When SubIDs are used, <cite>Stanza Headers and Internet Metadata (SHIM)</cite> headers are to be included in order to differentiate notifications sent regarding a particular subscription. The relevant use cases and scenarios are:</p>
|
|
<ul>
|
|
<li>Sending notifications regarding newly-published items as described in the <link url='#publisher-publish'>Publish an Item to a Node</link> use case.</li>
|
|
<li>Sending notifications regarding deleted items as described in the <link url='#publisher-delete'>Delete an Item from a Node</link> use case.</li>
|
|
</ul>
|
|
<p>The SHIM headers are generated by the node to which the subscriber has a subscription, which may be either a leaf node or a collection node.</p>
|
|
<p>SHIM headers are not to be included when the content does not differ based on subscription ID, e.g., when a node sends notification of a configuration change to the node itself, notification that the node has been purged, or notification that the node has been deleted.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Associating Events and Payloads with the Generating Entity' anchor='impl-association'>
|
|
<p>An implementation MAY enable the node configuration to specify an association between the event notification and the entity to which the published information pertains, but such a feature is OPTIONAL. Here are some possible examples:</p>
|
|
<ul>
|
|
<li>In the context of a geolocation notification service using &jep0080;, the user may generate the geolocation information or the information may be generated by an automated service (e.g., a service offered by a mobile telephony provider), but in either case the information is <em>about</em> the user's geolocation and therefore all replies should go to the user (who is probably the node owner).</li>
|
|
<li>In the context of a group weblog, different users might publish to the weblog and replies might go to the publisher of an entry rather than to the weblog owner.</li>
|
|
<li>In the context of an integrated pubsub and multi-user chat system, the node owner might be the room owner but all replies need to be sent to the room rather than to the owner.</li>
|
|
</ul>
|
|
<p>Therefore we define three node configuration options:</p>
|
|
<ul>
|
|
<li>pubsub#itemreply -- the per-item policy for replies (the value is "owner" or "publisher").</li>
|
|
<li>pubsub#replyto -- the specific user JID(s) to which replies should be sent.</li>
|
|
<li>pubsub#replyroom -- the multi-user chat room to which replies should be sent.</li>
|
|
</ul>
|
|
<p>A node owner MUST NOT define more than one of these options.</p>
|
|
<p>An example is shown below.</p>
|
|
<example caption='Event notification with extended stanza addressing'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit'
|
|
to='bassanio@merchantofvenice.lit'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='n48ad4fj78zn38st734'>
|
|
<item id='i1s2d3f4g5h6bjeh936'>
|
|
<geoloc xmlns='http://jabber.org/protocol/geoloc'>
|
|
<description>Venice</description>
|
|
<lat>45.44</lat>
|
|
<lon>12.33</lon>
|
|
</geoloc>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
<addresses xmlns='http://jabber.org/protocol/address'>
|
|
<address type='replyto' jid='portia@merchantofvenice.lit'/>
|
|
</addresses>
|
|
</message>
|
|
]]></example>
|
|
<p>Alternatively, if a service implements the personal eventing subset of this protocol, the virtual pubsub service is the account owner's bare JID and notifications are sent from that JID; for details, refer to <cite>JEP-0163</cite>.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Chaining' anchor='impl-chaining'>
|
|
<p>The word "chaining" refers to the practice of subscribing one node to another node. For instance, consider a scenario in which the node <pubsub@example.net/NewsBroadcaster> wants to distribute information received from the node "NewsFeed" at <pubsub.example.com>. While it is theoretically possible for <pubsub@example.net/NewsBroadcaster> to directly subscribe to the NewsFeed node (since the former node is directly addressable as a JID), implementations MUST NOT chain nodes in this fashion. Instead, implementations MUST subscribe from the address of the pubsub service rather than the node (in the example shown here, the subscription would be sent from <pubsub@example.net> rather than <pubsub@example.net/NewsBroadcaster>).</p>
|
|
|
|
</section2>
|
|
|
|
<section2 topic='Time-Based Subscriptions (Leases)' anchor='impl-leases'>
|
|
<p>In some systems it may be desirable to provide a subscription "leasing" feature in order to expire old or stale subscriptions. Leases can be implemented using configurable subscription options; specifically, when an entity subscribes, the service would require configuration of subscription options and the configuration form would contain a field of "pubsub#expire". This field MUST contain a dateTime (as specified in &jep0082;).</p>
|
|
<p>The leasing process is shown below.</p>
|
|
<example caption='Leasing process'><![CDATA[
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='lease1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='lease1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'
|
|
subscription='unconfigured'>
|
|
<subscribe-options>
|
|
<required/>
|
|
</subscribe-options>
|
|
</subscription>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='lease2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='lease2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
...
|
|
<field var='pubsub#expire' type='text-single'
|
|
label='Requested lease period'/>
|
|
...
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='lease3'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
...
|
|
<field var='pubsub#expire'><value>2006-02-28T11:59Z</value></field>
|
|
...
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='lease3'/>
|
|
]]></example>
|
|
<p>The service MAY send a message to the subscriber when the lease is almost over (e.g., 24 hours before the end of the lease term). This SHOULD be done by sending a &MESSAGE; containing an empty pubsub <event/> element and a SHIM header named "pubsub#expire".</p>
|
|
<example caption='Service notifies subscriber of impending lease end'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit/barracks'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'/>
|
|
<headers xmlns='http://jabber.org/protocol/shim'>
|
|
<header name='pubsub#expire'>2006-02-28T23:59Z</header>
|
|
</headers>
|
|
</message>
|
|
]]></example>
|
|
<p>When the subscriber wants to renew the lease, it would get the current subscription options, change the value of the "pubsub#expire" field, and submit the new subscription options back to the service. If the new expire value exceeds the maximum value allowed for subscription leases, the service MUST change the value of the field to be the current date/time plus the maximum allowed lease period.</p>
|
|
<example caption='Renewing a lease'><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='renew1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='renew1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
...
|
|
<field var='pubsub#expire' type='text-single'
|
|
label='Requested lease period'/>
|
|
...
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='set'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='renew2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings' jid='francisco@denmark.lit'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
...
|
|
<field var='pubsub#expire'><value>2006-03-31T23:59Z</value></field>
|
|
...
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='renew2'/>
|
|
]]></example>
|
|
</section2>
|
|
|
|
<section2 topic='Content-Based Pubsub Systems' anchor='impl-content'>
|
|
<p>A service MAY enable entities to subscribe to nodes and apply a filter to notifications (e.g., keyword matching such as "send me all news entries from Slashdot that match the term 'Jabber'"). Such a content-based service SHOULD allow an entity to subscribe more than once to the same node and, if so, MUST use subscription identifiers (SubIDs) to distinguish between multiple subscriptions. In order to prevent collisions, a service that supports content-based subscriptions using SubIDs SHOULD generate SubIDs on behalf of subscribers rather than allowing subscribers to set their own SubIDs. <note>Another way to implement content-based subscriptions is to host one node per keyword or other filter; however, this is likely to require an extremely large number of nodes.</note></p>
|
|
<p>Content-based services SHOULD use subscription options to specify the filter(s) to be applied. Because there many possible filtering mechanisms (many of which may be application-specific), this JEP does not define any such method. However, filtering mechanisms may be defined in separate specifications.</p>
|
|
<p>A fictional example of the subscription options configuration process for content-based pubsub is shown below.</p>
|
|
<example caption='A content-based subscription'><![CDATA[
|
|
<iq type='set'
|
|
from='marcellus@denmark.lit/castle'
|
|
to='pubsub.shakespeare.lit'
|
|
id='filter1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe
|
|
node='princely_musings'
|
|
jid='francisco@denmark.lit'/>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='marcellus@denmark.lit/castle'
|
|
id='filter1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscription
|
|
node='princely_musings'
|
|
jid='marcellus@denmark.lit'
|
|
subid='991d7fd1616fd041015064133cd097a10030819e'
|
|
subscription='unconfigured'>
|
|
<subscribe-options>
|
|
<required/>
|
|
</subscribe-options>
|
|
</subscription>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='get'
|
|
from='marcellus@denmark.lit/castle'
|
|
to='pubsub.shakespeare.lit'
|
|
id='filter2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings'
|
|
jid='marcellus@denmark.lit'
|
|
subid='991d7fd1616fd041015064133cd097a10030819e'/>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='marcellus@denmark.lit/castle'
|
|
id='filter2'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings'
|
|
jid='marcellus@denmark.lit'
|
|
subid='991d7fd1616fd041015064133cd097a10030819e'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
...
|
|
<field var='http://shakespeare.lit/search#keyword'
|
|
type='text-single'
|
|
label='Keyword to match'/>
|
|
...
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='set'
|
|
from='marcellus@denmark.lit/castle'
|
|
to='pubsub.shakespeare.lit'
|
|
id='filter3'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<options node='princely_musings'
|
|
jid='marcellus@denmark.lit'
|
|
subid='991d7fd1616fd041015064133cd097a10030819e'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
|
|
</field>
|
|
...
|
|
<field var='http://shakespeare.lit/search#keyword'><value>peasant</value></field>
|
|
...
|
|
</x>
|
|
</options>
|
|
</pubsub>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='marcellus@denmark.lit/castle'
|
|
id='filter3'/>
|
|
]]></example>
|
|
<p>The subscriber will then be notified about events that match the keyword.</p>
|
|
<example caption='Event notification for matched keyword'><![CDATA[
|
|
<message from='pubsub.shakespeare.lit' to='marcellus@denmark.lit'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='princely_musings'>
|
|
<item id='4e30f35051b7b8b42abe083742187228'>
|
|
<entry xmlns='http://www.w3.org/2005/Atom'>
|
|
<title>Alone</title>
|
|
<summary>
|
|
Now I am alone.
|
|
O, what a rogue and peasant slave am I!
|
|
</summary>
|
|
<link rel='alternate' type='text/html'
|
|
href='http://denmark.lit/2003/12/13/atom03'/>
|
|
<id>tag:denmark.lit,2003:entry-32396</id>
|
|
<published>2003-12-13T11:09:53Z</published>
|
|
<updated>2003-12-13T11:09:53Z</updated>
|
|
</entry>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
<headers xmlns='http://jabber.org/protocol/shim'>
|
|
<header name='pubsub#subid'>991d7fd1616fd041015064133cd097a10030819e</header>
|
|
</headers>
|
|
</message>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Internationalization Considerations' anchor='i18n'>
|
|
<section2 topic='Field Labels' anchor='i18n-formtypes'>
|
|
<p>The Data Forms shown in this specification include English-language labels for various fields; implementations that will display such forms to human users SHOULD provide localized label text for fields that are defined for the registered FORM_TYPEs.</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>Because the data published to a pubsub node may contain sensitive information (e.g., a user's geolocation), node owners SHOULD exercise care in approving subscription requests. Security considerations regarding particular kinds of information are the responsbility of the using protocol.</p>
|
|
<p>A service MUST NOT allow non-owners or other unauthorized entities to complete any actions defined under the <link url='#owner'>Owner Use Cases</link> section of this document.</p>
|
|
<p>A service MUST adhere to the defined access model in determining whether to send event notifications or payloads to an entity, or allow an entity to retrieve items from a node. A service MAY enforce additional privacy and security policies when determining whether an entity is allowed to subscribe to a node or retrieve items from a node; however, any such policies shall be considered specific to an implementation or deployment and are out of scope for this document.</p>
|
|
</section1>
|
|
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This JEP does not require interaction with &IANA;.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
|
|
|
|
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
|
|
<p>The ®ISTRAR; includes the following namespaces in its registry of protocol namespaces (see &NAMESPACES;):</p>
|
|
<ul>
|
|
<li>http://jabber.org/protocol/pubsub</li>
|
|
<li>http://jabber.org/protocol/pubsub#errors</li>
|
|
<li>http://jabber.org/protocol/pubsub#event</li>
|
|
<li>http://jabber.org/protocol/pubsub#owner</li>
|
|
</ul>
|
|
</section2>
|
|
|
|
<section2 topic='Service Discovery Category/Type' anchor='registrar-disco'>
|
|
<p>The Jabber Registrar includes a category of "pubsub" in its registry of Service Discovery identities (see &DISCOCATEGORIES;), as well as three specific types within that category:</p>
|
|
<table caption='Service Discovery Types in Pubsub Category'>
|
|
<tr>
|
|
<td>collection</td>
|
|
<td>A pubsub node of the "collection" type.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>leaf</td>
|
|
<td>A pubsub node of the "leaf" type.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>service</td>
|
|
<td>A pubsub service that supports the functionality defined in JEP-0060. <note>Prior to version 1.5 of JEP-0060, this type was called "generic".</note></td>
|
|
</tr>
|
|
</table>
|
|
<p>The registry submission is as follows:</p>
|
|
<code><![CDATA[
|
|
<category>
|
|
<name>pubsub</name>
|
|
<desc>Services and nodes that adhere to JEP-0060.</desc>
|
|
<type>
|
|
<name>collection</name>
|
|
<desc>A pubsub node of the "collection" type.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</type>
|
|
<type>
|
|
<name>leaf</name>
|
|
<desc>A pubsub node of the "leaf" type.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</type>
|
|
<type>
|
|
<name>service</name>
|
|
<desc>A pubsub service that supports the functionality defined in JEP-0060.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</type>
|
|
</category>
|
|
]]></code>
|
|
<p>Future submissions to the Jabber Registrar may register additional types.</p>
|
|
</section2>
|
|
|
|
<section2 topic='Service Discovery Features' anchor='registrar-features'>
|
|
<p>The Jabber Registrar maintains a registry of service discovery features (see &DISCOFEATURES;), which includes a number of features that may be returned by pubsub services. The following registry submission has been provided to the Jabber Registrar for that purpose.</p>
|
|
<code><![CDATA[
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#collections</name>
|
|
<desc>Collection nodes are supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#config-node</name>
|
|
<desc>Configuration of node options is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#create-and-configure</name>
|
|
<desc>Simultaneous creation and configuration of nodes is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#create-nodes</name>
|
|
<desc>Creation of nodes is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#delete-any</name>
|
|
<desc>Any publisher may delete an item (not only the originating publisher).</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#delete-nodes</name>
|
|
<desc>Deletion of nodes is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#get-pending</name>
|
|
<desc>Retrieval of pending subscription approvals is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#instant-nodes</name>
|
|
<desc>Creation of instant nodes is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#item-ids</name>
|
|
<desc>Publishers may specify item identifiers.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#leased-subscription</name>
|
|
<desc>Time-based subscriptions are supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#meta-data</name>
|
|
<desc>Node meta-data is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#manage-subscription</name>
|
|
<desc>Node owners may manage subscriptions.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#modify-affiliations</name>
|
|
<desc>Node owners may modify affiliations.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#multi-collection</name>
|
|
<desc>A single leaf node may be associated with multiple collections.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#multi-subscribe</name>
|
|
<desc>A single entity may subscribe to a node multiple times.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#outcast-affiliation</name>
|
|
<desc>The outcast affiliation is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#persistent-items</name>
|
|
<desc>Persistent items are supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#presence-notifications</name>
|
|
<desc>Presence-based delivery of event notifications is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#publish</name>
|
|
<desc>Publishing items is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#publisher-affiliation</name>
|
|
<desc>The publisher affiliation is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#purge-nodes</name>
|
|
<desc>Purging of nodes is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#retract-items</name>
|
|
<desc>Item retraction is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#retrieve-affiliations</name>
|
|
<desc>Retrieval of current affiliations is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#retrieve-default</name>
|
|
<desc>Retrieval of default node configuration is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#retrieve-items</name>
|
|
<desc>Item retrieval is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#retrieve-subscriptions</name>
|
|
<desc>Retrieval of current subscriptions is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#subscribe</name>
|
|
<desc>Subscribing and unsubscribing are supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#subscription-options</name>
|
|
<desc>Configuration of subscription options is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
<var>
|
|
<name>http://jabber.org/protocol/pubsub#subscription-notifications</name>
|
|
<desc>Notification of subscription state changes is supported.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</var>
|
|
]]></code>
|
|
</section2>
|
|
|
|
<section2 topic='Field Standardization' anchor='registrar-formtypes'>
|
|
<p>JEP-0068 defines a process for standardizing the fields used within Data Forms scoped by a particular namespace, and the Jabber Registrar maintains a registry of such FORM_TYPES (see &FORMTYPES;). Within pubsub, there are four uses of such forms:</p>
|
|
<ol>
|
|
<li>Authorization of subscriptions using the 'http://jabber.org/protocol/pubsub#subscribe_authorization' namespace.</li>
|
|
<li>Configuration of subscription options using the 'http://jabber.org/protocol/pubsub#subscribe_options' namespace.</li>
|
|
<li>Configuration of a node using the 'http://jabber.org/protocol/pubsub#node_config' namespace.</li>
|
|
<li>Setting of meta-data information using the 'http://jabber.org/protocol/pubsub#meta-data' namespace.</li>
|
|
</ol>
|
|
<p>The registry submissions associated with these namespaces are defined below.</p>
|
|
<p>Note: There is no requirement that configuration fields need to be registered with the Jabber Registrar. However, as specified in Section 3.4 of <cite>JEP-0068</cite>, names of custom (unregistered) fields MUST begin with the characters "x-" if the form itself is scoped by a registered FORM_TYPE.</p>
|
|
|
|
<section3 topic='pubsub#subscribe_authorization FORM_TYPE' anchor='registrar-formtypes-auth'>
|
|
<code><![CDATA[
|
|
<form_type>
|
|
<name>http://jabber.org/protocol/pubsub#subscribe_authorization</name>
|
|
<jep>JEP-0060</jep>
|
|
<desc>Forms enabling authorization of subscriptions to pubsub nodes</desc>
|
|
<field
|
|
var='pubsub#allow'
|
|
type='boolean'
|
|
label='Whether to allow the subscription'/>
|
|
<field
|
|
var='pubsub#subid'
|
|
type='text-single'
|
|
label='The SubID of the subscription'/>
|
|
<field
|
|
var='pubsub#node'
|
|
type='text-single'
|
|
label='The NodeID of the relevant node'/>
|
|
<field
|
|
var='pubsub#subscriber_jid'
|
|
type='jid-single'
|
|
label='The address (JID) of the subscriber'/>
|
|
</form_type>
|
|
]]></code>
|
|
</section3>
|
|
<section3 topic='pubsub#subscribe_options FORM_TYPE' anchor='registrar-formtypes-options'>
|
|
<code><![CDATA[
|
|
<form_type>
|
|
<name>http://jabber.org/protocol/pubsub#subscribe_options</name>
|
|
<jep>JEP-0060</jep>
|
|
<desc>Forms enabling configuration of subscription options for pubsub nodes</desc>
|
|
<field
|
|
var='pubsub#deliver'
|
|
type='boolean'
|
|
label='Whether an entity wants to receive
|
|
or disable notifications'/>
|
|
<field
|
|
var='pubsub#digest'
|
|
type='boolean'
|
|
label='Whether an entity wants to receive digests
|
|
(aggregations) of notifications or all
|
|
notifications individually'/>
|
|
<field var='pubsub#digest_frequency'
|
|
type='text-single'
|
|
label='The minimum number of milliseconds between
|
|
sending any two notification digests'/>
|
|
<field
|
|
var='pubsub#expire'
|
|
type='text-single'
|
|
label='The DateTime at which a leased subscription
|
|
will end or has ended'/>
|
|
<field
|
|
var='pubsub#include_body'
|
|
type='boolean'
|
|
label='Whether an entity wants to receive an XMPP
|
|
message body in addition to the payload
|
|
format'/>
|
|
<field
|
|
var='pubsub#show-values'
|
|
type='list-multi'
|
|
label='The presence states for which an entity
|
|
wants to receive notifications'>
|
|
<option label='XMPP Show Value of Away'>
|
|
<value>away</value>
|
|
</option>
|
|
<option label='XMPP Show Value of Chat'>
|
|
<value>chat</value>
|
|
</option>
|
|
<option label='XMPP Show Value of DND (Do Not Disturb)'>
|
|
<value>dnd</value>
|
|
</option>
|
|
<option label='Mere Availability in XMPP (No Show Value)'>
|
|
<value>online</value>
|
|
</option>
|
|
<option label='XMPP Show Value of XA (Extended Away)'>
|
|
<value>xa</value>
|
|
</option>
|
|
</field>
|
|
<field var='pubsub#subscription_type'
|
|
type='list-single'>
|
|
<option label='Receive notification of new items only'>
|
|
<value>items</value>
|
|
</option>
|
|
<option label='Receive notification of new nodes only'>
|
|
<value>nodes</value>
|
|
</option>
|
|
</field>
|
|
<field var='pubsub#subscription_depth'
|
|
type='list-single'>
|
|
<option label='Receive notification from direct child nodes only'>
|
|
<value>1</value>
|
|
</option>
|
|
<option label='Receive notification from all descendent nodes'>
|
|
<value>all</value>
|
|
</option>
|
|
</field>
|
|
</form_type>
|
|
]]></code>
|
|
</section3>
|
|
<section3 topic='pubsub#node_config FORM_TYPE' anchor='registrar-formtypes-config'>
|
|
<code><![CDATA[
|
|
<form_type>
|
|
<name>http://jabber.org/protocol/pubsub#node_config</name>
|
|
<jep>JEP-0060</jep>
|
|
<desc>Forms enabling configuration of pubsub nodes</desc>
|
|
<field var='pubsub#access_model'
|
|
type='list-single'
|
|
label='Who may subscribe and retrieve items'>
|
|
<option label='Subscription requests must be approved and only subscribers may retrieve items'>
|
|
<value>authorize</value>
|
|
</option>
|
|
<option label='Anyone may subscribe and retrieve items'>
|
|
<value>open</value>
|
|
</option>
|
|
<option label='Anyone with a presence subscription of both or from may subscribe and retrieve items'>
|
|
<value>presence</value>
|
|
</option>
|
|
<option label='Anyone in the specified roster group(s) may subscribe and retrieve items'>
|
|
<value>roster</value>
|
|
</option>
|
|
<option label='Only those on a whitelist may subscribe and retrieve items'>
|
|
<value>whitelist</value>
|
|
</option>
|
|
</field>
|
|
<field var='pubsub#body_xslt'
|
|
type='text-single'
|
|
label='The URL of an XSL transformation which can be
|
|
applied to payloads in order to generate an
|
|
appropriate message body element.'/>
|
|
<field var='pubsub#collection'
|
|
type='text-single'
|
|
label='The collection with which a node is affiliated'/>
|
|
<field var='pubsub#dataform_xslt'
|
|
type='text-single'
|
|
label='The URL of an XSL transformation which can be
|
|
applied to the payload format in order to generate
|
|
a valid Data Forms result that the client could
|
|
display using a generic Data Forms rendering
|
|
engine'/>
|
|
<field var='pubsub#deliver_notifications' type='boolean'
|
|
label='Whether to deliver event notifications'>
|
|
<value>true</value>
|
|
</field>
|
|
<field var='pubsub#deliver_payloads'
|
|
type='boolean'
|
|
label='Whether to deliver payloads with event notifications'/>
|
|
<field var='pubsub#itemreply'
|
|
type='list-single'
|
|
label='Whether owners or publisher should receive replies to items'>
|
|
<option label='Statically specify a replyto of the node owner(s)'>
|
|
<value>owner</value>
|
|
</option>
|
|
<option label='Dynamically specify a replyto of the item publisher'>
|
|
<value>publisher</value>
|
|
</option>
|
|
</field>
|
|
<field var='pubsub#children_association_policy'
|
|
type='list-single'
|
|
label='Who may associate leaf nodes with a collection'>
|
|
<option label='Anyone may associate leaf nodes with the collection'>
|
|
<value>all</value>
|
|
</option>
|
|
<option label='Only collection node owners may associate leaf nodes with the collection'>
|
|
<value>owners</value>
|
|
</option>
|
|
<option label='Only those on a whitelist may associate leaf nodes with the collection'>
|
|
<value>whitelist</value>
|
|
</option>
|
|
</field>
|
|
<field var='pubsub#children_association_whitelist'
|
|
type='jid-multi'
|
|
label='The list of JIDs that may associated leaf nodes with a collection'/>
|
|
<field var='pubsub#children'
|
|
type='text-multi'
|
|
label='The child nodes (leaf or collection) associated with a collection'/>
|
|
<field var='pubsub#children_max'
|
|
type='text-single'
|
|
label='The maximum number of child nodes that can be associated with a collection'/>
|
|
<field var='pubsub#max_items'
|
|
type='text-single'
|
|
label='The maximum number of items to persist'/>
|
|
<field var='pubsub#max_payload_size'
|
|
type='text-single'
|
|
label='The maximum payload size in bytes'/>
|
|
<field var='pubsub#node_type'
|
|
type='list-single'
|
|
label='Whether the node is a leaf (default) or a collection'>
|
|
<option label='The node is a leaf node (default)'>
|
|
<value>leaf</value>
|
|
</option>
|
|
<option label='The node is a collection node'>
|
|
<value>collection</value>
|
|
</option>
|
|
</field>
|
|
<field var='pubsub#notify_config'
|
|
type='boolean'
|
|
label='Whether to notify subscribers when the node configuration changes'/>
|
|
<field var='pubsub#notify_delete'
|
|
type='boolean'
|
|
label='Whether to notify subscribers when the node is deleted'/>
|
|
<field var='pubsub#notify_retract'
|
|
type='boolean'
|
|
label='Whether to notify subscribers when items are removed from the node'/>
|
|
<field var='pubsub#persist_items'
|
|
type='boolean'
|
|
label='Whether to persist items to storage'/>
|
|
<field var='pubsub#presence_based_delivery'
|
|
type='boolean'
|
|
label='Whether to deliver notifications to available users only'/>
|
|
<field var='pubsub#publish_model'
|
|
type='list-single'
|
|
label='The publisher model'>
|
|
<option label='Only publishers may publish'>
|
|
<value>publishers</value>
|
|
</option>
|
|
<option label='Subscribers may publish'>
|
|
<value>subscribers</value>
|
|
</option>
|
|
<option label='Anyone may publish'>
|
|
<value>open</value>
|
|
</option>
|
|
</field>
|
|
<field var='pubsub#replyroom'
|
|
type='jid-multi'
|
|
label='The specific multi-user chat rooms to specify for replyroom'/>
|
|
<field var='pubsub#replyto'
|
|
type='jid-multi'
|
|
label='The specific JID(s) to specify for replyto'/>
|
|
<field var='pubsub#roster_groups_allowed'
|
|
type='list-multi'
|
|
label='The roster group(s) allowed to subscribe and retrieve items'/>
|
|
<field var='pubsub#send_last_published_item'
|
|
type='list-single'
|
|
label='When to send the last published item'>
|
|
<option label='Never'>
|
|
<value>never</value>
|
|
</option>
|
|
<option label='When a new subscription is processed'>
|
|
<value>on_sub</value>
|
|
</option>
|
|
<option label='When a new subscription is processed and whenever a subscriber comes online'>
|
|
<value>on_sub_and_presence</value>
|
|
</option>
|
|
</field>
|
|
<field var='pubsub#subscribe' type='boolean'
|
|
label='Whether to allow subscriptions'>
|
|
<value>1</value>
|
|
</field>
|
|
<field var='pubsub#title'
|
|
type='text-single'
|
|
label='A friendly name for the node'/>
|
|
<field var='pubsub#type'
|
|
type='text-single'
|
|
label='The type of node data, usually specified by
|
|
the namespace of the payload (if any); MAY
|
|
be list-single rather than text-single'/>
|
|
</form_type>
|
|
]]></code>
|
|
</section3>
|
|
<section3 topic='pubsub#meta-data FORM_TYPE' anchor='registrar-formtypes-metadata'>
|
|
<code><![CDATA[
|
|
<form_type>
|
|
<name>http://jabber.org/protocol/pubsub#meta-data</name>
|
|
<jep>JEP-0060</jep>
|
|
<desc>Forms enabling setting of meta-data information about pubsub nodes</desc>
|
|
<field var='pubsub#contact'
|
|
type='jid-multi'
|
|
label='The JIDs of those to contact with questions'/>
|
|
<field var='pubsub#creation_date'
|
|
type='text-single'
|
|
label='The datetime when the node was created'/>
|
|
<field var='pubsub#creator'
|
|
type='jid-single'
|
|
label='The JID of the node creator'/>
|
|
<field var='pubsub#description'
|
|
type='text-single'
|
|
label='A description of the node'/>
|
|
<field var='pubsub#language'
|
|
type='text-single'
|
|
label='The default language of the node'/>
|
|
<field var='pubsub#num_subscribers'
|
|
type='text-single'
|
|
label='The number of subscribers to the node'/>
|
|
<field var='pubsub#owner'
|
|
type='jid-multi'
|
|
label='The JIDs of those with an affiliation of owner'/>
|
|
<field var='pubsub#publisher'
|
|
type='jid-multi'
|
|
label='The JIDs of those with an affiliation of publisher'/>
|
|
<field var='pubsub#title'
|
|
type='text-single'
|
|
label='The name of the node'/>
|
|
<field var='pubsub#type'
|
|
type='text-single'
|
|
label='Payload type'/>
|
|
</field>
|
|
</form_type>
|
|
]]></code>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic='SHIM Headers' anchor='registrar-shim'>
|
|
<p>The Jabber Registrar includes "pubsub#collection", "pubsub#expire", and "pubsub#subid" in its registry of SHIM headers (see &SHIMHEADERS;). The registry submission is as follows:</p>
|
|
<code><![CDATA[
|
|
<header>
|
|
<name>pubsub#collection</name>
|
|
<desc>The collection via which a notification was received from the originating node.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</header>
|
|
<header>
|
|
<name>pubsub#expire</name>
|
|
<desc>The DateTime at which a pubsub leased subscription will end or has ended.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</header>
|
|
<header>
|
|
<name>pubsub#subid</name>
|
|
<desc>A subscription identifer within the pubsub protocol.</desc>
|
|
<doc>JEP-0060</doc>
|
|
</header>
|
|
]]></code>
|
|
<p>Future submissions to the Jabber Registrar may register additional SHIM headers that can be used in relation to the pubsub protocol, and such submission may occur without updating this specification.</p>
|
|
</section2>
|
|
<section2 topic='URI Query Types' anchor='registrar-querytypes'>
|
|
<p>As authorized by &jep0147;, the Jabber Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).</p>
|
|
<p>The "pubsub" querytype is defined herein for interaction with pubsub services, with two keys: (1) "action" (whose defined values are "subscribe" and "unsubscribe") and (2) "node" (to specify a pubsub node).</p>
|
|
<example caption='Pubsub Subscribe Action: IRI/URI'><![CDATA[
|
|
xmpp:pubsub.shakespeare.lit?pubsub;action=subscribe;node=princely_musings
|
|
]]></example>
|
|
<example caption='Pubsub Subscribe Action: Resulting Stanza'><![CDATA[
|
|
<iq to='pubsub.shakespeare.lit' type='set'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<subscribe node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Pubsub Unsubscribe Action: IRI/URI'><![CDATA[
|
|
xmpp:pubsub.shakespeare.lit?pubsub;action=unsubscribe;node=princely_musings
|
|
]]></example>
|
|
<example caption='Pubsub Unsubscribe Action: Resulting Stanza'><![CDATA[
|
|
<iq to='pubsub.shakespeare.lit' type='set'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<unsubscribe node='princely_musings'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
<p>The following submission registers the "pubsub" querytype.</p>
|
|
<code><![CDATA[
|
|
<querytype>
|
|
<name>pubsub</name>
|
|
<proto>http://jabber.org/protocol/pubsub</proto>
|
|
<desc>enables interaction with a publish-subscribe service</desc>
|
|
<doc>JEP-0060</doc>
|
|
<keys>
|
|
<key>
|
|
<name>action</name>
|
|
<desc>the pubsub action</desc>
|
|
<values>
|
|
<value>
|
|
<name>subscribe</name>
|
|
<desc>enables subscribing to a pubsub node</desc>
|
|
</value>
|
|
<value>
|
|
<name>unsubscribe</name>
|
|
<desc>enables unsubscribing from a pubsub node</desc>
|
|
</value>
|
|
</values>
|
|
</key>
|
|
<key>
|
|
<name>node</name>
|
|
<desc>the pubsub node</desc>
|
|
</key>
|
|
</keys>
|
|
</querytype>
|
|
]]></code>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='XML Schemas' anchor='schemas'>
|
|
<section2 topic='http://jabber.org/protocol/pubsub' anchor='schemas-pubsub'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/pubsub'
|
|
xmlns='http://jabber.org/protocol/pubsub'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
JEP-0060: http://www.jabber.org/jeps/jep-0060.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:import
|
|
namespace='jabber:x:data'
|
|
schemaLocation='http://jabber.org/protocol/x-data/x-data.xsd'/>
|
|
|
|
<xs:element name='pubsub'>
|
|
<xs:complexType>
|
|
<xs:choice>
|
|
<xs:sequence>
|
|
<xs:element ref='create'/>
|
|
<xs:element ref='configure' minOccurs='0'/>
|
|
</xs:sequence>
|
|
<xs:sequence>
|
|
<xs:element ref='subscribe' minOccurs='0'/>
|
|
<xs:element ref='options' minOccurs='0'/>
|
|
</xs:sequence>
|
|
<xs:choice minOccurs='0'>
|
|
<xs:element ref='affiliations'/>
|
|
<xs:element ref='items'/>
|
|
<xs:element ref='publish'/>
|
|
<xs:element ref='retract'/>
|
|
<xs:element ref='subscription'/>
|
|
<xs:element ref='subscriptions'/>
|
|
<xs:element ref='unsubscribe'/>
|
|
</xs:choice>
|
|
</xs:choice>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='affiliations'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='affiliation' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='affiliation'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='affiliation' use='required'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='outcast'/>
|
|
<xs:enumeration value='owner'/>
|
|
<xs:enumeration value='publisher'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='configure'>
|
|
<xs:complexType>
|
|
<xs:choice minOccurs='0' xmlns:xdata='jabber:x:data'>
|
|
<xs:element ref='xdata:x'/>
|
|
</xs:choice>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='create'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='items'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='max_items' type='xs:positiveInteger' use='optional'/>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
<xs:attribute name='subid' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='item'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='0'>
|
|
<xs:any namespace='##other'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='id' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='options'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='0'>
|
|
<xs:any namespace='jabber:x:data'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='jid' type='xs:string' use='required'/>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
<xs:attribute name='subid' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='publish'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='retract'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='item' minOccurs='1' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
<xs:attribute name='notify' type='xs:boolean' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='subscribe-options'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name='required' type='empty' minOccurs='0'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='subscribe'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='jid' type='xs:string' use='required'/>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='subscriptions'>
|
|
<xs:complexType>
|
|
<xs:element ref='subscription' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='subscription'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='subscribe-options' minOccurs='0'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='jid' type='xs:string' use='required'/>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
<xs:attribute name='subid' type='xs:string' use='optional'/>
|
|
<xs:attribute name='subscription' use='optional'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='none'/>
|
|
<xs:enumeration value='pending'/>
|
|
<xs:enumeration value='subscribed'/>
|
|
<xs:enumeration value='unconfigured'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='unsubscribe'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='jid' type='xs:string' use='required'/>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
<xs:attribute name='subid' type='xs:string' use='optional'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
|
|
<section2 topic='http://jabber.org/protocol/pubsub#errors' anchor='schemas-error'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/pubsub#errors'
|
|
xmlns='http://jabber.org/protocol/pubsub#errors'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
This namespace is used for error reporting only, as
|
|
defined in JEP-0060:
|
|
|
|
http://www.jabber.org/jeps/jep-0060.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:element name='closed-node' type='empty'/>
|
|
<xs:element name='configuration-required' type='empty'/>
|
|
<xs:element name='invalid-jid' type='empty'/>
|
|
<xs:element name='invalid-options' type='empty'/>
|
|
<xs:element name='invalid-payload' type='empty'/>
|
|
<xs:element name='invalid-subid' type='empty'/>
|
|
<xs:element name='item-forbidden' type='empty'/>
|
|
<xs:element name='item-required' type='empty'/>
|
|
<xs:element name='jid-required' type='empty'/>
|
|
<xs:element name='max-nodes-exceeded' type='empty'/>
|
|
<xs:element name='nodeid-required' type='empty'/>
|
|
<xs:element name='not-in-roster-group' type='empty'/>
|
|
<xs:element name='not-subscribed' type='empty'/>
|
|
<xs:element name='payload-too-big' type='empty'/>
|
|
<xs:element name='payload-required' type='empty'/>
|
|
<xs:element name='pending-subscription' type='empty'/>
|
|
<xs:element name='presence-subscription-required' type='empty'/>
|
|
<xs:element name='subid-required' type='empty'/>
|
|
<xs:element name='unsupported'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='feature' use='required'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='collections'/>
|
|
<xs:enumeration value='config-node'/>
|
|
<xs:enumeration value='create-and-configure'/>
|
|
<xs:enumeration value='create-nodes'/>
|
|
<xs:enumeration value='delete-any'/>
|
|
<xs:enumeration value='delete-nodes'/>
|
|
<xs:enumeration value='get-pending'/>
|
|
<xs:enumeration value='instant-nodes'/>
|
|
<xs:enumeration value='item-ids'/>
|
|
<xs:enumeration value='leased-subscription'/>
|
|
<xs:enumeration value='manage-subscriptions'/>
|
|
<xs:enumeration value='meta-data'/>
|
|
<xs:enumeration value='modify-affiliations'/>
|
|
<xs:enumeration value='multi-collection'/>
|
|
<xs:enumeration value='multi-subscribe'/>
|
|
<xs:enumeration value='outcast-affiliation'/>
|
|
<xs:enumeration value='persistent-items'/>
|
|
<xs:enumeration value='presence-notifications'/>
|
|
<xs:enumeration value='publish'/>
|
|
<xs:enumeration value='publisher-affiliation'/>
|
|
<xs:enumeration value='purge-nodes'/>
|
|
<xs:enumeration value='retract-items'/>
|
|
<xs:enumeration value='retrieve-affiliations'/>
|
|
<xs:enumeration value='retrieve-default'/>
|
|
<xs:enumeration value='retrieve-items'/>
|
|
<xs:enumeration value='retrieve-subscriptions'/>
|
|
<xs:enumeration value='subscribe'/>
|
|
<xs:enumeration value='subscription-options'/>
|
|
<xs:enumeration value='subscription-notifications'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
<xs:element name='unsupported-access-model' type='empty'/>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
|
|
<section2 topic='http://jabber.org/protocol/pubsub#event' anchor='schemas-event'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/pubsub#event'
|
|
xmlns='http://jabber.org/protocol/pubsub#event'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
JEP-0060: http://www.jabber.org/jeps/jep-0060.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:import
|
|
namespace='jabber:x:data'
|
|
schemaLocation='http://jabber.org/protocol/x-data/x-data.xsd'/>
|
|
|
|
<xs:element name='event'>
|
|
<xs:complexType>
|
|
<xs:choice minOccurs='0'>
|
|
<xs:element ref='collection'/>
|
|
<xs:element ref='configuration'/>
|
|
<xs:element ref='delete'/>
|
|
<xs:element ref='items'/>
|
|
<xs:element ref='purge'/>
|
|
<xs:element ref='subscription'/>
|
|
</xs:choice>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='collection'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='1'>
|
|
<xs:element ref='node'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='configuration'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='0' xmlns:xdata='jabber:x:data'>
|
|
<xs:element ref='xdata:x'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='delete'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<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: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:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='node'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='id' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='purge'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='retract'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='id' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='subscription'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='jid' type='xs:string' use='required'/>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
<xs:attribute name='subid' type='xs:string' use='optional'/>
|
|
<xs:attribute name='subscription' use='optional'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='none'/>
|
|
<xs:enumeration value='pending'/>
|
|
<xs:enumeration value='subscribed'/>
|
|
<xs:enumeration value='unconfigured'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
|
|
<section2 topic='http://jabber.org/protocol/pubsub#owner' anchor='schemas-owner'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/pubsub#owner'
|
|
xmlns='http://jabber.org/protocol/pubsub#owner'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
JEP-0060: http://www.jabber.org/jeps/jep-0060.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:import
|
|
namespace='jabber:x:data'
|
|
schemaLocation='http://jabber.org/protocol/x-data/x-data.xsd'/>
|
|
|
|
<xs:element name='pubsub'>
|
|
<xs:complexType>
|
|
<xs:choice>
|
|
<xs:element ref='affiliations'/>
|
|
<xs:element ref='configure'/>
|
|
<xs:element ref='delete'/>
|
|
<xs:element ref='purge'/>
|
|
<xs:element ref='subscriptions'/>
|
|
</xs:choice>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='affiliations'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='affiliation' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='affiliation'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='affiliation' use='required'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='none'/>
|
|
<xs:enumeration value='outcast'/>
|
|
<xs:enumeration value='owner'/>
|
|
<xs:enumeration value='publisher'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
<xs:attribute name='jid' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='configure'>
|
|
<xs:complexType>
|
|
<xs:choice minOccurs='0' xmlns:xdata='jabber:x:data'>
|
|
<xs:element ref='xdata:x'/>
|
|
</xs:choice>
|
|
<xs:attribute name='node' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='default'>
|
|
<xs:complexType>
|
|
<xs:choice minOccurs='0' xmlns:xdata='jabber:x:data'>
|
|
<xs:element ref='xdata:x'/>
|
|
</xs:choice>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='delete'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='purge'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='subscriptions'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='subscription' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='node' type='xs:string' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='subscription'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='subscription' use='required'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='none'/>
|
|
<xs:enumeration value='pending'/>
|
|
<xs:enumeration value='subscribed'/>
|
|
<xs:enumeration value='unconfigured'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
<xs:attribute name='jid' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
|
|
</section1>
|
|
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>Thanks to Bob Wyman, Gaston Dombiak, and Matt Tucker for their feedback.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Author Note' anchor='authornote'>
|
|
<p>Peter Millard, primary author of this specification from version 0.1 through version 1.7, died on April 26, 2006. The remaining co-authors are indebted to him for his many years of work on publish-subscribe technologies.</p>
|
|
</section1>
|
|
|
|
</jep>
|