progress.data.JSDOSession class

The progress.data.JSDOSession is a JavaScript class that provides methods, properties, and events to create and manage a JSDO login session. A JSDO login session includes a single end point (web application) and a single authentication model (Anonymous, HTTP Basic, or HTTP Form), and manages user access to Progress Data Object resources using instances of the progress.data.JSDO class (JSDO). This includes loading the definitions for the Data Object resources that JSDOs can access and starting and managing JSDO login sessions on web servers that provide access to these resources.

This JSDOSession class supports methods for loading Data Service Object resource definitions and managing login sessions only run asynchronously and return jQuery Promises to handle the results in callbacks registered using Promise methods. The information required to instantiate and start JSDO login sessions with JSDOSession objects is handled somewhat differently than with Session objects, including optional support for web app page refresh.

Like a Session object, a JSDOSession object manages user authentication and session identification information in HTTP/S messages sent between JSDOs running in a mobile app and Data Object Services running on a web server, each of which provide access to a set of Data Object resources. The authentication information includes a username and password (user credentials), if necessary, to authenticate a JSDO login session in a web application, which provides a REST transport between a set of Data Object Services and any client mobile app that accesses them. The session identification information includes the URI for the web application and might include a session ID that identifies the JSDO login session and helps to manage interactions between the client and the web application.

To start a JSDO login session for a JSDOSession object to manage, first instantiate the JSDOSession for a particular web application URI and authentication model as required by the web application's security configuration. Then invoke the object's login( ) method. Pass the login( ) method any required user credentials to authenticate JSDOSession access to the web application according to its authentication model. Once started, a login session for a web application supports all Data Object Services that the application provides, each of which can define one or more resources for access by JSDOs.

Each Data Object Service provides a separate JSON file (Data Service Catalog) that defines the schema for its set of resources and the operations to communicate between these resources and the JSDO instances that access them from a mobile app. To create a JSDO instance for a Data Object resource, a JSDOSession object must first load the Catalog that defines the resource using its addCatalog( ) method. This method can load this Catalog from the web application, from some other web location, or from a location on the client where the mobile app runs, and the method can also accept credentials to access a Data Service Catalog that is protected separately from the web application itself.

Once a Data Service Catalog is loaded into a JSDOSession object, you can instantiate a JSDO to access a particular resource defined in that Catalog. Once the JSDOSession is logged into its web application, the JSDO can then access its resource, relying on any authentication information for the login session (if necessary) to authorize this access.

Multiple JSDOs can thus rely on a single JSDOSession object to manage session access to all Data Object Services and their resources defined by the same web application.

Constructor

Instantiates a JSDOSession object that you can use to start and manage a JSDO login session in a web application and load the Data Service Catalog for each supported Data Object Service whose resources are accessed using JSDOs.

Syntax

progress.data.JSDOSession ( options )

options

An object that contains the following configuration properties:

• serviceURI — (Required) A string expression containing the URI of the web application for which to start a JSDO login session. This web application must support one or more Data Object Services in order to create JSDOs for the resources provided by the application. This URI is appended with a string that identifies a resource to access as part of the login process.

  If the mobile app from which you are logging in is a hybrid app that will be installed to run directly in a native device container, or if it is a web app deployed to a different web server from the web application that hosts the JSDO login session, you must specify serviceURI as an absolute URI to the Tomcat server domain or host and port, for example, http://www.progress.com/SportsMobileApp, or perhaps for testing, http://testmach:8980/SportsMobileApp.

  If the mobile app from which you are logging in is a web app deployed to the same Apache Tomcat server as the web application that hosts the JSDO login session, you can specify serviceURI as a relative URI, for example, /SportsMobileApp, which is relative to the deployment end point (Tomcat server domain or host and port).

  Note: Once the login( ) method executes, the value you pass for serviceURI also sets the value of the sessionURI property on the current JSDOSession object, whether or not JSDO login completes successfully.
• authenticationModel — (Optional) A string constant that specifies one of the three authentication models that the JSDOSession object supports, depending on the web application configuration:
  • progress.data.Session.AUTH_TYPE_ANON — (Default) The web application supports Anonymous access. No authentication is required.
  • progress.data.Session.AUTH_TYPE_BASIC — The web application supports HTTP Basic authentication and requires a valid username and password. To have the JSDOSession object manage access to the web application's resources for you, you need to pass these credentials in a call to the JSDOSession object's login( ) method. Typically, you would require the user to enter their credentials into a login dialog provided by your mobile app, either using a form of your own design or using a template provided by Progress Software Corp.
  • progress.data.Session.AUTH_TYPE_FORM — The web application uses Form-based authentication. Like HTTP Basic, Form-based authentication requires user credentials for access to protected resources; the difference is that the web application itself sends a form to the client to get the credentials. However, when you have the JSDOSession object manage access to the web application's resources, you handle Form-based authentication the same way that you handle Basic—get the user's credentials yourself and pass them to the login( ) method. The JSDOSession intercepts the form sent by the web application and handles the authentication without that form being displayed.

  If the web application requires authentication, you must set this value correctly to ensure that users can log in.

  For more information on these authentication models and how to configure them for a web application, see the sections on configuring web server authentication models in the administration documentation for the server hosting your Data Object Service.

• name — (Optional) A string with an operative value that you define to enable page refresh support for a JSDOSession object when it is instantiated for access by a client web app. The operative value can be any value other than the empty string (""), null, or undefined.

  If this page refresh support is enabled, when the web app successfully logs the newly instantiated JSDOSession into its server web application, the object stores the state of its JSDO login session using this name property value as a key. Then, at any time after log in, if the user initiates a browser refresh on the web app page, the JSDOSession object automatically identifies and restores its login session using this value. This helps to ensure, after a page refresh, that the web app does not need to prompt the user again for credentials in order to re-establish its connection to the web application for this JSDOSession.

  If you do not specify an operative value for name (the default), or you specify a non-operative value, such as the empty string (""), null, or undefined, the JSDOSession is instantiated without this page refresh support.

  For more information on how a login session is restored for a JSDOSession object with page refresh support, see the Notes for this class description.

  Note: If you pass the JSDOSession constructor the same value for name as an existing JSDOSession, it will return a JSDOSession using that same key. Both of them have the potential to overwrite each other. You must ensure that you pass a unique name value for each call to the JSDOSession constructor (or the getSession( ) stand-alone function).
  Note: Page refresh supports only Anonymous and Form-based authentication. You cannot enable page refresh support when you set authenticationModel for a JSDOSession to progress.data.Session.AUTH_TYPE_BASIC; in this case, any setting of the name property is ignored. To enable page refresh support, you must set the authenticationModel property to either progress.data.Session.AUTH_TYPE_ANON or progress.data.Session.AUTH_TYPE_FORM.
  Note: To help manage the results of a page refresh for any web app that accesses a JSDO, the JSDOSession class provides an isAuthorized( ) method that you can call to test that an authorized login session is established for a given JSDOSession object. For more information and an example, see the description of the isAuthorized( ) method.

Properties

Methods

Events

Example — Using the JSDOSession class

This example shows how you might create a JSDOSession object using the URI and authentication model of a web application (CustService), log into the web application,and load the Data Service Catalog for a Data Object Service provided by that web application. It creates this login session for a JSDO that is created and accessed by an instance of the JSDO dialect of the Kendo UI DataSource (dataSource), which provides a Customer resource from the Data Object Service for access by a Kendo UI Grid:

var session;

/* create jsdoSession   */
session = new progress.data.JSDOSession(
        { serviceURI: "http://localhost:8980/CustService",
          authenticationModel: progress.data.Session.AUTH_TYPE_FORM
        };

/* create login screen (using UI defined in HTML file) */
window.loginView = kendo.observable( {
    submit: function() {
        var loginParams = {
                 username: this.username,
                 password: this.password) };

        /* log in (also loads CustService.json if it succeeds) */
        session.login(loginParams 
            ).done( // Logged in
            function(session, result, info) {
                session.addCatalog("http://localhost/.../CustService.json" 
                    ).done( // Data Service Catalog loaded
                    function(session, result, details){
                        /* success function – create grid and datasource */
                        $("#grid").kendoGrid( {
                            dataSource: {
                                type: "jsdo",
                                transport: { 
                                    jsdo: { resourceName: "Customer" }
                                },
                                error: function(e) {
                                    console.log("Error: ", e);
                                }
                            },
                            /* etc., other kendoGrid properties */
                        };

                        /* switch UI to show grid */
                        window.location.href = "#grid";
                    }).fail( // Data Service Catalog not loaded 
                    function(session, result, details){
                        alert("Data Service Catalog failed to load");
                }); //JSDOSession addCatalog()

            }).fail( // Not logged in
            function(session, result, info) {
                /* display error message, stay on login screen */
                alert("Login failed");
        }); // JSDOSession login()
    } // observable submit method
} ); // kendo.observable

The JSDO automatically finds and uses the JSDOSession object where its Customer resource is loaded from the Data Service Catalog.

Notes

• The six web-communicating methods of this class, invalidate( ), isAuthorized( ), login( ), addCatalog( ), logout( ), and ping( ), as well as the stand-alone functions, progress.data.getSession( ) and progress.data.invalidateAllSessions( ), all execute asynchronously and return a reference to a jQuery Promise object as the return value when jQuery Promises are supported in the development environment. A Promise is a deferred object that defines methods which, in turn, register callbacks that execute when results are available from the method that returns the Promise. You provide your own code in each callback to handle the results returned for a given Promise method, much like the code you provide in an event callback.

  The primary Promise methods for use with a JSDOSession object include done( ), fail( ), and always( ), which allow you to separately handle the successful, unsuccessful, and all results (respectively) of a JSDOSession method execution. Note that for any given JSDOSession method, the parameter lists for all Promise method callbacks have the same signature. Note also that the callback for the always( ) method executes with the same values in its parameter list as the callback for the done( ) or fail( ) method, whichever one executes with results.

  For more information on the jQuery implementation of Promises and the additional Promise methods that are available to register callbacks, see the following jQuery topics at the specified web locations:

  • Category: Deferred Object — http://api.jquery.com/category/deferred-object/
  • Promise Object — http://api.jquery.com/Types/#Promise
  • .promise — http://api.jquery.com/promise/
• When you have the credentials from a user login, you have two options to create and initialize a JSDO login session:
  1. As shown in the Example — Using the JSDOSession class, manually instantiate the JSDOSession object for a specified network server (web application) and if successful, invoke its login( ) method to start the associated JSDO login session and if successful, invoke its addCatalog( ) method to load one or more Data Service Catalogs and if successful, create one or more JSDO instances to access the resources provided by the initialized Data Object Services.
  2. Make one call to the progress.data.getSession( ) stand-alone function (the standard mechanism provided by the JSDO framework to start a login session), which automatically instantiates the JSDOSession for access to a specified web application, and if successful, invokes its login( ) method to start the login session, and if successful, invokes its addCatalog( ) method to load a single Data Service Catalog. If the getSession( ) invocation is successful, you can then create one or more JSDO instances to access resources provided by the single specified Data Object Service. If you require access to additional Data Object Services, you can also make additional calls to addCatalog( ) to load the Catalogs. If you require access to additional web applications on this network server (or on other network servers, with CORS support), you can make additional calls to getSession( ) to create as many login sessions as necessary.

  At any point during an established login session, you can call the ping( ) method to determine if its JSDOSession object is in an online state and able to access both its web application and associated application server.

  CAUTION: Under certain conditions when a server error occurs, either or both the asynchronous login( ) and addCatalog( ) methods fail to return a result and notify the app that the error has occurred. However, both of these methods provide an option (which is set by default) that can force these methods to return a result after a specified timeout threshold.

  Following is a known set of inclusive conditions that, if all are true, prevent the asynchronous login( ) and addCatalog( ) methods from returning an error result to the app:

  • The app is running on an iOS device.
  • The failure is caused by invalid credentials.
  • The authentication model used to authenticate the credentials is HTTP Basic.

  The option provided to force these methods to return a result is an iOSBasicAuthTimeout property that you can pass to each method in an object parameter. This property specifies a timeout threshold value that when reached forces the method to return an error result to the app in any registered Promise method callback that executes in response to an error result, such as the fail( )callback. The session itself enforces a default timeout threshold for these methods of four (4) seconds, which you can change by setting this property to a different value. A value of zero (0) cancels the timeout threshold entirely, which prevents the method from returning under the specified conditions. Note that any non-zero timeout threshold is only operative for these methods when all of the following conditions are true:

  • The JSDO session uses Basic authentication.
  • The app is running on an iOS device (iPhone, iPad, or iPod), either as a hybrid app or as a web app in a browser (such as Safari).

  Otherwise, no timeout is in effect for either of these methods (and should not be necessary), even if you explicitly set this property to a threshold value in its object argument before invoking the method.

• When your mobile or web app user has signaled their intention to logout, and if necessary for your application, you have three options to terminate one or more current JSDO login sessions, with the following trade-offs:
  1. Invoke the logout( ) method on each JSDOSession object. This both terminates the login session and allows the JSDOSession to start another login session by calling login( ) on it again. Note that this option can pose a security risk and is not recommended, especially for secure logins (other than Anonymous).
  2. Invoke the invalidate( ) method on each JSDOSession object. This both terminates the login session and disables the JSDOSession from any further access, preventing any attempt to start another login session with it.
  3. Invoke the progress.data.invalidateAllSessions( ) stand-alone function. This invokes invalidate( ) on every JSDOSession object that you created using the progress.data.getSession( ) stand-alone function and is currently managing a login session for the app. This is a convenient way to terminate multiple login sessions unless you have a reason to retain one or more of them for further use, such as Anonymous login sessions you might be using to look-up read-only information. In that case, you must call invalidate( ) or logout( ) only for each session you want to terminate.
     Note: If you did not use getSession( ) to create a JSDOSession object, but instantiated the class manually, you can only log out its session or invalidate the object permanently by calling logout( ) or invalidate( ) on the JSDOSession instance manually.
• The behavior of a login session using this class depends on the authentication model of the web server and how its resources are protected and accessed. For more information, see the description of the login( ) method.
• If you have special requirements for sending JSDOSession requests to the web server, you can modify the XMLHttpRequest object that is sent by the JSDOSession object. To do so, assign a callback function as the value of onOpenRequest property.
• You can enable page refresh support accessed by a client web app when you create a JSDOSession instance using either the class constructor or the progress.data.getSession( ) stand-alone function. If you enable page refresh support, when the user initiates a browser page refresh on the web app page and you instantiate the corresponding JSDOSession object with the same name property value, the following JSDOSession properties will have the same values as they did for the corresponding JSDOSession instance before the page refresh was initiated (with one exception):
  • loginResult
  • clientContextId
  • connected
  • loginHttpStatus
  • userName
  • pingInterval
  • authenticationModel (passed to the constructor anyway)
  • serviceURI (passed to the constructor anyway)

  The one exception is if the values of the authenticationModel and serviceURI properties passed to the JSDOSession constructor are different from existing saved values. In this case, the saved data is ignored and cleared out, and a subsequent invocation of the isAuthorized( ) method returns progress.data.Session.LOGIN_AUTHENTICATION_REQUIRED as the result parameter value to any callback registered for the Promise that is returned by the method.

See also

addCatalog( ) method (JSDOSession class), getSession( ) stand-alone function, invalidate( ) method, invalidateAllSessions( ) stand-alone function, isAuthorized( ) method, login( ) method (JSDOSession class), logout( ) method (JSDOSession class), onOpenRequest property, ping( ) method (JSDOSession class), progress.data.JSDO class