Note: Updated for Progress Data Objects Version 4.4.1 and 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.
This method throws an error if the method arguments are invalid or if the underlying communication layer throws an error.
On a successful login, the JSDOSession object sets its connected property to true. If the login fails, the object leaves its connected property set to false.
This method is always executed asynchronously and returns results in callbacks that you register using methods of a Promise object returned as the method value.
Note: In order to invoke this method successfully, jQuery Promises must be supported in your development environment. Otherwise, the method throws an exception.
Note: Before invoking this method, ensure that you set the authenticationModel configuration property in the constructor of the JSDOSession object correctly (see the notes on authentication models).
Note: If the browser or mobile device has already authenticated a JSDO login session, this method completes successfully.
Note: This method does not support proxy servers (servers that function as a security service).
Note: As a recommended alternative to using this method on an existing JSDOSession object, you can create a new, initialized JSDOSession using the progress.data.getSession( ) stand-alone function. In one call, this function instantiates the object, invokes its login( ) method with specified credentials, then invokes its addCatalog( ) method to load a specified Data Service Catalog. For more information, see the getSession( ) stand-alone function description.
A string expression containing a user ID for the method to send to the web server for authentication.
Note: The userName property of the JSDOSession object returns the most recent value passed to this method for the current JSDOSession object.
password
A string expression containing a password for the method to send to the web server to authenticate the specified user.
parameter-object
An object that contains the following optional property:
iOSBasicAuthTimeout — A number that specifies the time, in milliseconds, that the login( ) method waits for a response before returning an error. This error might mean that the user entered invalid credentials. If you set this value to zero (0), no timeout is set, and login( ) can wait indefinitely before returning an error. If you do not set the iOSBasicAuthTimeout property, login( ) uses 4000 (4 seconds) as the default value.
Any non-zero timeout value (default or otherwise) for this parameter-object property operates only under certain conditions. Otherwise, any setting of this property has no effect. For more information, see the notes of the progress.data.JSDOSession class description.
Note: The login( ) method on the progress.data.Session class also takes a serviceURI property to specify the URI of the web application on which to start a JSDO login session and takes a loginTarget property to specify a protected web resource, other than the default, as a login target. The login( ) method on progress.data.JSDOSession relies on the class constructor to specify the web application URI and always uses the default web resource, /static/home.html, as the login target.
Promise method signatures
jQuery Promise objects define methods that register a callback function with a specific signature. The callback signatures depend on the method that returns the Promise. Following are the signatures of callbacks registered by methods in any Promise object that login( ) returns:
Syntax:
promise.done( function ( session , result , info ) )
promise.fail( function ( session , result , info ) )
promise.always( function ( session , result , info ) )
promise
A reference to the Promise object that is returned as the value of the login( ) method. For more information on Promises, see the notes on Promises in the description of the progress.data.JSDOSession class.
session
A reference to the JSDOSession object on which login( ) was called.
result
A constant indicating the overall result of the call that can have one of the following values:
progress.data.Session.AUTHENTICATION_SUCCESS — The JSDO login session started 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 — JSDO login failed because of invalid user credentials (username or password).
progress.data.Session.GENERAL_FAILURE — JSDO login failed because of a non-authentication failure.
This value can also be returned if invalid user credentials triggered a login timeout according to the value of the parameter-object.iOSBasicAuthTimeout property.
Note: It is not always necessary to test the value of result in a Promise method callback for the login( ) method, especially if the callback is registered using promise.done( ), where the callback always executes with the same value (progress.data.Session.AUTHENTICATION_SUCCESS).
info
A JavaScript object that can have the following properties:
errorObject — Any error object thrown as a result of sending a login request to the web server.
If this object is thrown because of a login timeout triggered according to the value of the parameter-object.iOSBasicAuthTimeout property, the message property of the error object is set to "login timeout expired".
xhr — A reference to the XMLHttpRequest object sent to the web server to start a JSDO login session.
You can also return the result of the most recent login attempt on the current JSDOSession object by reading its loginResult property. For a more specific status code returned in the HTTP response, you can also check the value of the loginHttpStatus property.
Note: You can log out from a web application and then log in again using the same JSDOSession object. The login will use the same serviceURI and authenticationModel settings originally passed to the constructor, but you must pass any required credentials each time login( ) is called.
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 JSDOSession object constructor. For more information on the authentication models that a JSDOSession object supports, see the description of the constructor for the progress.data.JSDOSession class.
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.
Note: Unless the application design guarantees that the user will be prompted by the web browser or native device container to provide credentials before a login( ) call occurs, Progress recommends (in some cases requires) that the mobile or web app pass the credentials as parameters to the login( ) method. In addition, you must correctly pass the value of the authenticationModel configuration property to the JSDOSession object's constructor. Coding the mobile or web app in this way ensures that the proper credentials are submitted to the server and promotes a favorable user experience.
Example
The following code fragment calls the login( ) method on the JSDOsession object, empSession. This example uses the callbacks registered by the Promise done( ) and fail( ) methods to check the result of the call along with any error object thrown as a result of the request, then assembles an appropriate message to display in an alert box. It also uses a try-catch block in case the login( ) method throws an error object instead of sending the request to the server:
var msg;
var xhr;
try {
empSession.login( userName, passWord ).done(
function( session, result, info ) {
msg = "Logged in successfully”;
}).fail(
function( session, result, info ) {
if ( result === progress.data.Session.AUTHENTICATION_FAILURE ) {
msg = "Employee Login failed. Authentication error";
}
else if ( result === progress.data.Session.GENERAL_FAILURE ) {
msg = "Employee Login failed. Unspecified error";
if ( info.errorObject ) {
// Process error object thrown during login . . .
}
if ( info.xhr ) {
// Process XHR sent during login . . .
}
}
xhr = info.xhr;
});
}
catch(errObj) {
msg = "Employee Login failed. Error attempting to call login";
msg = msg + '\n' + errObj.message;
}
iOSBasicAuthTimeout — A number that specifies the time, in milliseconds, that the login( ) method waits for a response before returning an error. This error might mean that the user entered invalid credentials. If you set this value to zero (0), no timeout is set, and login( ) can wait indefinitely before returning an error. If you do not set the iOSBasicAuthTimeout property, login( ) uses 4000 (4 seconds) as the default value.