1.2rc2

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

xep-0136.xml

@@ -7,7 +7,7 @@
 <xep>
 <header>
   <title>Message Archiving</title>
-  <abstract>This document defines mechanisms and preferences for the archiving and retrieval of XMPP messages.</abstract>
+  <abstract>This document defines mechanisms and preferences for the server-side archiving and retrieval of XMPP messages.</abstract>
   &LEGALNOTICE;
   <number>0136</number>
   <status>Draft</status>
@@ -35,11 +35,16 @@
   </author>
   &stpeter;
   &infiniti;
+  <author>
+    <firstname>Alexander</firstname>
+    <surname>Tsvyashchenko</surname>
+    <email>lists@ndl.kiev.ua</email>
+  </author>
   <revision>
-    <version>1.1rc1</version>
+    <version>1.1rc2</version>
-    <date>in progress, last updated 2009-04-07</date>
+    <date>in progress, last updated 2009-09-18</date>
     <initials>psa/at</initials>
-    <remark><p>Specified that collection retrieval shall be matched on a full JID only.</p></remark>
+    <remark><p>Specified that collection retrieval shall be matched on a full JID only; .</p></remark>
   </revision>
   <revision>
     <version>1.0</version>
@@ -243,7 +248,7 @@
         <p>If the 'save' attribute is <em>not</em> set to 'false' then is RECOMMENDED to also include an 'expire' attribute, which indicates how many seconds after messages are archived that the server SHOULD delete them.</p>
       </section4>
       <section4 topic='jid Attribute' anchor='pref-syntax-item-jid'>
-        <p>The 'jid' attribute specifies the JabberID of the XMPP entity to which the preferences specified in this &lt;item/&gt; element apply.</p>
+        <p>The 'jid' attribute specifies the JabberID of the XMPP entities to which the preferences specified in this &lt;item/&gt; element apply, see the <link url='#impl-jidmatch'>JID Matching</link> section of this document.</p>
       </section4>
       <section4 topic='otr Attribute' anchor='pref-syntax-item-otr'>
         <p>The 'otr' attribute specifies the user's setting for OTR Mode with regard to the specified JID. The allowable values are:</p>
@@ -433,6 +438,14 @@
 </iq>
     ]]></example>
   </section2>
+  <section2 topic='Server Archiving Preferences Interpretation' anchor='pref-server'>
+    <p>Most archiving preferences are designed for interpretation only by the client. The server MUST NOT take into account any of the archiving preferences when server administration policies <em>require</em> that every message is to be logged automatically. Otherwise, the server MUST interpret the following archiving preferences (and SHOULD NOT interpret any other ones):</p>
+    <ol>
+      <li>The &lt;auto/&gt; element.</li>
+      <li>When performing automatic archiving: the 'save' attribute of the &lt;default&gt; element, and the 'jid' and 'save' attributes of the &lt;item&gt; element.</li>
+      <li>When performing expiration of old messages: the 'jid' and 'expire' attributes of the &lt;item&gt; element.</li>
+    </ol>
+  </section2>
 </section1>
 
 <section1 topic='Off The Record' anchor='otr'>
@@ -565,7 +578,6 @@
   </section2>
   <section2 topic='with Attribute' anchor='collections-with'>
     <p>The 'with' attribute specifies the JID with which the messages were exchanged.</p>
-    <p>If the JID is of the form &LOCALBARE;, any resource matches; if the JID is of the form &DOMAINBARE;, any node matches.</p>
     <p>Inclusion of the 'with' attribute is REQUIRED.</p>
   </section2>
   <section2 topic='from and to Elements' anchor='collections-fromto'>
@@ -822,8 +834,7 @@
   </ol>
   <p>Requirements and protocol flows for each of these use cases are defined below. The protocols to retrieve a list of collections and an indivdual collection both make extensive use of &xep0059;. Clients and servers SHOULD support all the features defined in that protocol.</p>
   <section2 topic='Retrieving a List of Collections' anchor='manage-list'>
-    <p>To request a list of collections, the client sends a &lt;list/&gt; element. The 'start' and 'end' attributes MAY be specified to indicate a date range (the values of these attributes MUST be UTC and adhere to the DateTime format specified in <cite>XEP-0082</cite>). The 'with' attribute MAY be specified to limit the list to a single participating full JID, bare JID or domain.</p>
+    <p>To request a list of collections, the client sends a &lt;list/&gt; element. The 'start' and 'end' attributes MAY be specified to indicate a date range (the values of these attributes MUST be UTC and adhere to the DateTime format specified in <cite>XEP-0082</cite>). The 'with' attribute MAY specify the JIDs of XMPP entities (see the <link url='#impl-jidmatch'>JID Matching</link> section of this document).</p>
-    <p class='box'>Note: Collections are retrieved only based on the full JID of the conversation partner, not bare JIDs (which might result in returning multiple collections). Therefore, the &lt;retrieve/&gt; shall not possess the 'exactmatch' attribute, as can be done for other Message Archiving elements (see the <link url='#impl-exactmatch'>Exact JID Matching</link> section of this document).</p>
     <p>If the 'with' attribute is omitted then collections with any JID are returned. If only 'start' is specified then all collections on or after that date should be returned. If only 'end' is specified then all collections prior to that date should be returned.</p>
     <p>The client SHOULD use <cite>Result Set Management</cite> to limit the number of collections returned by the server in a single stanza, taking care not to request a page of collections that is so big it might exceed rate limiting restrictions.</p>
     <example caption='Requesting the first page of a list with same JID'><![CDATA[
@@ -880,8 +891,8 @@
     <p>Refer to <cite>Result Set Management</cite> to learn more about the various ways that the pages of the list may be accessed.</p>
   </section2>
   <section2 topic='Retrieving a Collection' anchor='manage-retrieve'>
-    <p>To request a page of messages from a collection the client sends a &lt;retrieve/&gt; element. The 'with' and 'start' attributes specify the participating full JID and the start time (see <cite>XEP-0082</cite>). Both attributes MUST be included to uniquely identify a collection.</p>
+    <p>To request a page of messages from a collection the client sends a &lt;retrieve/&gt; element. The 'with' and 'start' attributes specify the participating JID and the start time (see <cite>XEP-0082</cite>). Both attributes MUST be included to uniquely identify a collection.</p>
-    <p>In addition, the client MAY match an exact bare JID &BAREJID; by setting the boolean 'exactmatch' attribute to a value of "true" or "1" &BOOLEANNOTE; -- for details, refer to the <link url='#impl-exactmatch'>Exact JID Matching</link> section of this document.</p>
+    <p class='box'>Note: the &lt;retrieve/&gt; SHALL NOT possess the 'exactmatch' attribute, because exact JID matching is always implied for this command (see the <link url='#impl-jidmatch'>JID Matching</link> section of this document). This is done to prevent the return of multiple collections in response to the &lt;retrieve/&gt; command.</p>
     <p>The client SHOULD use <cite>Result Set Management</cite> to limit the number of messages returned by the server in a single stanza, taking care not to request a page of messages that is so big it might exceed rate limiting restrictions.</p>
     <example caption='Requesting the first page of a collection'><![CDATA[
 <iq type='get' id='page1'>
@@ -964,8 +975,7 @@
           start='1469-07-21T02:56:15Z'/>
 </iq>
     ]]></example>
-    <p>The client may remove several collections at once. The 'start' and 'end' elements MAY be specified to indicate a date range. The 'with' attribute MAY be a full JID, bare JID or domain.</p>
+    <p>The client MAY remove several collections at once. The 'start' and 'end' elements MAY be specified to indicate a date range. The 'with' attribute MAY specify JID of XMPP entities, see the <link url='#impl-jidmatch'>JID Matching</link> section of this document.</p>
-    <p>In addition, the client MAY match an exact bare JID &BAREJID; by setting the boolean 'exactmatch' attribute to a value of "true" or "1" &BOOLEANNOTE; -- for details, refer to the <link url='#impl-exactmatch'>Exact JID Matching</link> section of this document.</p>
     <example caption='Removing all collections with a specified bare JID between two times'><![CDATA[
 <iq type='set' id='remove2'>
   <remove xmlns='urn:xmpp:archive'
@@ -1032,15 +1042,14 @@
   <example caption='Requesting a page of modifications'><![CDATA[
 <iq type='get' id='sync1'>
   <modified xmlns='urn:xmpp:archive'
-            start='1469-07-21T01:14:47Z'
+            start='1469-07-21T01:14:47Z'/>
-            version='3'/>
     <set xmlns='http://jabber.org/protocol/rsm'>
       <max>50</max>
     </set>
   </modified>
 </iq>
   ]]></example>
-  <p>The server MUST return the changed collections in the chronological order that they were changed (most recent last). If a collection has been modified, created, or removed <em>after</em> the time specified by the 'start' attribute, then the server MUST include it in the returned result set page of collections (unless the specified maximum page size would be exceeded). Each &lt;changed/&gt; or &lt;removed/&gt; collection element (for modified/created, or removed collections respectively) in the returned list MUST include the 'with' and 'start' attribues (and MAY include the 'exactmatch' attribute if that was specified in the request). The XML character data of the &lt;last/&gt; element is a unique, persistent identifier created by the server, which MUST be treated as opaque by the client.</p>
+  <p>The server MUST return the changed collections in the chronological order that they were changed (most recent last). If a collection has been modified, created, or removed <em>after</em> the time specified by the 'start' attribute, then the server MUST include it in the returned result set page of collections (unless the specified maximum page size would be exceeded). Each &lt;changed/&gt; or &lt;removed/&gt; collection element (for modified/created, or removed collections respectively) in the returned list MUST include the 'with' and 'start' attribues. The XML character data of the &lt;last/&gt; element is a unique, persistent identifier created by the server, which MUST be treated as opaque by the client.</p>
   <example caption='Receiving a page of modifications'><![CDATA[
 <iq type='result' to='romeo@montague.net/orchard' id='sync1'>
   <modified xmlns='urn:xmpp:archive'>
@@ -1063,8 +1072,7 @@
   <example caption='Requesting the next page of modifications'><![CDATA[
 <iq type='get' id='sync2'>
   <modified xmlns='urn:xmpp:archive'
-            start='1469-07-21T01:14:47Z'
+            start='1469-07-21T01:14:47Z'/>
-            version='3'/>
     <set xmlns='http://jabber.org/protocol/rsm'>
       <after>ja923ljasnvla09woei777</after>
       <max>50</max>
@@ -1107,8 +1115,14 @@
 </section1>
 
 <section1 topic='Implementation Notes' anchor='impl'>
-  <section2 topic='Exact JID Matching' anchor='impl-exactmatch'>
+  <section2 topic='JID Matching' anchor='impl-jidmatch'>
-    <p>When the 'exactmatch' attribute is set to "true" or "1" on an element of &lt;item/&gt;, &lt;list/&gt;, or &lt;remove/&gt;, a 'with' value such as "example.com" matches that exact JID only rather than &lt;*@example.com&gt;, &lt;*@example.com/*&gt;, or &lt;example.com/*&gt;, and a 'with' value such as "localpart@example.com" matches that exact JID only rather than &lt;localpart@example.com/*&gt;.</p>
+    <p>&lt;list/&gt;, &lt;remove/&gt; commands and &lt;item/&gt; element in archiving preferences require the ability to match multiple collections by given JID. Therefore, the following rules apply.</p>
+    <ol>
+      <li>If the JID is of the form &LOCALFULL;, only this particular JID matches.</li>
+      <li>If the JID is of the form &LOCALBARE;, any resource matches.</li>
+      <li>If the JID is of the form &DOMAINBARE;, any node matches.</li>
+    </ol>
+    <p>However, having these rules only would make impossible a match like "all collections having JID exactly equal to bare JID/domain JID". Therefore, when the 'exactmatch' attribute is set to "true" or "1" &BOOLEANNOTE; on the &lt;list/&gt;, &lt;remove/&gt; or &lt;item/&gt; element, a JID value such as "example.com" matches that exact JID only rather than &lt;*@example.com&gt;, &lt;*@example.com/*&gt;, or &lt;example.com/*&gt;, and a JID value such as "localpart@example.com" matches that exact JID only rather than &lt;localpart@example.com/*&gt;.</p>
   </section2>
   <section2 topic='Time Synchronization' anchor='impl-sync'>
     <p>When creating a new collection, it is RECOMMENDED that the client synchronizes the collection start time that it sends to the server with server time. This is important since the user may subsequently retrieve the archived collection using client machines whose UTC clocks are not synchronized with the client machine that uploaded the collection. (i.e. Either or both of the clients' UTC clocks may be wrong.) The client can achieve this synchronization with server time by using &xep0202; to estimate the difference between the server and client UTC clocks.</p>
@@ -1120,6 +1134,11 @@
   <section2 topic='Storage Considerations' anchor='impl-storage'>
     <p>Server implementations SHOULD give system administrators the option to disable support for both automatic and manual archiving, since archived conversations can consume significant storage space.</p>
   </section2>
+  <section2 topic='Conversations Tracking In Automatic Archiving' anchor='impl-convtracking'>
+    <p>When starting automatic archiving for a new conversation, it is possible that the initial message might not be enough to determine the full JID of the recipient. For example, if the conversation is initiated by a client whose server performs automatic archiving and that client does not know which full JID it ought to use for the recipient, it will send the initial message to bare JID. As a result, automatic archiving will create a collection that is identified by the bare JID of the recipient.</p>
+    <p>However, once the client receives a reply from the contact, it knows the full JID of the recipient. At that point, the initial collection can be adjusted, changing the bare JID to the full JID of the recipient.</p>
+    <p>The server SHOULD attempt to perform conversation tracking and JID adjustment to ensure that the identifying JID for the collection reflects the actual full JID used during conversation rather than initial bare JID used when the conversation started. However, the server MAY use the bare JID for the collection if there is evidence that the conversation involves several different full JIDs, such as receiving messages from different full JIDs with the same &lt;thread/&gt; element.</p>
+  </section2>
 </section1>
 
 <section1 topic='Stream Feature' anchor='streamfeature'>
@@ -1214,7 +1233,6 @@
     <xs:complexType>
       <xs:simpleContent>
         <xs:extension base='empty'>
-          <xs:attribute name='exactmatch' type='xs:boolean' use='optional'/>
           <xs:attribute name='start' type='xs:dateTime' use='required'/>
           <xs:attribute name='with' type='xs:string' use='required'/>
           <xs:attribute name='version' type='xs:nonNegativeInteger' use='required'/>
@@ -1427,7 +1445,6 @@
     <xs:complexType>
       <xs:simpleContent>
         <xs:extension base='empty'>
-          <xs:attribute name='exactmatch' type='xs:boolean' use='optional'/>
           <xs:attribute name='start' type='xs:dateTime' use='required'/>
           <xs:attribute name='with' type='xs:string' use='required'/>
           <xs:attribute name='version' type='xs:nonNegativeInteger' use='required'/>