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

progress.data.Session class

Note: Deprecated in Progress Data Objects Version 4.4 and later. Please use the progress.data.JSDOSession class instead.
The progress.data.Session 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 Session class supports similar features to the progress.data.JSDOSession class, except that Session methods for loading Data Service Object resource definitions and managing login sessions can either run synchronously or fire asynchronous events to allow results to be handled in separately registered callbacks, whereas the equivalent progress.data.JSDOSession methods run asynchronously only and return jQuery Promises to handle the results in callbacks registered using Promise methods. In addition, the information required to instantiate and start JSDO login sessions with Session objects is handled somewhat differently than with JSDOSession objects.
Note: If you are creating JSDO login sessions to work with the JSDO dialect of the Kendo UI DataSource, Progress recommends using the progress.data.JSDOSession class to manage login sessions for JSDOs. Note that to use JSDOSession objects, your development environment must also support jQuery Promises (or the exact equivalent), similar to the Telerik Platform. For more information, see the description of the progress.data.JSDOSession class. For more information on the JSDO dialect of the Kendo UI DataSource, see Using the JSDO dialect of the Kendo UI DataSource .
Like a JSDOSession object, a Session 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 Session object to manage, first instantiate the Session object and ensure that you have set the object's authenticationModel property to the correct authentication model for the session as required by the web application's security configuration. Then invoke the login( ) method on the Session object, passing as parameters the web application URI, any required user credentials to authenticate Session access to the web application according to its authentication model, and an optional specified web application resource (such as a static HTML page) used to authenticate access. 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 Session 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 Session object, you can instantiate a JSDO to access a particular resource defined in that Catalog. Once the Session 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 Session object to manage session access to all Data Object Services and their resources defined by the same web application.

Constructor

Instantiates a Session object that you can use to start a JSDO login session for a web application and load the Data Service Catalog for each supported Data Object Service whose resources are accessed using JSDOs.
Syntax
progress.data.Session ( )

Properties

Table 23. progress.data.Session properties
Member
Brief description (See also the reference entry)
A string constant that you can set to specify the authentication model that a given web application requires for a mobile app to start a JSDO login session for this Session object.
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 an object reference to the XMLHttpRequest object (XHR) that was most recently used by the progress.data.Session object to execute a Session object method.
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 string appended to the web application URI passed to the login( ) method to form the URI of an application resource against which the user has been authenticated for the current login session.
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 24. progress.data.Session class-instance methods
Member
Brief description (See also the reference entry)
Loads a local or remote Data Service Catalog into the current Session object.
Starts a JSDO login session on the current Session object by sending an HTTP request with specified user credentials to the URI of a specified web application.
Terminates the login session on the web application managed by the current Session object, and reinitializes most of the state information maintained by the object.
Determines the online state of the current Session 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 Session object.
Unsubscribes a given event callback function from an event of the current Session 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 25. progress.data.Session events
Member
Brief description (See also the reference entry)
Fires when the addCatalog( ) method on the current Session object completes execution after it was called asynchronously.
Fires when the login( ) method on the current Session object completes execution after it was called asynchronously.
Fires when the logout( ) method on the current Session object completes execution after it was called asynchronously.
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 Session class

This is an example of how you might create a Session object and use the URI to a web application to log into the application, load the Data Service Catalog for a Data Object Service provided by that application, and create a JSDO for a Customer resource defined by that Service in the Catalog:
// create Session
pdsession = new progress.data.Session();

// log in, i.e., authenticate to the web application
pdsession.login('https://BestSports.com:443/SportsApp', username, password);

// load Catalog for a service that's part of the web application
pdsession.addCatalog('https://BestSports.com:443/SportsApp/static/OrderEntrySvc.json');

// create JSDO
customers = new progress.data.JSDO( { name: 'Customer' } );

/* etc. - additional code to fill and use the JSDO */
The JSDO automatically finds and uses the Session object on which a Catalog that defines the Customer resource is loaded.

Notes

*Use an instance of this class to call the login( ) method to start a JSDO login session, call the addCatalog( ) method to load one or more Data Service Catalogs for the session, and possibly call the logout( ) method to terminate the session. To use the same Session instance to start a new login session, you must call the logout( ) method first.
Caution: To help ensure that HTTP Forms access to web applications works in certain web browsers, such as Firefox, when the web application is configured for Cross-Origin Resource Sharing (CORS), always call the login( ), addCatalog( ), and logout( ) methods asynchronously.
Caution: Under certain conditions when a server error occurs, either or both the 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 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 method is executed asynchronously.
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 an any registered afterLogin or afterAddCatalog event 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 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).
*The JSDO session uses Basic authentication.
*The login( ) or addCatalog( ) method is invoked asynchronously.
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.
*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 Data Object Service requests to the web server, you can modify the XMLHttpRequest object that is sent by the Session object. To do so, assign a callback function as the value of Session.onOpenRequest.

See also

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