Terminates the login session on the web application managed by the current Session object, and reinitializes most of the state information maintained by the object.
This method can be called synchronously or asynchronously, depending on parameters that you pass.
On a successful logout, the Session object sets its connected property to false. If the logout fails, the object leaves its connected property set to true, unless the failure happened because the app cannot access the server.
Once logout( ) is executed, no further communication (other than a login( ) call) can occur between the mobile app and the server until a new login session is established.
Note: If you call logout( ) with no parameters, the method executes synchronously. If you call it passing args, the method executes synchronously or asynchronously, depending on the setting of args.
args
An object that has one property:
async — (Optional) A boolean that, if true, tells logout( ) to execute asynchronously. If false or absent, logout( ) executes synchronously. For an asynchronous call, the method results are returned in the afterLogout event that is fired on the Session object after the method completes. Before calling the method, you can subscribe one or more handlers to this event using the subscribe( ) method on the Session object.
Note: If you include any other properties in args, logout( ) ignores them.
When this method terminates the associated login session, the Session object can be re-used to start a new session. The Session object's properties retain their values, with the following exceptions:
clientContextId is reset to null.
lastSessionXHR is reset to null.
loginHttpStatus is reset to null.
loginResult is reset to null.
userName is reset to null.
Existing JSDOs and catalog information are not affected by logout( ). However, any attempt to call addCatalog( ) or a JSDO method that requires contacting the server results in an Error object being thrown.
For all errors encountered by logout( ), the method also throws an Error object. For detailed information about any unsuccessful logout( ) response returned from the web server, you can check the XMLHttpRequest object (XHR) returned by the lastSessionXHR property. However, note that if the logout( ) call is successful, lastSessionXHR is set to null.
Note: When called asynchronously, any handler for the afterLogout event is passed the same information that is available for the logout( ) method when it is called synchronously, including the Session object that executed logout( ) (with the same property settings) and any Error object that was thrown processing the server response.
Caution: To help ensure that HTTP Forms access to web applications works in certain web browsers, such as Firefox, when the web application is configured for Cross-Origin Resource Sharing (CORS), always call the logout( ) method asynchronously.
Example
The following code fragment calls the logout( ) method without parameters synchronously on the session, empSession. For a similar example with the method called asynchronously, see the reference entry for the afterLogout event. This synchronous example uses try and catch blocks in case logout( ) throws an Error object, and displays a message if it does:
try {
empSession.logout( ); }
catch(errObj) {
var msg;
msg = errObj ? '\n' + errObj.message : ''; if ( empSession.lastSessionXHR === null ) {
alert("logout succeeded");
return;
}
alert("There was an error attempting log out." + msg);
}
async — (Optional) A boolean that, if true, tells logout( ) to execute asynchronously. If false or absent, logout( ) executes synchronously. For an asynchronous call, the method results are returned in the afterLogout event that is fired on the Session object after the method completes. Before calling the method, you can subscribe one or more handlers to this event using the subscribe( ) method on the Session object.