updates #339.

* The JID is only required when using keepalive with prebind.
* Provide a logout API method.

converse.js

@@ -5290,20 +5290,32 @@
             }
         };
 
+        this.startNewBOSHSession = function () {
+            $.ajax({
+                url:  this.prebind_url,
+                type: 'GET',
+                success: function (response) {
+                    this.session.save({rid: response.rid});
+                    this.connection.attach(
+                            response.jid,
+                            response.sid,
+                            response.rid,
+                            this.onConnect
+                    );
+                }.bind(this),
+                error: function (response) {
+                    delete this.connection;
+                    this.emit('noResumeableSession');
+                }.bind(this)
+            });
+        };
+
         this.initConnection = function () {
             var rid, sid, jid;
             if (this.connection && this.connection.connected) {
                 this.setUpXMLLogging();
                 this.onConnected();
             } else {
-                // XXX: it's not yet clear what the order of preference should
-                // be between RID and SID received via the initialize method or
-                // those received from sessionStorage.
-                //
-                // What do you we if we receive values from both avenues?
-                //
-                // Also, what do we do when the keepalive session values are
-                // expired? Do we try to fall back?
                 if (!this.bosh_service_url && ! this.websocket_url) {
                     throw("Error: you must supply a value for the bosh_service_url or websocket_url");
                 }
@@ -5326,40 +5338,28 @@
                     }
                 }
                 if (this.keepalive) {
-                    if (!this.jid) {
-                        throw("When using 'keepalive', you must supply the JID of the current user. ");
-                    }
                     rid = this.session.get('rid');
                     sid = this.session.get('sid');
                     jid = this.session.get('jid');
-                    if (rid && sid && jid && Strophe.getBareJidFromJid(jid) === Strophe.getBareJidFromJid(this.jid)) {
-                        // The RID needs to be increased with each request.
-                        this.session.save({rid: rid});
-                        this.connection.attach(jid, sid, rid, this.onConnect);
-
-                    } else if (this.prebind) {
-                        if (this.prebind_url) {
-                            $.ajax({
-                                url:  this.prebind_url,
-                                type: 'GET',
-                                success: function (response) {
-                                    this.session.save({rid: rid});
-                                    this.connection.attach(
-                                            response.jid,
-                                            response.sid,
-                                            response.rid,
-                                            this.onConnect
-                                    );
-                                }.bind(this),
-                                error: function (response) {
-                                    delete this.connection;
-                                    this.emit('noResumeableSession');
-                                }.bind(this)
-                            });
+                    if (this.prebind) {
+                        if (!this.jid) {
+                            throw("When using 'keepalive' with 'prebind, you must supply the JID of the current user.");
+                        }
+                        if (rid && sid && jid && Strophe.getBareJidFromJid(jid) === Strophe.getBareJidFromJid(this.jid)) {
+                            this.session.save({rid: rid}); // The RID needs to be increased with each request.
+                            this.connection.attach(jid, sid, rid, this.onConnect);
+                        } else if (this.prebind_url) {
+                            this.startNewBOSHSession();
                         } else {
                             delete this.connection;
                             this.emit('noResumeableSession');
                         }
+                    } else {
+                        // Non-prebind case.
+                        if (rid && sid && jid) {
+                            this.session.save({rid: rid}); // The RID needs to be increased with each request.
+                            this.connection.attach(jid, sid, rid, this.onConnect);
+                        }
                     }
                 }
             }
@@ -5439,6 +5439,11 @@
         'initialize': function (settings, callback) {
             converse.initialize(settings, callback);
         },
+        'account': {
+            'logout': function () {
+                converse.logOut();
+            },
+        },
         'settings': {
             'get': function (key) {
                 if (_.contains(Object.keys(converse.default_settings), key)) {

docs/CHANGES.rst

@@ -8,6 +8,8 @@ Changelog
 * New configuration setting ``allow_contact_removal``. [jcbrand]
 * Document that event handlers receive 'event' obj as first arg. [jcbrand]
 * Add a test to check that notifications are played in chat rooms. [jcbrand] 
+* #339 Require the JID to be specified when using ``keepalive`` with
+  ``prebind``. Also add a logout API method. [jcbrand]
 
 0.9.0 (2015-03-06)
 ------------------

docs/source/configuration.rst

@@ -169,7 +169,8 @@ The Jabber ID or "JID" of the current user. The JID uniquely identifies a user
 on the XMPP network. It looks like an email address, but it's used for instant
 messaging instead.
 
-This value needs to be provided when using the :ref:`keepalive` option.
+This value needs to be provided when using the :ref:`keepalive` option together
+with `prebind`_.
 
 
 .. _`keepalive`:
@@ -182,11 +183,11 @@ Default:    ``true``
 Determines whether Converse.js will maintain the chat session across page
 loads.
 
-When using keepalive, you will have to provide the `jid`_ of the current user
-to ensure that a cached session is only resumed if it belongs to the current
-user.
+This setting should also be used in conjunction with :ref:`prebind`.
 
-This setting should also be used in conjunction with :ref:`prebind` and :ref:`keepalive`.
+When using ``keepalive`` and ``prebind``, you will have to provide the `jid`_
+of the current user to ensure that a cached session is only resumed if it
+belongs to the current user.
 
 See also:
 
@@ -350,8 +351,9 @@ Here's an example of converse.js being initialized with these three options:
 .. note:: The ``prebind_url`` configuration setting is new in version 0.9 and
     simplifies the code needed to set up and maintain prebinded sessions.
 
-    When using ``prebind_url`` and ``keepalive``, you don't need to manually pass in
-    the RID, SID tokens anymore, but you still need to provide the JID.
+    When using ``prebind``, ``prebind_url`` and ``keepalive``, you don't need
+    to manually pass in the RID, SID tokens anymore, but you still need to
+    provide the JID.
 
 
 .. _`prebind_url`: