JSDO class and object reference : progress.data.JSDOSession class
  

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 similar features to the progress.data.Session class, except that JSDOSession 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, whereas the equivalent progress.data.Session methods can either run synchronously or fire asynchronous events to allow results to be handled in separately registered callbacks. In addition, 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 (available in Progress Data Objects Version 4.3 or later).
Note: If your development environment does not support jQuery Promises (or the exact equivalent), you must use the progress.data.Session class to manage login sessions for JSDOs. For more information, see the description of the progress.data.Session class.
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.
Note: The standard mechanism supported by the JSDO framework to invoke most of the features of instantiating a JSDOSession object, establishing its JSDO login session, and loading a Data Service Catalog, is to invoke a single call to the progress.data.getSession( ) stand-alone function. For more information, see the getSession( ) stand-alone function description. (Available in Progress Data Objects Version 4.3 or later.) Also, see the Notes on this class.
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).
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; available in Progress Data Objects Version 4.3 or later) 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.
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).
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.
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.
Note: The standard mechanism supported by the JSDO framework to invoke most of the features of instantiating a JSDOSession object, establishing its JSDO login session, and loading a Data Service Catalog, is to invoke a single call to the progress.data.getSession( ) stand-alone function. For more information, see the getSession( ) stand-alone function description. (Available in Progress Data Objects Version 4.3 or later.) Also, see the Notes on this class.

Properties

Table 17. progress.data.JSDOSession properties
Member
Brief description (See also the reference entry)
Returns a string constant that was passed as an option to the object's class constructor, and specifies the authentication model that the current JSDOSession object requires to start a JSDO login session in the web application for which the JSDOSession object was also created.
Returns the list of URIs successfully used to load Data Service Catalogs into the current JSDOSession or Session object.
The value of the most recent client context identifier (CCID) that the current JSDOSession or Session object has found in the X-CLIENT-CONTEXT-ID HTTP header of a server response message.
Returns a boolean that indicates the most recent online status of the current JSDOSession or Session object when it last determined if the web application it manages was available.
Returns an array of JSDOs that use the current JSDOSession or Session object to communicate with their Data Object Services.
Returns the specific HTTP status code returned in the response from the most recent login attempt on the current JSDOSession or Session object.
Returns the return value of the login( ) method, which is the basic result code for the most recent login attempt on the current JSDOSession or Session object.
Returns the value of any name property to enable page refresh support that was passed to the constructor of the current JSDOSession object.
Note: Applies to Progress Data Objects Version 4.3 or later.
Returns the reference to a user-defined callback function that the JSDOSession or Session object executes to modify a request object before sending the request object to the server.
A number that specifies the duration, in milliseconds, between one automatic execution of the current JSDOSession or Session object's ping( ) method and the next.
Returns an array of objects that identifies the Data Object Services that have been loaded for the current JSDOSession or Session object and its web application.
Returns the URI to the web application that has been passed as an option to the class constructor for the current JSDOSession object or that has been passed as a parameter to the most recent call to the login( ) method on the current Session object, whether or not the most recent call to login( ) succeeded.
Returns the username passed as a parameter to the most recent call to the login( ) method on the current JSDOSession or Session object.

Methods

Table 18. progress.data.JSDOSession class-instance methods
Member
Brief description (See also the reference entry)
Loads one or more local or remote Data Service Catalogs into the current JSDOSession object.
Terminates the login session managed by the current JSDOSession object and permanently disables the object, rendering it unable to start a new login session.
Note: Applies to Progress Data Objects Version 4.4.1 or later.
Determines if the current JSDOSession object has authorized access to the web application specified by its serviceURI property setting.
Note: Applies to Progress Data Objects Version 4.3 or later.
Starts a JSDO login session in a web application for the current JSDOSession object by sending an HTTP request with specified user credentials to the web application URI specified in the object's constructor.
Terminates the login session on the web application managed by the current JSDOSession object and leaves the object available to start a new login session with a call to its login( ) method.
Determines the online state of the current JSDOSession object from its ability to access the web application that it manages, and for an OpenEdge web application, from detecting if its associated application server is running.
Subscribes a given event callback function to an event of the current JSDOSession object.
Unsubscribes a given event callback function from an event of the current JSDOSession object.
Unsubscribes all event callback functions from a single named event of the current JSDO, JSDOSession or Session object, or unsubscribes all event callback functions from all events of the current JSDO, JSDOSession, or Session object.

Events

Table 19. progress.data.JSDOSession events
Member
Brief description (See also the reference entry)
Fires when the current JSDOSession or Session object detects that the device on which it is running has gone offline, or that the web application to which it has been connected is no longer available.
Fires when the current JSDOSession or Session object detects that the device on which it is running has gone online after it was previously offline, or that the web application to which it is connected is now available after it was previously unavailable.

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.
For more information on using the JSDO dialect of the Kendo UI DataSource, see Using the JSDO dialect of the Kendo UI DataSource .

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 Objecthttp://api.jquery.com/category/deferred-object/
*Promise Objecthttp://api.jquery.com/Types/#Promise
*.promisehttp://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.
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 (available in Progress Data Objects Version 4.3 or later) 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