moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-28 04:02:20 -05:00
Code Issues Releases Wiki Activity

1.12pre1

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1951 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-06-12 18:43:10 +00:00
parent c8e166e0b9
commit 404779655e
1 changed files with 244 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

253
xep-0060.xml
View File

@ -48,6 +48,22 @@
&stpeter;
&ralphm;
<revision>
<version>1.12pre1</version>
<date>in progress, last updated 2008-06-12</date>
<initials>psa</initials>
<remark>
<ul>
<li>Specified that service should return ItemID on successful publish.</li>
<li>Described the use of Result Set Management to return some but not all published items.</li>
<li>More clearly defined terminology related to deployment scenarios for collection nodes, with some borrowings from graph theory.</li>
<li>Corrected syntax for associating with and disassociating from a collection node so that it is possible to perform these tasks in relation to the root collection node.</li>
<li>Added note about ignoring delivery options set for configuration of a collection node and instead applying delivery options as configured for the publishing leaf node.</li>
<li>Defined handling of collection node deletion for various deployment scenarios.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.11</version>
<date>2008-03-05</date>
@ -1946,7 +1962,7 @@ And by opposing end them?
]]></example>
</section3>
<section3 topic='Returning All Items' anchor='subscriber-retrieve-returnall'>
<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>
<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 (see next section).</p>
<example caption='Service returns all items'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
@ -2017,6 +2033,69 @@ And by opposing end them?
</item>
</items>
</pubsub>
</iq>
]]></example>
</section3>
<section3 topic='Returning Some Items' anchor='subscriber-retrieve-returnsome'>
<p>A node may have a large number of items associated with it, in which case it may be problematic to return all of the items in response to an items request. In this case, the service SHOULD return some of the items and note that the list of items has been truncated by including a &xep0059; notation.</p>
<example caption='Service returns some items via result set management'><![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>
</items>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>368866411b877c30064a5f62b917cffe</first>
<last>4e30f35051b7b8b42abe083742187228</last>
<count>19</count>
</set>
</pubsub>
</iq>
]]></example>
</section3>
@ -2384,7 +2463,7 @@ And by opposing end them?
id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
<item>
<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Soliloquy</title>
<summary>
@ -2407,12 +2486,18 @@ And by opposing end them?
]]></example>
</section3>
<section3 topic='Success Case' anchor='publisher-publish-success'>
<p>If the pubsub service can successfully process the request, it MUST inform the publisher of success.</p>
<p>If the pubsub service can successfully process the request, it MUST inform the publisher of success. If the publish request did not include an ItemID, the IQ-result SHOULD include an empty &ITEM; element that specifies the ItemID of the published item.</p>
<example caption='Service replies with success'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='hamlet@denmark.lit/blogbot'
id='publish1'/>
id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
</publish>
</pubsub>
</iq>
]]></example>
<p>Note: If the publisher previously published an item with the same ItemID, successfully processing the request means that the service MUST overwrite the old item with the new item and then proceed as follows.</p>
<p>The pubsub service MUST then send one &MESSAGE; stanza containing a pubsub event notification to each entity that meets the criteria for receiving a notification (typically to each approved subscriber, although there are other contexts in which an entity may receive a notification as summarized under <link url='#impl-notify'>Notification Triggers</link>). Each &MESSAGE; stanza generated by a pubsub service SHOULD possess an 'id' attribute with a unique value so that the service can properly track any notification-related errors that may occur (see the <link url='#impl-errors'>Handling Notification-Related Errors</link> section of this document). Depending on the node configuration, the event notification either will or will not contain the payload, as shown below.</p>
@ -3775,7 +3860,7 @@ And by opposing end them?
</event>
</message>
]]></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>
<p>If the node to be deleted is a collection node, the service should follow the recommendations provided under <link url='#collections-delete'>Collection Node Deletion</link>.</p>
</section3>
<section3 topic='Error Cases' anchor='owner-delete-error'>
<p>There are several reasons why the node deletion request might fail:</p>
@ -4664,8 +4749,109 @@ And by opposing end them?
<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>
<p>A pubsub service MAY support collection nodes as well as leaf nodes. Collections enable nodes to be grouped together in many ways. A collection node MUST contain only leaf nodes and/or other collection nodes (similar to the way in which a file system directory can contain both files and subdirectories) and MUST NOT contain published 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='Node Relationship Models' anchor='collections-models'>
<p>This section provides background information about collection nodes, with insights from graph theory. <note>See <link url='http://en.wikipedia.org/wiki/Graph_(mathematics)'>http://en.wikipedia.org/wiki/Graph_(mathematics)</link>.</note> The intended result is a clearer vocabulary about particular deployment scenarios. The terminology introduced in this section is used mainly in the discussion of <link url='collections-delete'>collection node deletion</link>.</p>
<p>In terms of graph theory, the set of nodes hosted at a pubsub service is a directed acyclic graph. <note>See <link url='http://en.wikipedia.org/wiki/Directed_acyclic_graph'>http://en.wikipedia.org/wiki/Directed_acyclic_graph</link>.</note> The particular graph types can be further described as follows:</p>
<ol>
<li>If there are no collection nodes, we say that the graph is simply a <strong>flat set</strong> of nodes without connections because there are no arcs between nodes, i.e., no node is the direct predecessor of another node (here we use the less formall phrase that no node is the parent of any other child node).</li>
<li>If there may be multiple paths between between any two given nodes (where the path may include intermediate collection nodes), the graph is a <strong>Directed Acyclic Graph</strong> or "DAG" <note>See <link url='http://en.wikipedia.org/wiki/Directed_acyclic_graph'>http://en.wikipedia.org/wiki/Directed_acyclic_graph</link>.</note> because a given node may be the child of multiple parents.</li>
<li>If there is only one path between any two given nodes (where the path may include intermediate collection nodes), the graph is a <strong>Tree</strong> <note>See <link url='http://en.wikipedia.org/wiki/Tree_(graph_theory)'>http://en.wikipedia.org/wiki/Tree_(graph_theory)</link>.</note> because a given node may be the child of only one collection node.</li>
<li>If there is a root collection node but there are no internal collection nodes, we say informally that the graph has a <strong>depth</strong> of 1 because all of the connections from leaf nodes to the root collection node are direct (i.e., each connection is an arc); this case is equivalent to a flat set with a root collection node and is typically uninteresting.</li>
<li>If there is a root collection node and there are internal collection nodes, we say that the graph has <strong>infinite depth</strong> because there is an unbounded number of arcs between each leaf node and the root collection node; this case is more interesting than a graph of depth=1 since it enables a wide range of trees and hierarchies.</li>
<li>In a tree with collection nodes, deletion of a collection node automatically results in destruction of the arcs to that collection node from leaf nodes or other collection nodes because a child can have only one parent; in this case we say that a child node has a <strong>dependency</strong> on its parent and that the tree is a <strong>Strict Hierarchy</strong>. (This is similar to a strictly hierarchical file system, in which deletion of a directory results in deletion of all its file and subdirectories.)</li>
<li>In a DAG with collection nodes, deletion of a collection node does not automatically result in destruction of the arcs to that collection node from leaf nodes or other collection nodes because a child can have multiple parents (but if the last parent is deleted, the last remaining arc is destroyed); in this case we say that the tree is a <strong>Loose Hierarchy</strong>. (This is similar to a loosely hierarchical file system that is mostly hierarchical but that allows multiple soft links.)</li>
<li>If a graph is made up of directed acyclic graphs but there is no single root collection node for all the DAGs, we say that the graph is a <strong>Dag Set</strong> (i.e., a set of directed acyclic graphs).</li>
<li>If a graph is made up of trees but there is no single root collection node for all the trees, the graph is a <strong>Forest</strong> (i.e., a set of trees).</li>
<li>If each tree in a forest is a Strict Hierarchy, we say that the graph is a <strong>Strict Hierarchy Set</strong>.</li>
<li>If each DAG in a set is a Loose Hierarchy, we say that the graph is a <strong>Loose Hierarchy Set</strong>.</li>
</ol>
<p>Finally, in XMPP pubsub, all graphs are <strong>oriented</strong> because any two collection nodes cannot have a bidirectional relationship (i.e., if collection node #1 is a direct predecessor of collection node #2 then #2 cannot also be a direct predecessor of #1).</p>
<p>This terminology is summarized in the following table.</p>
<table caption='Node Relationship Models'>
<tr>
<th>Model</th>
<th>Description</th>
<th>Root Node</th>
<th>Multiple Parents</th>
<th>Node Dependency</th>
<th>Depth</th>
</tr>
<tr>
<td>Flat Set</td>
<td>A set of nodes with no parent-child relationships (i.e., there are no collection nodes).</td>
<td>No</td>
<td>N/A</td>
<td>No</td>
<td>0 (zero)</td>
</tr>
<tr>
<td>Directed Acyclic Graph (DAG)</td>
<td>A set of nodes with parent-child relationships, where a child node can have more than one parent.</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
<td>1 or infinite</td>
</tr>
<tr>
<td>Dag Set</td>
<td>A set of DAGs with no root node.</td>
<td>No</td>
<td>Yes</td>
<td>No</td>
<td>1 or infinite</td>
</tr>
<tr>
<td>Tree</td>
<td>A set of nodes with parent-child relationships, where a node can be the child of only one parent.</td>
<td>Yes</td>
<td>No</td>
<td>No</td>
<td>1 or infinite</td>
</tr>
<tr>
<td>Forest</td>
<td>A set of trees with no root node.</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>1 or infinite</td>
</tr>
<tr>
<td>Strict Hierarchy</td>
<td>An infinite tree in which a child node can have only one parent and is dependent on its parent.</td>
<td>Yes</td>
<td>No</td>
<td>Yes</td>
<td>Infinite</td>
</tr>
<tr>
<td>Strict Hierarchy Set</td>
<td>A set of strict hierarchies with no root node.</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
<td>Infinite</td>
</tr>
<tr>
<td>Loose Hierarchy</td>
<td>An infinite DAG in which a child node can have multiple parents but cannot exist without at least one parent.</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Infinite</td>
</tr>
<tr>
<td>Loose Hierarchy Set</td>
<td>A set of loose hierarchies with no root node.</td>
<td>No</td>
<td>Yes</td>
<td>Yes</td>
<td>Infinite</td>
</tr>
</table>
</section2>
<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>
@ -5015,6 +5201,51 @@ And by opposing end them?
</section3>
</section2>
<section2 topic='Collection Node Deletion' anchor='collections-delete'>
<p>Deletion of a collection node can introduce a large number of changes to the system, depending on the <link url='#collections-models'>node relationship model</link> of the deployed system. This section describes recommended handling of deletion requests in the context of collection nodes.</p>
<section3 topic='Directed Acyclic Graph' anchor='collections-delete-dag'>
<p>When the graph of the pubsub system is a Directed Acyclic Graph, a child node can have more than one parent, which may be the root collection node. Therefore, when a node owner deletes a collection node the service MUST behave as follows:</p>
<ul>
<li>If a child node will still have at least one other parent after deletion of the collection node, the service MUST NOT delete the child node but instead MUST simply sever the relationship between the deleted collection node and the child node.</li>
<li>If a child node will have no other parents after deletion of the collection node, the service MUST associate any orphaned child with the root collection node.</li>
</ul>
</section3>
<section3 topic='Dag Set' anchor='collections-delete-dagset'>
<p>When the graph of the pubsub system is a Dag Set, a child node can have more than one parent but there is no root collection node. Therefore, when a node owner deletes a collection node the service MUST behave as follows:</p>
<ul>
<li>If a child node will still have at least one other parent after deletion of the collection node, the service MUST NOT delete the child node but instead MUST simply sever the relationship between the deleted collection node and the child node.</li>
<li>If a child node will have no other parents after deletion of the collection node, the service MUST associate any orphaned child with no other node.</li>
</ul>
</section3>
<section3 topic='Tree' anchor='collections-delete-tree'>
<p>When the graph of the pubsub system is a Tree, a child node can have only one parent, which may be the root collection node. Therefore, when a node owner deletes a collection node the service MUST behave as follows:</p>
<ul>
<li>The service MUST associate any orphaned child with the root collection node.</li>
</ul>
</section3>
<section3 topic='Forest' anchor='collections-delete-forest'>
<p>When the graph of the pubsub system is a Forest, a child node can have only one parent but there is no root collection node. Therefore, when a node owner deletes a collection node the service MUST behave as follows:</p>
<ul>
<li>The service MUST associate any orphaned child with no other node.</li>
</ul>
</section3>
<section3 topic='Strict Hierarchy or Strict Hierarchy Set' anchor='collections-delete-strict'>
<p>When the graph of the pubsub system is a Strict Hierarchy or a Strict Hierarchy Set, a child node can have only one parent node and cannot exist without its parent. Therefore, when a node owner deletes a collection node the service MUST behave as follows:</p>
<ul>
<li>The service SHOULD delete any orphaned child(ren).</li>
</ul>
<p>Note: This action may introduce cascading changes, since deletion of a child will result in deletion of any grandchildren, great-grandchildren, etc. A service MAY refuse to allow deletion of a collection node if doing so will result in an excessive load on the system. If it so refuses, it MUST return a &constraint; error.</p>
</section3>
<section3 topic='Loose Hierarchy or Loose Hierarchy Set' anchor='collections-delete-loose'>
<p>When the graph of the pubsub system is a Loose Hierarchy or a Loose Hierarchy Set, a child node can have multiple parent nodes but a child node cannot exist without at least one parent node. Therefore, when a node owner deletes a collection node the service MUST behave as follows:</p>
<ul>
<li>If a child node will still have at least one other parent after deletion of the collection node, the service MUST NOT delete the child node but instead MUST simply sever the relationship between the deleted collection node and the child node.</li>
<li>If a child node will have no other parents after deletion of the collection node, the service SHOULD delete any orphaned child(ren).</li>
</ul>
<p>Note: This action may introduce cascading changes, since deletion of a child will result in deletion of any grandchildren, great-grandchildren, etc. A service MAY refuse to allow deletion of a collection node if doing so will result in an excessive load on the system. If it so refuses, it MUST return a &constraint; error.</p>
</section3>
</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>
@ -5042,6 +5273,7 @@ And by opposing end them?
</pubsub>
</iq>
]]></example>
<p>Note: To associate a node with the root collection node, the node owner MUST submit an empty &lt;value/&gt; element within the 'pubsub#collection' field.</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'
@ -5079,6 +5311,7 @@ And by opposing end them?
</event>
</message>
]]></example>
<p>If an entity attempts to associate a node with a collection in a way that would violate the <link url='#collections-models'>node relationship model</link> (e.g., adding a second parent to a node in a Tree or Strict Hierarchy or making a child a new parent of its existing parent or other predecessor and thus violating the orientation of the graph), the service MUST return a &conflict; error.</p>
</section2>
<section2 topic='Disassociate a Node from a Collection' anchor='collections-disassociate'>
@ -5101,14 +5334,15 @@ And by opposing end them?
<value>http://jabber.org/protocol/pubsub#node_config</value>
</field>
...
<field var='pubsub#collection'><value></value></field>
<field var='pubsub#collection'></field>
...
</x>
</configure>
</pubsub>
</iq>
]]></example>
<p>Note: To disassociate the node from all collection nodes, the node owner MUST submit an empty &lt;value/&gt; element within the 'pubsub#collection' field as shown in the foregoing example.</p>
<p>Note: To disassociate the node from all collection nodes, the node owner MUST submit an empty &lt;field/&gt; element for the 'pubsub#collection' field as shown in the foregoing example.</p>
<p>Note: To disassociate the node from the root collection node, the node owner MUST submit an empty &lt;value/&gt; 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'
@ -5181,6 +5415,7 @@ And by opposing end them?
.
.
]]></example>
<p>Note: The delivery options (such as "pubsub#deliver_payloads") are determined by the publishing leaf node, not by the aggregating collection node. If the owner of a collection node sets delivery options for a collection node, the service SHOULD ignore those options and apply the options set for the leaf node that publishes an item.</p>
</section2>
</section1>
@ -6508,7 +6743,7 @@ O, what a rogue and peasant slave am I!
</field>
<field var='pubsub#deliver_payloads'
type='boolean'
label='Whether to deliver payloads with event notifications'/>
label='Whether to deliver payloads with event notifications; applies only to leaf nodes'/>
<field var='pubsub#itemreply'
type='list-single'
label='Whether owners or publisher should receive replies to items'>