In order to limit the number of items of a result set to be returned, the requesting entity specifies a request type of "set" and the maximum size of the desired subset (via the XML character data of the <max/> element):

The responding entity then returns the first items of the result set in order. The number of items is limited to the requested size:

An entity often needs to retrieve a page of items adjacent to a page it has already received. For examples, when retrieving a complete result set in order page by page, or when a user 'scrolls' forwards one page.

The set of items that match a query MAY change over time, even during the time that a requesting entity pages through the result set (e.g., a set of chatrooms, since rooms can be created and destroyed at any time). The paging protocol outlined in this section is designed so that entities MAY provide the following features:

• Each page of the result set is up-to-date at the time it is sent (not just at the time the first page was sent).
• No items will be omitted from pages not yet sent (even if, after earlier pages were sent, some of the items they contained were removed from the set).
• When paging through the list in order, duplicate items are never received.
• The responding entity maintains no state (or a single minimal state for all requesting entities containing the positions of all recently deleted items).
• Rapid calculation of which items should appear on a requested page by responding entity (even for large result sets).

Note: If a responding entity implements dynamic result sets then receiving entities paging through the complete result set should be aware that it may not correspond to the result set as it existed at any one point in time.

The request for the first page is the same as when Limiting the Number of Items:

Responding entity support for paging through a result set is optional. If it does support paging (not just Limiting the Number of Items), then in each page it returns, the responding entity MUST include <first/> and <last/> elements that specify the unique ID (UID) for the first and last items in the page. If there is only one item in the page, then the first and last UIDs MUST be the same. If there are no items in the page, then the <first/> and <last/> elements MUST NOT be included.

The responding entity may generate these UIDs in any way, as long as the UIDs are unique in the context of all possible members of the full result set. Each UID MAY be based on part of the content of its associated item, as shown below, or on an internal table index. Another possible method is to serialize the XML of the item and then hash it to generate the UID. Note: The requesting entity MUST treat all UIDs as opaque.

The responding entity SHOULD also include the number of items in the full result set (which MAY be approximate) encapsulated in a <count/> element. The <first/> element SHOULD include an 'index' attribute. This integer specifies the position within the full set (which MAY be approximate) of the first item in the page. If that item is the first in the full set, then the index SHOULD be '0'. If the last item in the page is the last item in the full set, then the value of the <first/> element's 'index' attribute SHOULD be the specified count minus the number of items in the last page.

Note: The <count/> element and 'index' attribute enable important functionality for requesting entities (for example, a scroll-bar user-interface component). They MAY be omitted, but only if it would be either impossible or exceptionally resource intensive to calculate reasonably accurate values.

The requesting entity can then ask for the next page in the result set by including in its request the UID of the last item from the previous page (encapsulated in an <after/> element), along with the maximum number of items to return. Note: If no <after/> element is specified, then the UID defaults to "before the first item in the result set" (i.e., effectively an index of negative one).

The first item in the page returned by the responding entity MUST be the item that immediately follows the item that the requesting entity indicated in the <after/> element:

It may sometimes be necessary to return an empty page to the requesting entity. For example, with dynamic result sets the responding entity MAY delete some items from the full result set between requests. Another example occurs when the requesting entity specifies "0" for the maximum number items to return (see Getting the Item Count).

If there are no items whatsoever in the full result set, the responding entity MUST return a response that adheres to the definition of the wrapper protocol (e.g., "jabber:iq:search", "http://jabber.org/protocol/disco#items", or "http://jabber.org/protocol/pubsub"). For both JEP-0055 and JEP-0030, that means the responding entity shall return an empty &QUERY; element; for JEP-0060, that means the responding entity shall return an empty <pubsub/> element; for JEP-0136, that means the responding entity shall return an empty <list/> or <store/> element.

The requesting entity MAY ask for the previous page in a result set by including in its request the UID of the first item from the page that has already been received (encapsulated in a <before/> element), along with the maximum number of items to return.

The last item in the page returned by the responding entity MUST be the item that immediately preceeds the item that the requesting entity indicated it has already received:

The responding entity MUST reply with an 'item-not-found' error if all the following circumstances apply:

1. The item specified by the requesting entity via the UID in the <after/> or <before/> element no longer exists (it was deleted after the previous page was sent).

2. The UID itself cannot be used to derive directly the next item within the set (e.g. the alphabetical or numerical order of the UIDs do not specify the order of the items).

3. The responding entity does not remember the position of the deleted item within the full list. (Even if the responding entity bothers to remember the position of each deleted item, it will typically be necessary to expire that 'state' after an implementation-specific period of time.)

The requesting entity MAY ask for the last page in a result set by including in its request an empty <before/> element, and the maximum number of items to return.

The requesting entity MAY choose not to retrieve pages from the result set in order. (For example, when its user drags a user-interface slider to a radically new position within a very large result set.)

Only if the UID before the start (or after the end) of a desired result set page is not known, then the requesting entity MAY request the page that starts at a particular index within the result set. It does that by including in its request the index of the first item to be returned (encapsulated in an <index/> element), as well as the maximum number of items to return. Note: For reasons mentioned in Paging Forwards Through a Result Set requesting entities SHOULD, where possible, specify pages using a UID instead of an index.

Note: If the responding entity omitted the <count/> element from previous responses for this result set, then the requesting entity SHOULD assume that the responding entity does not support page retrieval by index for this result set (see error below).

The responding entity SHOULD derive the first UID from the specified index (the method used MAY be approximate) before returning the requested result set page in the normal way. If the specified index was "0" then the responding entity SHOULD derive the UID that is the first in the full result set.

Note: The 'index' attribute of the <first/> element MUST be the same as the index specified in the request. If the index specified by the requesting entity is greater than or equal to the number of items in the full set then the responding entity MUST return an empty page (see Paging Forwards Through a Result Set).

If it would be either impossible or exceptionally resource intensive for the responding entity to derive the first UID from the specified index with reasonable accuracy then the responding entity MAY return a &e501; error.

In order to get the item count of a result set without retrieving the items themselves, the requesting entity simply specifies zero for the maximum size of the result set page:

The responding entity then returns the item count, which MAY be approximate rather than precise if determining the exact number of items would be resource-intensive:

Note: The <count/> element MAY be omitted, but only if it would be either impossible or exceptionally resource intensive to calculate reasonably accurate values.

Note: If there are no items in the full result set then the responding entity MUST return a response that adheres to the definition of the wrapper protocol (see Paging Forwards Through a Result Set).

The ®ISTRAR; includes 'http://jabber.org/protocol/rsm' in its registry of protocol namespaces.