diff --git a/xep-0248.xml b/xep-0248.xml index ec3c836b..1a2a219b 100644 --- a/xep-0248.xml +++ b/xep-0248.xml @@ -1,166 +1,320 @@ + %ents; - ]> -
- PubSub Collection Nodes - This specification defines the nature and handling of collection nodes in the XMPP publish-subsribe extension. - &LEGALNOTICE; - 0248 - Deferred - Standards Track - Standards - Council - - XMPP Core - XEP-0060 - - - - NOT_YET_ASSIGNED - &stpeter; - &ralphm; - - 0.1 - 2008-08-11 - psa -

Initial version, split from XEP-0060.

 - -
+
+ PubSub Collection Nodes + This specification defines the nature and handling of collection nodes in the XMPP publish-subscribe extension. + &LEGALNOTICE; + 0248 + Deferred + Standards Track + Standards + Council + + XMPP Core + XEP-0060 + + + + NOT_YET_ASSIGNED + &stpeter; + &ralphm; + + Brian + Cully + bjc@kublai.com + bjc@kublai.com + + + 0.2 + 2010-09-20 + bjc + +

Completely reworked from initial version. To whit:

+
    +
  • Normalized layout
    • +
  • Added required sections
    • +
  • Renamed "multi-collection" disco feature to "multi-collections" for consistency with "collections" feature
    • +
  • Added associate request
    • +
  • Added dissociate request
    • +
  • Added ability to request items on a collection node
    • +
  • Removed "Node Relationship Models" section
    • +
+ + + + 0.1 + 2008-08-11 + psa +

Initial version, split from XEP-0060.

 + +
- -

&xep0060; defines an XMPP protocol extension for generic publish-subscribe features. This specification defines the nature and handling of collection nodes in XMPP-based publish-subscribe technologies.

-

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 Discover Nodes section of this document.

- + +

&xep0060; defines an XMPP protocol extension for generic publish-subscribe features. However, it only allows notifications from nodes to which an entity is directly subscribed. It is useful in some circumstances to describe a relationship between nodes so that a publish on one node may be delivered via another node. For instance, if an entity is interested in notifications from a set of nodes the entity would discover each node somehow and then subscribe to them. With collection nodes, the entity would subscribe only to the collection which links the desired nodes, simplifying the subscription process.

- -

This section provides background information about collection nodes, with insights from graph theory. See http://en.wikipedia.org/wiki/Graph_(mathematics). The intended result is a clearer vocabulary about particular deployment scenarios. The terminology introduced in this section is used mainly in the discussion of collection node deletion.

-

In terms of graph theory, the set of nodes hosted at a pubsub service is a directed acyclic graph. See http://en.wikipedia.org/wiki/Directed_acyclic_graph. The particular graph types can be further described as follows:

-
    -
  1. If there are no collection nodes, we say that the graph is simply a flat set 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 formal phrase that no node is the parent of any other child node).
    2. -
  2. If there may be multiple paths between any two given nodes (where the path may include intermediate collection nodes), the graph is a Directed Acyclic Graph or "DAG" See http://en.wikipedia.org/wiki/Directed_acyclic_graph. because a given node may be the child of multiple parents.
    3. -
  3. If there is only one path between any two given nodes (where the path may include intermediate collection nodes), the graph is a Tree See http://en.wikipedia.org/wiki/Tree_(graph_theory). because a given node may be the child of only one collection node.
    4. -
  4. If there is a root collection node but there are no internal collection nodes, we say informally that the graph has a depth 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.
    5. -
  5. If there is a root collection node and there are internal collection nodes, we say that the graph has infinite depth 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.
    6. -
  6. 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 dependency on its parent and that the tree is a Strict Hierarchy. (This is similar to a strictly hierarchical file system, in which deletion of a directory results in deletion of all its file and subdirectories.)
    7. -
  7. 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 Loose Hierarchy. (This is similar to a loosely hierarchical file system that is mostly hierarchical but that allows multiple soft links.)
    8. -
  8. 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 Dag Set (i.e., a set of directed acyclic graphs).
    9. -
  9. If a graph is made up of trees but there is no single root collection node for all the trees, the graph is a Forest (i.e., a set of trees).
    10. -
  10. If each tree in a forest is a Strict Hierarchy, we say that the graph is a Strict Hierarchy Set.
    11. -
  11. If each DAG in a set is a Loose Hierarchy, we say that the graph is a Loose Hierarchy Set.
    12. -
-

Finally, in XMPP pubsub, all graphs are oriented 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).

-

This terminology is summarized in the following table.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModelDescriptionRoot NodeMultiple ParentsNode DependencyDepth
Flat SetA set of nodes with no parent-child relationships (i.e., there are no collection nodes).NoN/ANo0 (zero)
Directed Acyclic Graph (DAG)A set of nodes with parent-child relationships, where a child node can have more than one parent.YesYesNo1 or infinite
Dag SetA set of DAGs with no root node.NoYesNo1 or infinite
TreeA set of nodes with parent-child relationships, where a node can be the child of only one parent.YesNoNo1 or infinite
ForestA set of trees with no root node.NoNoNo1 or infinite
Strict HierarchyAn infinite tree in which a child node can have only one parent and is dependent on its parent.YesNoYesInfinite
Strict Hierarchy SetA set of strict hierarchies with no root node.NoNoYesInfinite
Loose HierarchyAn infinite DAG in which a child node can have multiple parents but cannot exist without at least one parent.YesYesYesInfinite
Loose Hierarchy SetA set of loose hierarchies with no root node.NoYesYesInfinite
- - -

A service that implements collection nodes SHOULD allow entities to subscribe to collection nodes (subject to access models and local security policies).

-

In addition to the subscription configuration options already defined, there are two subscription configuration options specific to collection nodes:

-
    -
  • -

    pubsub#subscription_type

    -

    This subscription option enables the subscriber to subscribe either to items or to nodes.

    -

    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.

    -

    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.

    -

    The default value of this subscription option MUST be "nodes".

    -
    • -
  • -

    pubsub#subscription_depth

    -

    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").

    -

    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.

    -

    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.

    -

    The default value of this subscription option MUST be "1".

    -
    • -
-

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).

- In addition to simplifying the subscriber's usage, collection nodes also allow the owner to describe almost any type of relationship between nodes. Using various access models on different nodes the owner can also create almost any desired authorization semantics on a set of leaf nodes.

+ +

Note: Any use cases not described herein are described in XEP-0060. Also, this document does not show error flows related to the generic publish-subscribe use cases referenced herein, since they are exhaustively defined in XEP-0060. The reader is referred to XEP-0060 for all relevant protocol details related to the XMPP publish-subscribe extension.

+ + + +

This documents addresses the common requirements regarding configuration, publishing, subscribing, and notification semantics of collection nodes.

+ + + +

The following terms are used in this document to refer to collection node-specific features.

+ +

Note: some of these terms are specified in greater detail within the body of this document.

+ +
+ +
Collection Node
+
A type of node that contains other nodes but no published items (c.f. Leaf Node).
+ +
Leaf Node
+
A type of node that contains published items but no other nodes (c.f. Collection Node).
+ +
Node Graph
+
The network of nodes emitting from a given node which contains all its descendants.
+ +
Root Node
+
An anonymous collection node used as the de facto beginning of a service's node graph.
+ +
Subscription Depth
+
How deep the collection node graph will be traversed when determining whether notifications will be sent. May be any integer, 0 or greater, or "all".
+ +
Subscription Type
+
The type of notification, either "nodes", "items", or "all" which the subscriber is interested in.
+ +
+ + + + +

Collection nodes link nodes together to unify notifications from a set of collection or leaf nodes. An entity can subscribe to the collection and receive notifications of any associated leaf nodes.

+ +

A collection node can link with any other node in order to create a directed acyclic graph (DAG). Collection nodes MUST NOT be linked in such a way as to produce a cyclic graph (i.e., they cannot link to nodes that eventually link back to the initial node).

+ +

Collection nodes only contain other nodes and MUST NOT contain published items (therefore a collection MUST NOT support the "publish" feature or related features such as "persistent-items").

+ + + + + +

An entity might wish to discover if a service implements collection nodes; in order to do so, it sends a service discovery information ("disco#info") query to the component's JID using &xep0030;. If a service supports collection nodes it MUST return a "pubsub#collections" feature. In addition, if the service supports associating a node with more than one collection it MUST return a feature of "pubsub#multi-collections".

+ + + + + ]]> + + + + ... + + + ... + + ]]> + + + +

The service discovery items ("disco#items") protocol enables an entity to query a service for a list of associated items, which, in the case of collection nodes would consist of the children associated with a given node.

+ + + + + + ]]> + + + + + + + + + + ]]> + + + + + +

If a notification on a child node is created and then delivered via the collection then the notifications generated by the service MUST contain additional information. The 'node' attribute of the &ITEM; or <node/> element contained in the notification message MUST specify the node identifier of the node that generated the notification (not the collection) and the &MESSAGE; stanza MUST contain &xep0131; that specifies the node identifier of the collection.

+ +

Note: The delivery options (such as "pubsub#deliver_payloads") are determined by the publishing leaf node, not by the 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.

+ + +

Item notifications are notifications about the contents of a leaf node, and are generated by a publish, retract, or purge request.

+ + + + + + ... + + + + +
blogs
+ + + ]]> + + + +

Node notifications are notifications about nodes themselves, and are generated by a create, delete, or configure request.

+ + + + + + +
blogs
+ + + ]]> + + + + +

If a collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a <collection/> element whose 'node' attribute specifies the NodeID of the collection; this element in turn contains an <associate/> or <dissociate/> element whose 'node' attribute specifies the NodeID of node that has been associated with the collection.

+ + + + + + + + + ]]> + + + + + + + + + ]]> + + +

The notification event MAY also include the node meta-data, formatted using the &xep0004; protocol.

+ + + + + + + + http://jabber.org/protocol/pubsub#meta-data + + + 2003-07-29T22:56Z + + + hamlet@denmark.lit + + + Atom feed for my blog. + + + en + + + bard@shakespeare.lit + + + hamlet@denmark.lit + + + Princely Musings (Atom). + + http://www.w3.org/2005/Atom + + + + + + + ]]> + + + + + + + +

A service that implements collection nodes SHOULD allow entities to subscribe to collection nodes (subject to access models and local security policies).

+

In addition to the subscription configuration options already defined in XEP-0060, there are two subscription configuration options specific to collection nodes:

+
    +
  • +

    pubsub#subscription_type

    +

    This subscription option enables the subscriber to subscribe either to notifications about items or notifications about nodes.

    + +

    If the subscription type is "items", the subscriber shall be notified whenever any node contained in the collection has an item published to it, retracted from it, or the node is purged, as modified by the value of the "pubsub#subscription_depth" option.

    + +

    If the subscription type is "nodes", the subscriber shall be notified whenever a new node is added to the collection, removed from the collection, or the configuration of a node within the collection has changed, as modified by the value of the "pubsub#subscription_depth" option.

    + +

    If the subscription type is "all", the subscriber shall be notified about both "items" and "nodes" types of events, as modified by the value of the "pubsub#subscription_depth" option.

    + +

    The default value of this subscription option SHOULD be "nodes".

    +
    • + +
  • +

    pubsub#subscription_depth

    + +

    This subscription option enables the subscriber to specify how far to traverse the node graph when determining whether a notification will be sent. It may be any integer value, 0 or greater, or the value "all" which means that any node within the collection will generate a notification.

    + +

    The default value of this subscription option SHOULD be "1".

    +
    • +
+

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).

+ + + - + - ]]> -

The subscriber will now receive notification of new first-level nodes created within the "blogs" collection.

- + +

The subscriber will now receive notification of new first-level nodes created within the "blogs" collection.

+ + + id='collsub1'> @@ -192,73 +348,122 @@ all - - + + - ]]> -

The subscriber will now receive item notifications from nodes at any depth within the "blogs" collection.

-

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.

-

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.

- + ]]> + - -

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").

-

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.

- +

If the service allows the subscription it MUST inform the requesting entity that it is now subscribed.

+ + + + + + ]]> + + + +

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.

+ + + + + + + ]]> + +

Depending on the nature of the node graph, 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.

+ + + + + + + ]]> + + + + +

When an entity requests items on a collection node the service SHOULD return the items on any leaf nodes associated with it subject to the access model of the collection node.

+ + + + id='items1'> - - + + - ]]> -

If the root collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a <collection/> element whose 'node' attribute specifies the NodeID of the collection (in this case the NodeID is empty to signify that the collection is the root collection); this element in turn contains an <associate/> element whose 'node' attribute specifies the NodeID of node that has been associated with the collection.

- - - - - - - - ]]> -

The notification event MAY also include the node meta-data, formatted using the Data Forms protocol.

- - - - - - - http://jabber.org/protocol/pubsub#meta-data - - 2003-07-29T22:56Z - hamlet@denmark.lit - Atom feed for my blog. - en - bard@shakespeare.lit - hamlet@denmark.lit - Princely Musings (Atom). - http://www.w3.org/2005/Atom - - - - - - ]]> - + ]]> + - -

To create a new collection node, the requesting entity MUST include a Data Form containing a 'pubsub#node_type' field whose <value/> is "collection".

- +

When a collection contains multiple nodes with items it MUST return multiple &ITEMS; elements, one per node.

+ + + + + + ... + + + + + ... + + + + + ]]> + + + +

Depending on the nature of the node graph it may be expensive to allow item retrieval from a collection node. Therefore the service MAY disallow item retrieval via collection nodes, in which case it MUST return a &feature; error to the requesting entity.

+ + + + + + + ]]> + + + + + + +

To create a new collection node, the requesting entity MUST include a Data Form containing a "pubsub#node_type" field whose <value/> element contains "collection". The default value for "pubsub#node_type" SHOULD be "leaf".

+ + + @@ -273,500 +478,556 @@ - ]]> - + + + + - ]]> -

In addition to the errors already defined for leaf node creation, there are several reasons why the collection node creation request might fail:

-
    -
  1. The service does not support collection nodes.
    2. -
  2. The service does not support creation of collection nodes.
    3. -
  3. The requesting entity does not have sufficient privileges to create collection nodes.
    4. -
-

These error cases are described more fully in the following sections.

-

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".

- + + + +

In addition to the errors already defined for leaf node creation, there are several reasons why the collection node creation request might fail:

+ +
    +
  1. The service does not support collection nodes.
    2. +
  2. The service does not support creation of collection nodes.
    3. +
  3. The requesting entity does not have sufficient privileges to create collection nodes.
    4. +
+ +

These error cases are described more fully in the following sections.

+ + +

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".

+ + - - - + from='pubsub.shakespeare.lit' + to='francisco@denmark.lit/barracks' + id='create3'> - ]]> -

If the service supports collection nodes but does not allow new collection nodes to be created, it MUST respond with a ¬allowed; error.

- + + + +

If the service supports collection nodes but does not allow new collection nodes to be created, it MUST respond with a ¬allowed; error.

+ + - - - + id='create3'> - ]]> -

If the requesting entity has insufficient privileges to create new collections, the service MUST respond with a &forbidden; error.

- + + + +

If the requesting entity has insufficient privileges to create new collections, the service MUST respond with a &forbidden; error.

+ + - - - + to='francisco@denmark.lit/barracks' + id='create3'> - ]]> -

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:

-
    -
  • pubsub#children_association_policy -- the policy regarding who may associate child nodes with the collection (values: all, owner, whitelist).
    • -
  • pubsub#children_association_whitelist -- the whitelist of entities that may associate child nodes with the collection.
    • -
  • pubsub#children_max -- the maximum number of child nodes that may be associated with a collection.
    • -
- + ]]> + + + - - -

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 Create and Configure a Node section of this document). In order to specify the associated collection(s), the form MUST include a 'pubsub#collection' field.

-

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).

-

Note: For the protocol used to associate an existing node with a collection, refer to the Associate an Existing Node with a Collection section of this document.

- + +

In addition to the node configuration options specified in XEP-0060, there are three additional node configuration options that a service which supports collection nodes MUST supply.

+ +
    +
  • pubsub#node_type +

    Whether this is a "leaf" or "collection" node.

    • +
  • pubsub#collection +

    The parents of this node.

    • +
  • pubsub#children +

    The children of this node.

    • +
+ +

To associate the root node to the collection the <value/> element MUST be empty.

+ +

A service MAY offer some node configuration options that are specific to collection nodes and SHOULD NOT be provided in configuration forms related to leaf nodes. The following are RECOMMENDED:

+ +
    +
  • pubsub#children_association_policy +

    The policy regarding who may associate child nodes with the collection (values: all, owner, whitelist).

    • +
  • pubsub#children_association_whitelist +

    The whitelist of entities that may associate child nodes with the collection.

    • +
  • pubsub#children_max +

    The maximum number of child nodes that may be associated with a collection.

    • +
+ + + - - - + id='config1'> + + - announcements - - - - - ]]> -

Note: If the node is a collection node and the requesting entity wishes to request the default configuration, the requesting entity MUST include only the "pubsub#collection" and "pubsub#node_type" fields in the configuration form.

- - -

If no error occurs, the service MUST create the node and associate it with the collection.

- - -

There are several reasons why the request might fail:

-
    -
  1. The request specified more than one collection node, but the service allows a node to be associated with only one collection node.
    2. -
  2. The requesting entity does not have sufficient privileges to associate a node with the specified collection node.
    3. -
  3. No additional nodes can be associated with the collection node.
    4. -
  4. The specified collection node is actually a leaf node.
    5. -
  5. The specified collection node does not exist.
    6. -
-

These error cases are described more fully in the following sections.

- -

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.

- - - - - - - announcements - news + + http://jabber.org/protocol/pubsub#node_config collection + + Romeoance + Julliennui + + + + - - - ]]> - - -

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.

- + + + + ]]> + + + + +

Leaf nodes only contain published items and MUST NOT have any children. If an entity attempts to add children to a leaf node (either via "pubsub#children" on the leaf node or "pubsub#collection" on another node) the service MUST return a ¬allowed; error with a pubsub-specific error condition of <invalid-options/>.

+ + - - - - - announcements - - - - + to='francisco@denmark.lit/barracks' + id='config1'> + + + + + + ]]> + + + +

If the requesting entity is not authorized to add the node to a collection then the service MUST return a &forbidden; error.

+ + + - ]]> - - -

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 ¬allowed; error, which SHOULD also include a pubsub-specific error condition of <max-nodes-exceeded/>.

- + + + +

If the configuration would exceed the maximum number of children allowed on a node, either because the node's "pubsub#children" exceeds it's own "pubsub#children_max" value or because adding this node to a parent via "pubsub#collection" would exceed the parent's "pubsub#children_max" value, the service MUST return a ¬allowed; error with a pubsub-specific error condition of <max-nodes-exceeded/>.

+ + + to='francisco@denmark.lit/barracks' + id='config1'> - ]]> - - -

If the specified collection node is actually a leaf node, the service MUST return an ¬allowed; error.

- + + + +

The service MUST NOT allow the node type to be changed. If it is attempted the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <invalid-options/>

+ + - - - - - announcements - - - + to='francisco@denmark.lit/barracks' + id='config1'> + - ]]> - - -

If the specified collection node does not exist, the service MUST return an ¬found; error.

- - - - - - announcements - - - - - - - - ]]> - - - + ]]> + - -

Deletion of a collection node can introduce a large number of changes to the system, depending on the node relationship model of the deployed system. This section describes recommended handling of deletion requests in the context of collection nodes.

- -

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:

-
    -
  • 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.
    • -
  • 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.
    • -
- - -

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:

-
    -
  • 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.
    • -
  • 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.
    • -
- - -

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:

-
    -
  • The service MUST associate any orphaned child with the root collection node.
    • -
- - -

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:

-
    -
  • The service MUST associate any orphaned child with no other node.
    • -
- - -

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:

-
    -
  • The service SHOULD delete any orphaned child(ren).
    • -
-

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.

- - -

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:

-
    -
  • 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.
    • -
  • If a child node will have no other parents after deletion of the collection node, the service SHOULD delete any orphaned child(ren).
    • -
-

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.

- - -

If the requesting entity attempts to delete the root collection node, the service MUST return a ¬allowed; error.

- +

The service MUST NOT allow a cycle to be created in the node graph (e.g., node A to B to C to A). If an entity attempts to submit a configuration that would create a cycle the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <invalid-options/>.

+ + + + + + + + ]]> + + + + + + +

If a service supports collection node creation it MUST support collection node deletion.

+ + - + + + ]]> + + + +

If no error occurs, the service MUST inform the owner of success.

+ + + ]]> + + + + +

If the requesting entity attempts to delete the root node, the service MUST return a ¬allowed; error.

+ + - ]]> - - + ]]> + + + - -

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:

-
    -
  • By modifying the node's "pubsub#collection" configuration field.
    • -
  • By modifying the collection node's "pubsub#children" configuration field.
    • -
-

These methods are described below.

-

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:

- + +

A service MAY allow collection nodes to have children associated with them without changing the rest of the configuration. If the service allows this an entity can send and <associate/> element with a 'node' attribute that contains the child node within a <collection/> element that posesses a 'node' attribute containing the parent node to the service.

+ + + id='assoc1'> - - - - http://jabber.org/protocol/pubsub#node_config - - ... - blogs - ... - - - - - ]]> -

Note: To associate a node with the root collection node, the node owner MUST submit an empty <value/> element within the 'pubsub#collection' field.

-

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:

- - - - - - http://jabber.org/protocol/pubsub#node_config - - ... - - princely_musings - kingly_ravings - starcrossed_stories - moorish_meanderings - - ... - - - - - ]]> -

If the collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a <collection/> element whose 'node' attribute specifies the NodeID of the collection; this element in turn contains an <associate/> element whose 'node' attribute specifies the NodeID of node that has been associated with the collection.

- - - + - - - ]]> -

If an entity attempts to associate a node with a collection in a way that would violate the node relationship model (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.

- + + + ]]> + - -

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:

-
    -
  • By modifying the node's "pubsub#collection" configuration field.
    • -
  • By modifying the collection node's "pubsub#children" configuration field.
    • -
-

These methods are described below.

-

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:

- - - - - - http://jabber.org/protocol/pubsub#node_config - - ... - - ... - - - - - ]]> -

Note: To disassociate the node from all collection nodes, the node owner MUST submit an empty <field/> element for the 'pubsub#collection' field as shown in the foregoing example.

-

Note: To disassociate the node from the root collection node, the node owner MUST submit an empty <value/> element within the 'pubsub#collection' field as shown in the foregoing example.

-

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:

- - - - - - http://jabber.org/protocol/pubsub#node_config - - ... - - kingly_ravings - starcrossed_stories - moorish_meanderings - - ... - - - - - ]]> -

If the collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a <collection/> element whose 'node' attribute specifies the NodeID of the collection; this element in turn contains a <disassociate/> element whose 'node' attribute specifies the NodeID of node that has been disassociated from the collection.

- - - - - - - - ]]> -

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.

-

Note: The combination of associating a node with one collection and disassociating the same node from another collection can be used to move a node from one collection to another.

- + +

If the service allows the node association then it MUST confirm the association with an empty result.

- -

The default configuration options can 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").

- - - - - - http://jabber.org/protocol/pubsub#node_config - - collection - - - - - ]]> -

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".

- + ]]> + + + + + - - - - - http://jabber.org/protocol/pubsub#node_config - - collection - - - + to='francisco@denmark.lit/barracks' + id='assoc1'> - - + + + ]]> + + + +

If the configuration would exceed the maximum number of children allowed on a node, either because the node's "pubsub#children" exceeds it's own "pubsub#children_max" value or because adding this node to a parent via "pubsub#collection" would exceed the parent's "pubsub#children_max" value, the service MUST return a ¬allowed; error with a pubsub-specific error condition of <max-nodes-exceeded/>.

+ + + + + + + + ]]> + + + +

The service MUST NOT allow a cycle to be created in the node graph (e.g., node A to B to C to A). If an entity attempts to submit a configuration that would create a cycle the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <invalid-options/>.

+ + + + + + + + ]]> + + + + + + +

A service MAY allow collection nodes to have children dissociated from them without changing the rest of the configuration. If the service allows this an entity can send and <dissociate/> element with a 'node' attribute that contains the child node within a <collection/> element that posesses a 'node' attribute containing the parent node to the service.

+ + + + + + + + + ]]> + + + +

If the service allows the node dissociation then it MUST confirm the association with an empty result.

+ + + ]]> + + + + +

If a dissociation is requested between two nodes that are not already associated then the service MUST return a &badrequest; error.

+ + + + + + + ]]> + + + + + + + + + ]]> + + + + + + + +

To provide a starting point for service discovery a service SHOULD support a root node. A root node represents the node belonging to a given service and MUST be identified by the lack of a node identifier (i.e., the address of the pubsub service itself, such as "pubsub.shakespeare.lit"). Because the root node is owned by the service itself an entity SHOULD NOT be allowed create, delete, or configure the root node.

+ +

If a node is created or configured without any parents specified, a service MAY automatically associate otherwise orphaned nodes directly to the root node. If a service automatically associates a node with the root it MUST reflect that in the node configuration data form.

+ + + + + ]]> - + - -

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.

- - - - - ... - - - - -
blogs
- - + +

Deletion of collection nodes can have a number of side effects due to implementation. Depending on the nature of the collection any of the following MAY happen when a collection node is deleted:

- - - - - ... - - - - -
blogs
- - -. -. -. - ]]> -

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.

- + + - -

REQUIRED.

- - -

REQUIRED.

- - -

REQUIRED.

- - -

REQUIRED for protocol specifications.

- + +

Node configuration MUST always reflect the current state of the node graph. Because node configuration contains both a pointer to its parents as well as its children an update to a primary node's "pubsub#collection" value will change the value of the secondary node's "pubsub#children" value, and vice-versa. A service MAY send a notification of the configuration change on the secondary node to subscribers if "pubsub#notify_config" is enabled on the secondary node.

+ + + + + +

Collection nodes can be used to associate almost any node within the service, but only the access model of the collection node itself is used to determine what an entity is allowed to see. Therefore care should be taken that nodes are not linked in such a way as to leak private data (e.g., from a "closed" leaf node through an "open" collection) unless that behavior is specifically desired.

+ + + + +

This document requires no interaction with &IANA;.

+ + + +

Note: These options are in addition to the standard options described in XEP-0060 and related XEPs.

+ + + + pubsub#collections + Support for collection nodes + XEP-0248 + + + pubsub#multi-collections + Support for multiple collections on a node + XEP-0248 + + ]]> + + + + + http://jabber.org/protocol/pubsub#subscribe_options + XEP-0248 + Options for collection node subscription + + label='How far to traverse the node graph for notifications'/> + + + + + + + + http://jabber.org/protocol/pubsub#node_config + XEP-0248 + Options for collection node configuration + + + + + + + + + + + + + + + ]]> + + + + + Collection + The node of subscription that sent a notification + XEP-0248 + + ]]> + + + + +

REQUIRED.

+ + + +

Many thanks to Dave Cridland for his feedback and advice.

+