This document defines an XMPP extension to enable more advanced search functionality.
WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.
Status: Experimental
Type: Standards Track
Number: 0059
Version: 0.2
Last Updated: 2005-12-22
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: None
Supersedes: None
Superseded By: None
Short Name: rsm
Wiki Page: <http://wiki.jabber.org/index.php/Result Set Manipulation (JEP-0059)>
Email: jls@antepo.com
JID: jlseguineau@im.antepo.com
Email: stpeter@jabber.org
JID: stpeter@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2005 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this JEP has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
In both Service Discovery [1] and Jabber Search [2], it is possible to receive large result sets in response to information requests (e.g., a service discovery items request sent to a Multi-User Chat [3] service or a user directory search on a common first name). Thus it would be helpful to define a protocol extension that enables the following functionality:
This document defines just such a protocol extension.
In order to get the item count of a result set without retrieving the items themselves, the requesting entity specifies a request type of "count":
Example 1. Requesting the Item Count
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='count1'>
<query xmlns='jabber:iq:search'>
<first>Peter</first>
<count xmlns='http://jabber.org/protocol/rsm'/>
</query>
</iq>
The responding entity then returns the item count:
Example 2. Returning the Item Count
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='count1'>
<query xmlns='jabber:iq:search'>
<count xmlns='http://jabber.org/protocol/rsm'>866</count>
</query>
</iq>
In order to limit the number of items to be returned in a result set, the requesting entity specifies a request type of "set" and the maximum size of the desired result set:
Example 3. Requesting a Limit to the Result Set
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='limit1'>
<query xmlns='jabber:iq:search'>
<first>Peter</first>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
</set>
</query>
</iq>
The responding entity then returns a result set limited to the requested size:
Example 4. Returning a Limited Result Set
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='limit1'>
<query xmlns='jabber:iq:search'>
<item jid='stpeter@jabber.org'>
<first>Peter</first>
<last>Saint-Andre</last>
<nick>stpeter</nick>
</item>
<item jid='pgmillard@jabber.org'>
<first>Peter</first>
<last>Millard</last>
<nick>pgmillard</nick>
</item>
.
[8 more items]
.
</query>
</iq>
In order to page through a result set, the requesting entity specifies a request type of "set" as well as the item to start with (initially "0") as well as the maximum number of items to return:
Example 5. Requesting the First Page of a Result Set
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='page1'>
<query xmlns='jabber:iq:search'>
<first>Peter</first>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<start>0</start>
</set>
</query>
</iq>
The responding entity then returns the first page of the result set:
Example 6. Returning the First Page of a Result Set
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='page1'>
<query xmlns='jabber:iq:search'>
<item jid='stpeter@jabber.org'>
<first>Peter</first>
<last>Saint-Andre</last>
<nick>stpeter</nick>
</item>
<item jid='pgmillard@jabber.org'>
<first>Peter</first>
<last>Millard</last>
<nick>pgmillard</nick>
</item>
.
[8 more items]
.
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<start>0</start>
</set>
</query>
</iq>
Naturally, the requesting entity can then ask for the next page in the result set:
Example 7. Requesting the Second Page of a Result Set
<iq type='get' from='stpeter@jabber.org/roundabout' to='users.jabber.org' id='page1'>
<query xmlns='jabber:iq:search'>
<first>Peter</first>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<start>10</start>
</set>
</query>
</iq>
The responding entity then returns the first page of the result set:
Example 8. Returning the First Page of a Result Set
<iq type='result' from='users.jabber.org' to='stpeter@jabber.org/roundabout' id='page1'>
<query xmlns='jabber:iq:search'>
<item jid='peter@pixyland.org'>
<first>Peter</first>
<last>Pan</last>
<nick>peterpan</nick>
</item>
<item jid='peter@rabbit.lit'>
<first>Peter</first>
<last>Rabbit</last>
<nick>prabbit</nick>
</item>
.
[8 more items]
.
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<start>10</start>
</set>
</query>
</iq>
To be defined.
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [4].
The Jabber Registrar [5] shall include 'http://jabber.org/protocol/rsm' in its registry of protocol namespaces.
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/rsm'
xmlns='http://jabber.org/protocol/rsm'
elementFormDefault='qualified'>
<xs:element name='count' type='xs:string'/>
<xs:element name='set'>
<xs:complexType>
<xs:sequence>
<xs:element name='max' type='xs:int' minOccurs='1' maxOccurs='1'/>
<xs:element name='start' type='xs:int' minOccurs='0' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
1. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
2. JEP-0055: Jabber Search <http://www.jabber.org/jeps/jep-0055.html>.
3. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.
4. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
5. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
END