invalidate( ) method

Terminates the login session managed by the current JSDOSession object and permanently disables the object, rendering it unable to start a new login session.

This method throws an error if the underlying communication layer throws an error.

On a successful invalidate, the JSDOSession object sets its connected property to false. If the invalidate fails to logout the session because it cannot access the server, the object still sets its connected property to false because it is no longer available to manage any login session.

Once invalidate( ) is executed, no further communication can occur between the mobile app and the server using this JSDOSession object. Thus, any call made to its addCatalog( ), isAuthorized( ), login( ), or ping( ) method, or any attempt to instantiate a progress.data.JSDO associated with this JSDOSession object, throws an exception. In addition, any calls to methods on an existing JSDO instance that communicate with the server associated with this JSDOSession throw an exception as well.

This method is always executed asynchronously and returns results in callbacks that you register using methods of a Promise object returned as the method value.

Return type: jQuery Promise

Applies to: progress.data.JSDOSession class

Syntax

invalidate ( )

Promise method signatures

jQuery Promise objects define methods that register a callback function with a specific signature. The callback signatures depend on the method that returns the Promise. Following are the signatures of callbacks registered by methods in any Promise object that invalidate( ) returns:

Syntax:

promise.done( function ( session , result , info ) )
promise.fail( function ( session , result , info ) )
promise.always( function ( session , result , info ) )

promise

A reference to the Promise object that is returned as the value of the invalidate( ) method. For more information on Promises, see the notes on Promises in the description of the progress.data.JSDOSession class.

session

A reference to the JSDOSession object on which invalidate( ) was called.

result

A constant indicating the overall result of the call that can have one of the following values:

• progress.data.Session.SUCCESS — The invalidate of the JSDOSession object completed successfully.
• progress.data.Session.GENERAL_FAILURE — The invalidate failed because of some error.

Note: It is not always necessary to test the value of result in a Promise method callback for the invalidate( ) method, especially if the callback is registered using promise.done( ) or promise.fail( ), where the callback always executes with the same value (progress.data.Session.SUCCESS and progress.data.Session.GENERAL_FAILURE, respectively).

info

A JavaScript object that can have the following properties:

• errorObject — An error object thrown while attempting to terminate the login session.
• xhr — A reference to the XMLHttpRequest object sent to the web server to terminate the login session.

Example

The following code fragment calls the invalidate( ) method on the JSDOsession object, session. This example uses try and catch blocks in case invalidate( ) throws an unexpected exception, and displays messages returned from Promise handlers accordingly:

var serviceURI = "http://oemobiledemo.progress.com/OEMobileDemoServicesForm/",
session = new progress.data.JSDOSession({
            "authenticationModel": progress.data.Session.AUTH_TYPE_FORM,
            "serviceURI": serviceURI
    });

try { // Login, add catalogs, create additional JSDO instances, 
      // and do JSDO tasks for this session, ...then(...) ...
    session.invalidate()
    .then(function(session, result, info) {
        // Success handler of invalidate
        return "Employee session invalidated successfully";
    }, function(session, result, info) {
        // Failure handler of invalidate
        if ( result === progress.data.Session.GENERAL_FAILURE ) {
            if ( info.errorObject ) {
                // Process error object thrown during invalidate...
            }
            if ( info.xhr ) {
                // Process XHR sent during invalidate...
            }
            return "Employee session invalidate failed. Unspecified error.";
        }
        else {
            return "Unexpected failed invalidate result";
        }
    })
    .then(function (msg) {
        console.log(msg);
    });
}
catch(ex) {
    console.log("There was an unexpected error from attempted invalidate: " + ex);
}

See also:

invalidateAllSessions( ) stand-alone function, logout( ) method (JSDOSession class), connected property