<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-10-07</date>
<initials>jjh/psa</initials>
<remark><p>Added more detailed error flows; added additional implementation notes.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-10-07</date>
<initials>jjh/psa</initials>
<remark>
<ul>
<li>Specified that notifications are sent to only one subscriber at a time.</li>
<li>Specified that notifications include payloads.</li>
<li>Added protocol extension for unlock feature.</li>
<li>Modified namespace to incorporate namespace versioning.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-08-14</date>
<initials>psa/jjh</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>The &xep0060; extension to XMPP provides a comprehensive technology for alerts, notifications, data syndication, rich presence, and other real-time messaging use cases. In terms of traditional publish-subscribe systems like Java Message Service (JMS), the core XMPP PubSub specification covers the Observer design pattern only; however, traditional publish-subscribe systems often include support for a second design pattern, usually called the "point-to-point" or "queueing" pattern. <note>See for instance <<linkurl='http://en.wikipedia.org/wiki/Java_Message_Service'>http://en.wikipedia.org/wiki/Java_Message_Service</link>>.</note> This specification defines a few small extensions to XMPP PubSub that enable support for a queueing mode in XMPP. The queueing mode is an add-on feature that a service can support, and that a node owner can enable if supported by the service. The feature name is "urn:xmpp:pubsub:queueing:0".</p>
</section1>
<section1topic='How It Works'anchor='howitworks'>
<section2topic='Subscribing'anchor='subscribe'>
<p>If a node has enabled support for the queueing mode, in response to a subscription request without configuration options it MUST return an IQ-error containing a subscription options form; this form MUST include the "queue_requests" field (which specifies the number of parallel requests a subscriber is willing to process).</p>
<examplecaption='Service indicates that subscription configuration is required'><![CDATA[
<p>If the subscription request can be processed successfully, the service returns an IQ-result and includes the configuration options established during the negotiation.</p>
<examplecaption='Service replies with success (including configuration options)'><![CDATA[
<section2topic='Deleting an Item from the Queue'anchor='delete'>
<p>When the subscriber that received the item has successfully processed it (whatever that means in the context of the queue), the subscriber deletes the item from the queue.</p>
<examplecaption='Entity deletes an item from a node'><![CDATA[
<iqfrom='workerbee237@shakespeare.lit/foo'
id='delete1'
to='workflows.shakespeare.lit'
type='get'>
<pubsubxmlns='http://jabber.org/protocol/pubsub'>
<retractnode='a290fjsl29j19kjb'>
<itemid='ae890ac52d0df67ed7cfdf51b644e901'/>
</retract>
</pubsub>
</iq>
]]></example>
<p>In the context of a queue node, the service MUST treat a delete request from a subscriber that received the item as if the sender were a publisher; i.e., it MUST delete the item from the queue and notify only this subscriber that the item has been deleted.</p>
<p>Note: The subscriber SHOULD NOT commit any pending transactions until it receives the delete notification.</p>
<p>If the item does not exist, the service MUST return an ¬found; error as described in <cite>XEP-0060</cite>.</p>
<p>If the entity that attempts to delete the item is not the subscriber that received the item, the service MUST return a &forbidden; error as described in <cite>XEP-0060</cite>.</p>
<p>If the item is locked by another subscriber, the service MUST return a &conflict; error (this flow is not defined in <cite>XEP-0060</cite>.</p>
<examplecaption='Item is locked by another subscriber'><![CDATA[
<p>If the subscriber that received the item attempts to delete the item but the item is no longer locked by the subscriber (e.g., because of a race condition or a lost notification), the service MUST return an &unexpected; error (this flow is not defined in <cite>XEP-0060</cite>.</p>
<examplecaption='Item is no longer locked by subscriber'><![CDATA[
<section2topic='Unlocking an Item'anchor='unlock'>
<p>The subscriber might determine that it cannot process the item (whatever that means in the context of the queue); if so, the subscriber unlocks the item.</p>
<examplecaption='Entity unlocks an item'><![CDATA[
<iqfrom='workerbee237@shakespeare.lit/foo'
id='unlock1'
to='workflows.shakespeare.lit'
type='get'>
<pubsubxmlns='http://jabber.org/protocol/pubsub'>
<unlockxmlns='urn:xmpp:pubsub:queueing:0'
node='a290fjsl29j19kjb'>
<itemid='ae890ac52d0df67ed7cfdf51b644e901'/>
</unlock>
</pubsub>
</iq>
]]></example>
<p>The service then MUST unlock the item and notify only this subscriber that the item has been unlocked.</p>
<p>When an item is unlocked, the service would then send a publish notification to another subscriber according to application-specific logic for determining the "next" subscriber.</p>
<p>If the item does not exist, the service MUST return an ¬found; error.</p>
<p>If the subscriber that received the item attempts to unlock the item but the item is no longer locked by the subscriber (e.g., because of a race condition or a lost notification), the service MUST return an &unexpected; error.</p>
<examplecaption='Item is no longer locked by subscriber'><![CDATA[
<p>If a pubsub service supports the queueing mode, it MUST advertise support for the "urn:xmpp:pubsub:queueing:0" namespace in response to &xep0030; information requests.</p>
<p>If the service receives unavailable presence from a subscriber, it SHOULD unlock all outstanding queue items associated with the subscriber and unsubscribe the subscriber to prevent delivery of further publish notifications.</p>
<p>If a subscriber cannot process queue items because of an unrecoverable error (e.g., disk full), the subscriber SHOULD unsubscribe and then unlock all of its outstanding queue items.</p>
<p>If the service does not receive a delete or unlock request from a subscriber that received a queue item in a configurable amount of time, it SHOULD timeout the request, send an unlock notification to the subscriber, and send a publish notification to the "next" subscriber.</p>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:pubsub:queueing:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
<p>The ®ISTRAR; maintains a registry of service discovery features (see &DISCOFEATURES;), which includes a number of features that can be returned by pubsub services. The following registry submission supplements the existing list.</p>
<code><![CDATA[
<var>
<name>urn:xmpp:pubsub:queueing:0</name>
<desc>The node or service supports the queueing mode.</desc>