A stand-alone function that creates and returns a progress.data.JSDOSession instance with a specified JSDO login session already established and a specified Data Service Catalog already loaded.

This function combines the features of:

  • Preparing the JSDOSession class constructor and instantiating the instance.
  • Calling the login( ) method on the instance to establish a JSDO login session.
  • Calling the addCatalog( ) method on the instance to load a single Data Service Catalog.

The resulting login session is then ready to support creation of JSDO instances for the one or more resources provided by the specified Data Object Service. In addition, this function provides automatic support for page refresh in web apps, if specified, when you call it.

This method is always executed asynchronously and returns results in callbacks that you register using methods of a Promise object returned as the function value.

Note: In order to invoke this function successfully, jQuery Promises must be supported in your development environment. Otherwise, the function throws an exception.
Note: This function does not support proxy servers (servers that function as a security service).

Return type: jQuery Promise

Applies to: The progress.data namespace

Syntax

progress.data.getSession ( parameter-object )
parameter-object
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://localhost: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).

  • catalogURI — (Required) A string expression that specifies the URI of a Data Service Catalog file. This URI can specify a location in a web application running on a web server. It is typically the location of the web application that hosts the Data Object Service where the returned JSDOSession object has a JSDO login session.

    If the Catalog is deployed to the same web server (or device) that the app UI is loaded from, catalogURI can be specified using a relative path, for example, /SportsMobileApp/static/OrderEntrySvc.json, where /SportsMobileApp is the relative URI of the web application that hosts the Catalog. Otherwise, it must be specified using an absolute path that includes the Tomcat server domain or host and port, for example, http://www.progress.com:8980/SportsMobileApp/static/OrderEntrySvc.json, or perhaps for testing, http://localhost:8980/SportsMobileApp/static/OrderEntrySvc.json.

    Note: The default Catalog URI for a Catalog created for an OpenEdge Data Object Service, relative to the Apache Tomcat server domain or host and port where the session is logged in, is the following: /WebApplicationName/static/ServiceName.json, where WebApplicationName is the name of the web application and ServiceName is the name of the Data Object Service for which the Data Service Catalog is created.
  • authenticationModel — (Required only for Basic or Form authentication) A string constant that specifies one of the three authentication models that the returned 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, you need to pass these credentials using the username and password properties. 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 using the username and password properties. 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.

  • username — (Required only for Basic or Form authentication) A string expression containing a user ID for the function to send to the web server for authentication.
    Note: The userName property of the returned JSDOSession object contains this value.
  • password — (Required only for Basic or Form authentication) A string expression containing a password for the function to send to the web server to authenticate the specified user.
  • name — (Optional) A string with an operative value that you define to enable page refresh support for the returned JSDOSession object. The operative value can be any value other than the empty string (""), null, or undefined.

    If this page refresh support is enabled and the function 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 the progress.data.JSDOSession classdescription.

    Note: If you pass the getSession( ) function 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 getSession( ) (or the JSDOSession constructor).
    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: When calling this getSession( ) function, you have no need to call the isAuthorized( ) method on the returned JSDOSession object in order to test that an authorized login session is established it to manage page refresh. This function automatically manages page refresh for any successful call by a web app.
Note: Similar to the login( ) method on the progress.data.JSDOSession class, the getSession( ) function always relies on the default web resource, /static/home.html, as the login target. In addition, if you are both using Basic authentication and the web app is running on an iOS device, this function waits up to four (4) seconds to time out before failing to authenticate a login session or load a Data Service Catalog.

Promise method signatures

jQuery Promise objects define methods that register a callback function with a specific signature. The callback signatures depend on the function that returns the Promise. Following are the signatures of callbacks registered by methods in any Promise object that getSession( ) returns:

Syntax:

promise.done( function ( JSDOsession , result ) )
promise.fail( function ( result , info ) )
promise.always( function ( JSDOsession , result | result , info ) )
Note: The always( ) method is always passed what the done( ) or the fail( ) methods are passed.
promise
A reference to the Promise object that is returned as the value of the getSession( ) function. For more information on Promises, see the notes on Promises in the description of the progress.data.JSDOSession class.
JSDOsession
A reference to the JSDOSession object that was successfully created and returned by getSession( ) with a valid JSDO login session and a single loaded Data Service Catalog.
result
An integer constant indicating the overall result of the call that can have one of the following values:
  • progress.data.Session.SUCCESS — The JSDOSession was created, logged in, and a Catalog added successfully. You can use JSDOs to access any Data Object Services supported by the web application to which the JSDOSession object has logged in.
  • progress.data.Session.AUTHENTICATION_FAILURE — Login failed because of an authentication error. This might be because the JSDO session login had invalid credentials or the authentication error happened when adding the Catalog.
  • progress.data.Session.GENERAL_FAILURE — JSDOSession creation failed because of something other than an authentication error.
    Note: This value can also be returned if invalid user credentials triggered a login timeout using Basic authentication on an iOS device.
Note: It is not always necessary to test the value of result in a Promise method callback for getSession( ), especially if the callback is registered using promise.done( ), where the callback always executes with the same value (progress.data.Session.SUCCESS).
info
A JavaScript object that can have the following properties:
  • errorObject — Any error object thrown as a result of sending a login or add Catalog request to the web server.
    Note: If this object is thrown because of a timeout triggered according to the four (4) second maximum wait time to login or load a Catalog, the message property of the error object is set to "login timeout expired".
  • xhr — A reference to the XMLHttpRequest object that was used to make the server request to either log in or add a catalog.

General web server interaction

The general web server interaction with and response to this method depends on the authentication model that the web server uses and how resources are accessed and protected. You configure the authentication model for each web application deployed to the Apache Tomcat and specify both the web application URI and its corresponding authentication model to the getSession( ) function.

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 server documentation for your Data Object Service.

CAUTION: You must be sure that security is configured to complete authentication before the application requests resources in the Data Service Catalog. Although it is possible to configure application security so that only the Data Object resources in the Catalog require authentication, Progress does not recommend this approach. Instead, Progress recommends that you require authentication for application resources in addition to those defined in the Catalog, and require that the authentication occur prior to accessing any resources in the Catalog. Once the user is authenticated, the web server provides access to all other resources, including Catalog resources, according to the user's authorization settings.

Example

The following code fragment calls getSession( ) in a try block, handling successful results with the Promise done( ) method, which invokes one inline function, and handling unsuccessful results with the Promise fail( ) method, which invokes another inline function. For a successful call, it saves the returned JSDOSession and logs a message to the consule, then creates and initializes a JSDO for further processing. For an unsuccessful call, it only logs a message to the console. If the call to getSession( ) itself throws an exception, this is handled in a catch block by logging the associated message to the console:

var promise,
    myjsdosession;

try {
    promise = progress.data.getSession({
        name: "mySession",
        authenticationModel: progress.data.Session.AUTH_TYPE_FORM,
        serviceURI: "https://someHost:8810/myWebApplication",
        catalogURI: "https://someHost:8810/myWebApplication/static/Customer.json",
        username: "restuser",
        password: "password"
    });
    promise.done( function( jsdosession, result ) {
        var jsdo;

        myjsdosession = jsdosession;
        console.log("Success on getSession().");

        // create a JSDO
        jsdo = new progress.data.JSDO({
                    name: 'MyCustomerBE'
        });
    });
    promise.fail( function( result, info ) {
        console.log("Failure from getSession()");
    });
}
catch(ex) {
    console.log("Exception: " + ex.message);
};

See also:

addCatalog( ) method (JSDOSession class), login( ) method (JSDOSession class), progress.data.JSDOSession class, serviceURI property, userName property