skip to main content
OpenEdge Mobile 11.5.1 Updates : Session management updates : progress.data.JSDOSession class
 

progress.data.JSDOSession class

The progress.data.JSDOSession is a JavaScript class that provides methods, properties, and events to manage user access to remote Mobile resources using progress.data.JSDO class instances (JSDOs). This includes loading the definitions for the Mobile resources that JSDOs can access and starting and managing user login sessions on Web servers that provide access to these Mobile resources.
This JSDOSession class supports similar features to the progress.data.Session class, except that JSDOSession methods for loading Mobile resource definitions and managing login sessions only run asynchronously and return jQuery Promises to handle the results, where as the equivalent progress.data.Session methods 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 user login sessions with JSDOSession objects is handled somewhat differently in order to support a more flexible session management model, and the process of loading Mobile resource definitions into a JSDOSession object does not require the object to start a login session as a prerequisite.
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 Mobile services running on a Web server, each of which provide access to a set of Mobile resources. The authentication information includes a user ID and password (user credentials), if necessary, to authenticate a user login session in a Mobile Web application, which provides a REST transport between a set of Mobile services and any client Mobile App that accesses them. The session identification information includes the URI for the Mobile Web application and a client context ID that identifies the user login session and helps to manage interactions between the client and the Mobile Web application.
To start a user login session for a JSDOSession object to manage, you first instantiate the JSDOSession for a particular Mobile Web application and its authentication model, and then invoke the object's login( ) method. You pass the login( ) method any required user credentials to authenticate JSDOSession access to the Mobile Web application according to its authentication model. Once a JSDOSession object is logged in to a Mobile Web application, the Web application provides client access to all Mobile services that the Web application defines, and each of its Mobile services provides access to a defined set of one or more Mobile resources.
Each Mobile service provides a separate JSON file (JSDO catalog) that defines the schema for its set of Mobile resources and the Mobile operations to communicate between these Mobile resources and the JSDO instances that access them from a Mobile App. To create a JSDO instance to access a Mobile resource, a JSDOSession object must load the catalog that defines the resource using its addCatalog( ) method either before or after it logs into the Mobile Web application. This method can load this catalog from the Mobile 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 protected JSDO catalog prior to logging into the Mobile Web application or to access a JSDO catalog that is protected separately from the Mobile Web application itself.
Once a JSDO catalog is loaded into a JSDOSession object, you can instantiate a JSDO to access a particular Mobile resource defined in that catalog. Once the JSDOSession is logged into its Mobile Web application, the JSDO can then access its Mobile 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 Mobile services and their resources defined by the same Mobile Web application.

Constructor

Instantiates a JSDOSession object that you can use to start and manage a user login session in a Mobile Web application and load the JSDO catalog for each supported Mobile 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 Mobile Web application for which to start the user login session. This Mobile Web application must support one or more OpenEdge Mobile services in order to create JSDOs for the service 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 Mobile Web App deployed to the same Apache Tomcat server as the Mobile Web application, 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).
If the Mobile App from which you are logging in is a Mobile Native App that will be installed to run directly in a native device container, or if it is a Mobile Web App deployed to a different Web server from the Mobile Web application, 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.
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 user login completes successfully.
*authenticationModel — (Optional) A string constant that specifies one of the three authentication models that the JSDOSession object supports:
*progress.data.Session.AUTH_TYPE_ANON — The Mobile Web application supports Anonymous access. No authentication is required. This is the default value if you do not specify a value for this property.
*progress.data.Session.AUTH_TYPE_BASIC — The Mobile 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 Mobile 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 Mobile Web application requires authentication, you must set this value correctly to ensure that users can log in.

Properties

Table 3. progress.data.JSDOSession properties
Member
Brief description (See also the reference entry)
Returns a string constant that specifies the authentication model that the current JSDOSession object is using and was passed as an option to the object's class constructor.
Returns the list of URIs successfully used to load JSDO 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 state of the current JSDOSession or Session object, when it last determined if the Mobile Web application it manages is available.
Returns an array of JSDOs that use the current JSDOSession or Session object to communicate with their mobile 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 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 Mobile services that have been loaded for the current JSDOSession or Session object and its Mobile Web application.
Returns the URI to the Mobile 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 user ID passed as a parameter to the most recent call to the login( ) method on the current JSDOSession or Session object.

Methods

Table 4. progress.data.JSDOSession class-instance methods
Member
Brief description (See also the reference entry)
Loads one or more local or remote JSDO catalogs into the current JSDOSession object.
Starts a user login session in a Mobile Web application for the current JSDOSession object by sending an HTTP request with user credentials to the Web application URI specified in the object's constructor.
Terminates the login session on the Mobile Web application managed by the current JSDOSession object, and reinitializes most of the state information maintained by the object.
Determines the online state of the current JSDOSession object from its ability to access the Mobile Web application that it manages, and for an OpenEdge Web application, from detecting if its associated application server is running.
Subscribes a given event handler function to an event of the current JSDOSession object.
Unsubscribes a given event handler function from an event of the current JSDOSession object.
Unsubscribes all event handler functions from a single named event of the current JSDO, JSDOSession or Session object, or unsubscribes all event handler functions from all events of the current JSDO, JSDOSession, or Session object.

Events

Table 5. 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 Mobile 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 Mobile Web application to which it is connected is now available after it was previously unavailable.

Example — Using the OpenEdge JSDOSession class

This is an example of how you might create a JSDOSession object using the URI and authentication model of a Mobile Web application (CustService), log into the Web application, load the JSDO catalog for a Mobile service provided by that Web application, and create a Kendo UI Grid with a JSDO dialect of the Kendo UI DataSource that creates a JSDO for a Customer Mobile resource defined by that Mobile service in the loaded catalog:
var session;

/* create jsdoSession */
session = new progress.data.JSDOSession(
{ serviceURI: "http://localhost/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( // JSDO 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( // JSDO catalog not loaded
function(session, result, details){
alert("JSDO 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 on which a catalog that defines the Customer resource is loaded.

Notes

*The four Web-communicating methods of this class, login( ), addCatalog( ), logout( ), and ping( ), all execute asynchronously, and return a jQuery Promise as the result. A Promise is a deferred object whose methods execute when results from the method that returns the Promise are available. You provide your own code to handle the results returned by 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. The parameter list for all of these primary Promise methods is the same for a given JSDOSession method, but each Promise method returns a slightly different or identical set of parameter values, depending on its function. For example, the always( ) method executes with values in its parameter list that are identical to the values passed to either 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, see the jQuery topics at the following 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/
*Use an instance of this class to call the login( ) method to start a user login session, call the addCatalog( ) method to load one or more JSDO catalogs for the session, and possibly call the logout( ) method to terminate the session. To use the same JSDOSession instance to start a new login session, you must call the logout( ) method first. Call the ping( ) method to determine if the JSDOSession object is in an online state, able to access its Mobile Web application and associated application server.
*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.

See also

addCatalog( ) method (JSDOSession class), login( ) method (JSDOSession class), logout( ) method (JSDOSession class), progress.data.JSDO class