re-organized manage affiliations section

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1314 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0060.xml

@@ -4267,9 +4267,11 @@ And by opposing end them?
     </section3>
   </section2>
 
-  <section2 topic='Manage Affiliations' anchor='owner-affiliations'>
+  <section2 topic='Manage Affiliations' anchor='owner-affilmanage'>
-    <p>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.</p>
+    <p>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.</p>
-    <section3 topic='Request' anchor='owner-affiliations-request'>
+    <section3 topic='Retrieve Affiliations List' anchor='owner-affilmanage-retrieve'>
+      <p>First the owner retrieves the affiliation list.</p>
+      <section4 topic='Request' anchor='owner-affilmanage-retrieve-request'>
         <p>In order to request a list of all affiliated entities, a node owner MUST send an affiliations request, consisting of an &lt;affiliations/&gt; element whose 'node' attribute specifies the NodeID of the relevant node.</p>
         <example caption='Owner requests all affiliated entities'><![CDATA[
 <iq type='get'
@@ -4281,8 +4283,8 @@ And by opposing end them?
   </pubsub>
 </iq>
         ]]></example>
-    </section3>
+      </section4>
-    <section3 topic='Success Case' anchor='owner-affiliations-success'>
+      <section4 topic='Success Case' anchor='owner-affilmanage-retrieve-success'>
         <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'
@@ -4297,8 +4299,8 @@ And by opposing end them?
   </pubsub>
 </iq>
         ]]></example>
-    </section3>
+      </section4>
-    <section3 topic='Error Cases' anchor='owner-affiliations-error'>
+      <section4 topic='Error Cases' anchor='owner-affilmanage-retrieve-error'>
         <p>There are several reasons why the affiliated entities request might fail:</p>
         <ol>
           <li>The service does not support modification of affiliations.</li>
@@ -4306,12 +4308,12 @@ And by opposing end them?
           <li>The specified node does not exist.</li>
         </ol>
         <p>These error cases are described more fully in the following sections.</p>
-      <section4 topic='Affiliation Modification Not Supported' anchor='owner-affiliations-notsupported'>
+        <section5 topic='Affiliation Modification Not Supported' anchor='owner-affilmanage-retrieve-notsupported'>
           <p>If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; 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'>
+    id='ent1'>
   <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
     <affiliations node='princely_musings'/>
   </pubsub>
@@ -4322,8 +4324,8 @@ And by opposing end them?
   </error>
 </iq>
           ]]></example>
-      </section4>
+        </section5>
-      <section4 topic='Insufficient Privileges' anchor='owner-affiliations-forbidden'>
+        <section5 topic='Insufficient Privileges' anchor='owner-affilmanage-retrieve-forbidden'>
           <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'
@@ -4337,13 +4339,13 @@ And by opposing end them?
   </error>
 </iq>
           ]]></example>
-      </section4>
+        </section5>
-      <section4 topic='Node Does Not Exist' anchor='owner-affiliations-node'>
+        <section5 topic='Node Does Not Exist' anchor='owner-affilmanage-retrieve-node'>
           <p>If the node does not exist, the service MUST return an &notfound; error.</p>
           <example caption='Node does not exist'><![CDATA[
 <iq type='error'
     from='pubsub.shakespeare.lit'
-    id='purge1'>
+    id='ent1'>
   <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
     <affiliations node='princely_musings'/>
   </pubsub>
@@ -4352,34 +4354,108 @@ And by opposing end them?
   </error>
 </iq>
           ]]></example>
+        </section5>
       </section4>
     </section3>
-    <section3 topic='Modifying Affiliations' anchor='owner-affiliations-modify'>
+    <section3 topic='Modify Affiliation' anchor='owner-affilmanage-modify'>
-      <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>
+      <p>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.</p>
-      <example caption='Owner modifies affiliations'><![CDATA[
+      <section4 topic='Request' anchor='owner-affilmanage-modify-request'>
+        <p>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.)</p>
+        <example caption='Owner modifies affiliation'><![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>
+      </section4>
+      <section4 topic='Success Case' anchor='owner-affilmanage-modify-success'>
         <example caption='Service responds with success'><![CDATA[
 <iq type='result'
     from='pubsub.shakespeare.lit'
     id='ent2'/>
         ]]></example>
-    </section3>
+      </section4>
-    <section3 topic='Deleting an Entity' anchor='owner-affiliations-delete'>
+      <section4 topic='Error Cases' anchor='owner-affiliations-modify-error'>
-      <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>There are several reasons why the modify-affiliations request might fail:</p>
-    </section3>
+        <ol>
-    <section3 topic='Multiple Simultaneous Modifications' anchor='owner-affiliations-multi'>
+          <li>The requested affiliation is not supported by the node or service.</li>
+          <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 in the following sections.</p>
+        <section5 topic='Affiliation Modification Not Supported' anchor='owner-affilmanage-retrieve-notsupported'>
+          <p>If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; 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='ent1'>
+  <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>
+        </section5>
+        <section5 topic='Affiliation Not Supported' anchor='owner-affiliations-nosuchaffil'>
+          <p>If the node or service does not support the requested affiliation, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; and a feature of "member-affiliation", "outcast-affiliation", or "publisher-affiliation" as appropriate.</p>
+          <example caption='Node or service does not support the requested affiliation'><![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='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>
+        </section5>
+        <section5 topic='Insufficient Privileges' anchor='owner-affilmanage-retrieve-forbidden'>
+          <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>
+        </section5>
+        <section5 topic='Node Does Not Exist' anchor='owner-affilmanage-retrieve-node'>
+          <p>If the node does not exist, the service MUST return an &notfound; error.</p>
+          <example caption='Node does not exist'><![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='cancel'>
+    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
+  </error>
+</iq>
+          ]]></example>
+        </section5>
+      </section4>
+      <section4 topic='Multiple Simultaneous Modifications' anchor='owner-affiliations-multi'>
         <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 &notacceptable;) 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[
@@ -4412,6 +4488,10 @@ And by opposing end them?
 </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 &lt;affiliation/&gt; 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 &lt;affiliation/&gt; elements for the same entity; otherwise the service MUST return a &badrequest; error.</p>
+      </section4>
+    </section3>
+    <section3 topic='Deleting an Entity' anchor='owner-affiliations-delete'>
+      <p>In order to remove an entity from the affiliations list, the owner MUST set the value of the 'affiliation' attribute to "none" and the service MUST remove that entity from the affiliations list and not return it in response to future list requests.</p>
     </section3>
     <section3 topic='Notifying Entities' anchor='owner-affiliations-notify'>
       <p>An implementation MAY send a message to an entity whose affiliation has changed, which MAY contain a &BODY; element specifying natural-language text regarding the affiliation change and which SHOULD contain the modified affiliation data.</p>
@@ -5393,7 +5473,10 @@ And by opposing end them?
   </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>
+    <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.</p>
+    <p>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.</p>
+    <p>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 &notallowed; error, which SHOULD also include a pubsub-specific error condition of &lt;max-items-exceeded/&gt;.</p>
+    <p>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.</p>
   </section2>
 
   <section2 topic='Auto-Subscribing Owners and Publishers' anchor='impl-autosubscribe'>
@@ -6743,6 +6826,7 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=unsubscribe;node=princely_musings
   <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-items-exceeded' 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'/>