Hello All,
Here are, I'm afraid, some more suggested changes to XEP-136 ;-)
The patch to XEP is attached, however, it's only for example purposes -
I'm nowhere near 100% sure these changes should go to spec in this form at
all, and also it does not include all modifications discussed below.
a) Added server push in "itemremove": this, I think, is more or less clear
- I think it was even mentioned already once on this list.
b) Changed "MUST" to "MAY" in requiring 'start' attribute in "modified"
command: it seems that in current specification 'start' attribute is not
that necessary anymore: for initial replication you'd better not specify
any date at all (so you get all changes that exist on server for
collections of this contact), and for subsequent ones "last" element is
used, as it ensures continuity of changes ('start' does not).
I think we could go even as far as removing 'start' attribute from
"modified" command altogether or at least deprecating it, to discourage
attempts to use it unsafely instead of "last" element. I didn't put that to
spec, though, as I'd like to get at least smb's else comment on that first.
c) "remove" command range specification changes: this one is a bit
controversial ...
"remove" command may be used in two scenarios:
1) Remove single collection: in this form collection specification should
preferably be similar to "retrieve" command, as basically both do the same:
select single collection, it's only that "retrieve" returns it after
selection while "remove" deletes it.
2) Remove collections range: in this form collection specification should
preferably be similar to "list" command, as again - 1st step is the same
for both commands.
However, due to overlap in attributes (both "retrieve" and "list" commands
use the same 'with' and 'start' attributes for different purposes) we
cannot reliably detect what form of "remove" command was specified knowing
attributes names only.
Therefore, current specification attempts to solve that by stating that
'with' + 'start' mean single collection, while 'with' + 'start' + 'end'
mean range.
In my opinion, that creates unnecessary confusion - ranged remove version
doesn't look and work like "list" anymore, and also you have to specify
artificial dates (like 1970 or 2038 year to mean -/+ infinity), which is
also not that nice.
In fact when implementing mod_archive_odbc I even overlooked this 'with' +
'start'/'with' + 'start' + 'end' difference at all as I didn't expect
"remove" to differ from "list" - probably it just means I'm not that good
at reading specs, of course, but it also might mean that current behavior
is unexpected from the other parts of spec.
I see several possibilities here:
* Split "remove" command to "single collection" and "collections range"
versions - by having two different remove commands
("removechat"/"removerange"?) or by adding attribute
("type=single"/"type=multiple", or "multiple=false"/"multiple=true"?).
* Change attributes used for collection range listing/removal: so that
"list"/"remove" (in collections range scenario)/"modified" commands use
smth like "withjids" and "startrange/endrange" to specify JIDs and date
range: then by looking at attributes names we can see what form of "remove"
is used.
* Leave in XEP only ranged removal - as single collection removal is
basically the same as ranged removal with range that selects this single
collection only.
* Decide that it's not worth the trouble and leave everything as is.
For me it looks like "leave in XEP only ranged removal" solution is
currently the easiest one - and the one that changes the smallest number of
things in specification compared to other solutions (well, except of "leave
as it is" one ;-) )
This change might be dangerous for existing implementations, though, as it
means that if anyone is using 'with + 'start' version implemented 100%
accordingly to the spec, then after this change it will remove ALL
collections starting from the given date.
I'm not sure how important it is, though - it doesn't look like a lot of
clients support XEP-136 anyway (I'd be glad to find at least one, in fact
;-) ), so, probably, it should not be _that_ problematic. If it is - we
might also consider changing "remove" command name, so that older client
implementations could not use it destructively.
Here are some other thoughts, not included in XEP patch:
d) I think that currently we do not state clearly enough and have
inconsistency in how end points in the ranged commands are handled: from my
reading of the spec it seems that it's [start, end) (i.e. include 'start'
point and exclude 'end' point) for "list" and "remove", but for "modified"
command it's ('start, ...) (i.e. exclude 'start' point).
This inconsistency in "modified" command was required for proper paging,
but as I wrote above we might remove 'start' attribute completely. Then we
will not have inconsistency here anymore - but it still might be a good
idea to state this policy somehow more explicitly.
Or is it only me who thinks it's not clear enough in its current form?
e) Current specification states that "remove" command should return
"item-not-found" if no collections are matched. It doesn't really look like
behavior I'd expect from "ranged" command, though - and indeed, "list" does
not have it. As far as I understand, this behavior might be necessary to
know that no collections were in fact removed - but then, probably, we
should just solve that by returning number of removed collections in some
attribute, like "removed=0" or "removed=N" in general case? Actually I
think that returning number of removed collections might be a good idea
regardless of "item-not-found" issue ...
Any comments are appreciated!
--
Good luck! AlexanderIndex: xep-0136.xml
===================================================================
--- xep-0136.xml (revision 3466)
+++ xep-0136.xml (working copy)
@@ -404,6 +404,19 @@
<example caption='Server Acknowleges Change'><![CDATA[
<iq type='result' id='remove1' to='[email protected]/chamber'/>
]]></example>
+ <example caption='Server Pushes New Modes'><![CDATA[
+<iq type='set' id='push5' to='[email protected]/chamber'>
+ <itemremove xmlns='urn:xmpp:archive'>
+ <item jid='[email protected]'/>
+ </itemremove>
+</iq>
+
+<iq type='set' id='push6' to='[email protected]/pda'>
+ <itemremove xmlns='urn:xmpp:archive'>
+ <item jid='[email protected]'/>
+ </itemremove>
+</iq>
+ ]]></example>
</section2>
<section2 topic='Setting Archiving Method Preferences' anchor='pref-archive'>
<p>The client can set one or more method preferences by sending an IQ-set containing a <pref/> element that in turn contains one or more <method/> elements.</p>
@@ -421,7 +434,7 @@
]]></example>
<p>If the client includes less than three <method/> elements, the server MUST NOT modify the unspecified methods and MUST leave them as currently stored on the server. However, when the server pushes the method preferences it MUST include all of the preferences, not only those that were set by the client.</p>
<example caption='Server Pushes New Method Preferences'><![CDATA[
-<iq type='set' id='push5' to='[email protected]/chamber'>
+<iq type='set' id='push7' to='[email protected]/chamber'>
<pref xmlns='urn:xmpp:archive'>
<method type='auto' use='concede'/>
<method type='local' use='forbid'/>
@@ -429,7 +442,7 @@
</pref>
</iq>
-<iq type='set' id='push6' to='[email protected]/pda'>
+<iq type='set' id='push8' to='[email protected]/pda'>
<pref xmlns='urn:xmpp:archive'>
<method type='auto' use='concede'/>
<method type='local' use='forbid'/>
@@ -967,40 +980,39 @@
<p>Refer to <cite>Result Set Management</cite> to learn more about the various ways that the pages of a collection may be accessed.</p>
</section2>
<section2 topic='Removing a Collection' anchor='manage-remove'>
- <p>To request the removal of a single collection the client sends an empty <remove/> element. The 'with' and 'start' attributes MUST be included to uniquely identify the collection.</p>
- <example caption='Removing a single collection'><![CDATA[
+ <p>To request collections removal the client sends an empty <remove/> element. The 'with', 'start' and 'end' attributes are interpreted in the same way as in <link url='#manage-list'>Retrieving a List of Collections</link> section of this document.</p>
+ <example caption='Removing all collections with a specified bare JID between two times'><![CDATA[
<iq type='set' id='remove1'>
<remove xmlns='urn:xmpp:archive'
- with='[email protected]/chamber'
- start='1469-07-21T02:56:15Z'/>
+ with='[email protected]'
+ start='1469-07-21T02:00:00Z'
+ end='1469-07-21T04:00:00Z'/>
</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 specify JID of XMPP entities, see the <link url='#impl-jidmatch'>JID Matching</link> section of this document.</p>
- <example caption='Removing all collections with a specified bare JID between two times'><![CDATA[
+ <p>To remove a single collection 'with', 'start' and 'end' attributes MUST be set so that they uniquely identify that collection, i.e. 'with' should equal to collection JID while 'start' and 'end' attributes should both be equal to collection date.</p>
+ <example caption='Removing a single collection'><![CDATA[
<iq type='set' id='remove2'>
<remove xmlns='urn:xmpp:archive'
- with='[email protected]'
- start='1469-07-21T02:00:00Z'
- end='1469-07-21T04:00:00Z'/>
+ with='[email protected]/chamber'
+ start='1469-07-21T02:56:15Z'
+ end='1469-07-21T02:56:15Z'/>
</iq>
]]></example>
- <p>If the 'with' attribute is omitted then collections with any JID are removed.</p>
- <p>If the end date is in the future then all collections on or after the start date are removed.</p>
+ <p>If the end date is not specified then all collections on or after the start date are removed.</p>
<example caption='Removing all collections after a date'><![CDATA[
<iq type='set' id='remove3'>
<remove xmlns='urn:xmpp:archive'
- start='1469-07-21T02:00:00Z'
- end='2038-01-01T00:00:00Z'/>
+ start='1469-07-21T02:00:00Z'/>
</iq>
]]></example>
- <p>If the start date is before all the collections in the archive then all collections prior to the end date are removed.</p>
+ <p>If the start date is not specified then all collections prior to the end date are removed.</p>
<example caption='Removing all collections before a date'><![CDATA[
<iq type='set' id='remove4'>
<remove xmlns='urn:xmpp:archive'
- start='0000-01-01T00:00:00Z'
end='1469-07-21T04:00:00Z'/>
</iq>
]]></example>
+ <p>If the 'with' attribute is omitted then collections with any JID are removed. If both 'start' and 'end' attributes are omitted, then collections with any date are removed.</p>
<example caption='Removing all collections'><![CDATA[
<iq type='set' id='remove5'>
<remove xmlns='urn:xmpp:archive'/>
@@ -1020,12 +1032,13 @@
open='true'/>
</iq>
]]></example>
- <p>If the specified collection (or collections) do not exist then the server MUST return an ¬found; error:</p>
+ <p>If no collections correspond to the request the server MUST return an ¬found; error:</p>
<example caption='Unsuccessful reply'><![CDATA[
<iq type='error' to='[email protected]/orchard' id='remove1'>
<remove xmlns='urn:xmpp:archive'
- with='[email protected]/chamber'
- start='1469-07-21T02:56:15Z'/>
+ with='[email protected]'
+ start='1469-07-21T02:00:00Z'
+ end='1469-07-21T04:00:00Z'/>
<error code='404' type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
@@ -1038,7 +1051,7 @@
<p>This section describes how a client can replicate an archive locally. <note>Clients that run in constrained environments may not be able to implement replication if they are prevented from accessing (sufficient) local storage.</note> The existence of a local copy of the archive enables clients to search the content of all messages (including collections saved by another client machine). <note>Since collections SHOULD be stored on the server in a form that it cannot decrypt, server-side searching of the content of messages is beyond the scope of this protocol.</note></p>
<p>The client can "synchronize" its local copy of the archive with the "master" archive on the server at any time. The first step is to request the list of collections that the server has modified (created, changed, or removed) in its master archive since the last update to the client's copy of the archive.</p>
<p>Replication uses the <modified/> element. The list of collections that have been modified since a given time is requested by sending a <modified/> element to the server. The server then returns the list of collections that have been created, changed, or removed. A collection that has been created or changed is specified with a <changed/> element (with version zero for created collections), and a collection that has been removed is specified with a <removed/> element.</p>
- <p>When requesting the list of modified collections, the client MUST embed appropriate <cite>Result Set Management</cite> data in the <modified/> element. The <modified/> element MUST include a 'start' attribute that specifies a UTC datetime (see <cite>XEP-0082</cite>) that it has previously received from the server or that it has determined locally (e.g., when synchronizing for the first time the client SHOULD choose a suitable time for the first page request, such as 1970-01-01T00:00:00Z).</p>
+ <p>When requesting the list of modified collections, the client MUST embed appropriate <cite>Result Set Management</cite> data in the <modified/> element. The <modified/> element MAY include a 'start' attribute that specifies a UTC datetime (see <cite>XEP-0082</cite>) that it has previously received from the server or that it has determined locally (e.g., when synchronizing for the first time the client MAY choose a suitable time for the first page request, such as 1970-01-01T00:00:00Z). If 'start' attribute is omitted the server returns all modified collections (subject to <cite>Result Set Management</cite> rules).</p>
<example caption='Requesting a page of modifications'><