Determines if the current JSDOSession object has authorized access to the web application specified by its serviceURI property setting.

This method also causes an offline or online event to fire if it detects that there has been a change in the JSDOSession object's online state.

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

isAuthorized ( )

Promise method signatures

jQuery Promise objects define methods that you can call to 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 isAuthorized( ) 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 isAuthorized( ) 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 isAuthorized( ) was called.
result
One of the following string constant values depending on the JSDOSession authorization or online status identified by isAuthorized( ):
  • progress.data.Session.SUCCESS — An authentication appropriate to the JSDOSession object’s authenticationModel setting previously succeeded and is currently sufficient to give access to the web application specified by its serviceURI setting.
  • progress.data.Session.AUTHENTICATION_FAILURE — An authentication appropriate to the JSDOSession object’s authenticationModel setting previously succeeded, but the JSDOSession is no longer authorized to access its web application, for example, because the login session, established using HTTP Form authentication, has expired.
  • progress.data.Session.LOGIN_AUTHENTICATION_REQUIRED — No successful authentication was completed for this JSDOSession object (there was no login session), or if there was a login session established, the JSDOSession has terminated its access to its web application by logging out.
    Note: This value is also returned when invoking the method after a page refresh if page refresh support is not enabled for the JSDOSession. For more information, see Additional information.
  • progress.data.Session.GENERAL_FAILURE — An error resulted from trying to contact its web application. You might find more information by consulting the info callback parameter.

The authorization status (result parameter value) is determined by whether the JSDOSession object can contact its web application to see if it is allowed access. If a login session was never previously authenticated, the JSDOSession never even tries to contact its web application. This communication also depends on the authenticationModel setting passed to the object’s constructor.

info
A JavaScript object that can have the following properties:
  • xhr — A reference to the XMLHttpRequest object, if any, sent to the web server to make the authorization request to the web application. If no request was made, this property is undefined.
  • offlineReason — A string constant that is set only if isAuthorized( ) determines that the JSDOsession object is disconnected from its web application or its associated application server. The returned value indicates the reason for the JSDOsession offline state. Possible values include some of those returned by a call to the ping( ) method, as follows:
    • progress.data.Session.DEVICE_OFFLINE — The device itself is offline. For example, it might be in airplane mode, or it might be unable to pick up a Wi-Fi or cell signal.
    • progress.data.Session.SERVER_OFFLINE — The web server is not available. For a Rollbase Data Object Service, this is the web server for the public or private cloud. For an OpenEdge Data Object Service, this is the Tomcat Java servlet container.
    • progress.data.Session.WEB_APPLICATION_OFFLINE — The server is running, but the Java web application that implements the Data Object Service is not deployed.

Additional information

The behavior of isAuthorized( ) in a web app after a browser page refresh depends on whether page refresh support is enabled by passing an operative value for the name property in the JSDOSession object constructor.

For example, if page refresh support has not been enabled, regardless of the authentication model, after the user initiates a page refresh, but before a new login session has been established by calling the login( ) method, the callback result parameter is always set to progress.data.Session.LOGIN_AUTHENTICATION_REQUIRED. For more information on page refresh support, see the description of the progress.data.JSDOSession class constructor.

Note: If the JSDOSession authentication model is HTTP Basic, page refresh support is never enabled.

Example

The following code fragment shows how you can use isAuthorized( ) to check the online state of a given JSDOSession object with page refresh support enabled in the JSDOSession constructor:

$(document).ready(function(){
    if (!ablSession) {
        // Create a session if it does not yet exist
        var ablSession = new progress.data.JSDOSession(
             {  serviceURI: "http://localhost:8810/FormFCS",
                authenticationModel: progress.data.Session.AUTH_TYPE_FORM,
                name: "ablSessionKey"   // enable page refresh support
             } );
    }
 
    // Check whether there had been a login and we are still authorized
    ablSession.isAuthorized()
    .done( function(session, result, info) {
        startApp(); // start web app
    })
    .fail( function(session, result, info) {
        switch (result) {
            case progress.data.Session.LOGIN_AUTHENTICATION_REQUIRED:
            case progress.data.Session.AUTHENTICATION_FAILURE:
                showLogin(); // login, then start web app
                break;
            case progress.data.Session.GENERAL_FAILURE:
                // possibly some sort of offline problem
                if (info.offlineReason) {
                    alert("Offline: " + info.offlineReason);
                }
                break;
        }
    });

This web app example initially verifies if the instance variable (ablSession) for a JSDOSession already references an instance and creates the instance if it does not already exist, with HTTP Form authentication and page refresh enabled.

It then immediately calls isAuthorized( ) to determine if an existing login session is already established from a restored prior session state. If it is established and authorized to access its web application, the done( ) callback executes calling startApp(), which is a method that continues web app execution using the restored JSDO login session. If it is not established or authorized (likely for a first-time execution or prior logout), the fail( ) callback executes.

If the fail( ) callback executes either because initial authentication for the JSDOSession has not been done or authorization for a restored JSDOSession failed, it calls showLogin(), which is a method that prompts the user for credentials to call the login( ) method on the JSDOSession and then perhaps call startApp() (or the equivalent) if the new session login succeeds.

If the fail( ) callback executes for some other reason, it displays any available offline status (info.offlineReason) that might be the cause of the failure. Although not shown, it can also inspect the returned XMLHttpRequest object (info.xhr) for more information on the failure.

See also:

name property (JSDOSession class), login( ) method (JSDOSession class), offline event, online event