From 4d838e4566e986c0c9c8718e5c2c7d997a3796c0 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Thu, 25 Oct 2007 17:55:45 +0000 Subject: [PATCH] re-organized manage affiliations section git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1314 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0060.xml | 198 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 141 insertions(+), 57 deletions(-) diff --git a/xep-0060.xml b/xep-0060.xml index 582b1c15..0746d64d 100644 --- a/xep-0060.xml +++ b/xep-0060.xml @@ -4267,11 +4267,13 @@ And by opposing end them? - -

A node owner may want to edit the affiliations of entities associated with a given node and to set affiliations for new entities. Support for this feature ("pubsub#modify-affiliations") is OPTIONAL.

- -

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.

- +

A node owner may want to manage the affiliations of entities associated with a given node and to set affiliations for new entities. Support for this feature ("pubsub#modify-affiliations") is OPTIONAL.

+ +

First the owner retrieves the affiliation list.

+ +

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.

+ - ]]> - - -

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

- + + +

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

+ - ]]> - - -

There are several reasons why the affiliated entities request might fail:

-
    -
  1. The service does not support modification of affiliations.
    2. -
  2. The requesting entity does not have sufficient privileges to modify affiliations.
    3. -
  3. The specified node does not exist.
    4. -
-

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

- -

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

- + + +

There are several reasons why the affiliated entities request might fail:

+
    +
  1. The service does not support modification of affiliations.
    2. +
  2. The requesting entity does not have sufficient privileges to modify affiliations.
    3. +
  3. The specified node does not exist.
    4. +
+

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

+ +

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

+ + id='ent1'> @@ -4321,11 +4323,11 @@ And by opposing end them? feature='modify-affiliations'/> - ]]> - - -

If the requesting entity is not a node owner, the service MUST return a &forbidden; error.

- + + +

If the requesting entity is not a node owner, the service MUST return a &forbidden; error.

+ @@ -4336,14 +4338,14 @@ And by opposing end them? - ]]> - - -

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

- + + +

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

+ + id='ent1'> @@ -4351,38 +4353,112 @@ And by opposing end them? - ]]> + ]]> + - -

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

- +

A node owner may want to edit the affiliation of an entity associated with a given node or to set the affiliation for a new entity.

+ +

In order to modify an affiliation, a node owner MUST send an IQ set containing the modified affiliation or 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.)

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

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.

- - -

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.

-

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.

- + + +

There are several reasons why the modify-affiliations request might fail:

+
    +
  1. The requested affiliation is not supported by the node or service.
    2. +
  2. The service does not support modification of affiliations.
    3. +
  3. The requesting entity does not have sufficient privileges to modify affiliations.
    4. +
  4. The specified node does not exist.
    5. +
+

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

+ +

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

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

If the node or service does not support the requested affiliation, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "member-affiliation", "outcast-affiliation", or "publisher-affiliation" as appropriate.

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

If the requesting entity is not a node owner, the service MUST return a &forbidden; error.

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

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

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

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.

+

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.

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

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.

+ ]]> +

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.

+ + + +

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.

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.

@@ -5393,7 +5473,10 @@ And by opposing end them? -

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.

+

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 and the service MUST NOT publish or retract any of the items.

+

If a batch publish contains so many items that publication of all the items would exceed the maximum number of items for the node, the service MUST return a ¬allowed; error, which SHOULD also include a pubsub-specific error condition of <max-items-exceeded/>.

+

Note: 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.

 @@ -6743,6 +6826,7 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=unsubscribe;node=princely_musings +