When a user runs a web app in a browser, it is common, especially when the app seems unresponsive, for the user to click a browser control that causes the page to be reloaded (refreshed) and redisplayed in its document context, hopefully in a state that the user expects. In the process of reloading the page, the refresh clears memory so that all of the JavaScript objects and variables are created again as if for the first time.

If the app is accessing a JSDO when the user initiates this page refresh, by default, all information that a JSDOSession or Session object uses to manages its JSDO login session is also lost. As such, the refresh resets the state of the login session as if it was never logged in. This causes the app to prompt the user for their credentials, if required, and invoke the getSession( ) method in order to re-establish the JSDO login session's connection to its web application. However, it should not be necessary for the session to log in again, because the state of the web application on the server is not affected by the browser page refresh.

To reduce the need for an additional login when a page refresh occurs, both the progress.data.JSDOSession class and the progress.data.getSession( ) stand-alone function provide the option for an instance to store some state from its login session once the session is first successfully established. The instance then attempts to re-establish the same login session state without requiring an additional session login when the web app page is refreshed.

To support page refresh in a web app, the JSDOSession class provides a constructor option (name property) to enable the page refresh feature itself and a method (isAuthorized( )) to test whether its JSDOSession instance already has an authorized login session established from a restored prior session state, or if a login session has yet to be established for a first-time execution. You enable page fresh support by passing the name property to the constructor with a value (an operative value) that the JSDOSession instance can use to store and restore its login session state. The JSDOSession class also provides a read-only name property that you can access to return the operative value, if any, that was set to enable its page refresh support. You can use getSession( ) as an alternative. It creates a new session if it is a brand new state or re-creates the old session on a page refresh.

Note: Page refresh supports only Anonymous and Form-based authentication. If you attempt to enable page refresh support using Basic authentication, any setting of the name property is ignored.

Use of this page refresh support typically follows this web app algorithm for as many JSDOSession instances as required:

  1. At the start, create the JSDOSession object, enabling page refresh support by passing the name property with an operative value to the constructor.
  2. Call isAuthorized( ) on the JSDOSession to test if:
    • A login session for the JSDOSession instance already exists, having been restored from a page refresh, and is authorized to access its web application. App execution continues with the existing login session.
    • No authorized login session for the JSDOSession instance exists, either because it has yet to be established (first-time execution), it was previously logged out, it timed out, it otherwise lost its authorized connection to the web application. A new login session for the instance needs to be established before app execution continues.
    • Some other session failure, such as an offline status, has prevented the JSDOSession instance from connecting to its web application and must be handled by the app.

The progress.data.getSession( ) stand-alone function, which creates and returns a JSDOSession instance already initialized with a valid JSDO login session and loaded with a Data Service Catalog, provides a similar option (name property) to enable the page refresh feature in the JSDOSession that it creates. However, with this stand-alone function, you have no need for the isAuthorized( ) method, because the getSession( ) function fully supports the page refresh feature itself without the need for any additional coding, such as invoking isAuthorized( ) on an existing JSDOSession.

For more information on enabling page refresh support and its effects, see the description of the progress.data.JSDOSession class and the getSession( ) stand-alone function. For more information on using the isAuthorized( ) method, including example code, see the description of the isAuthorized( ) method.