Determines the online state of the current JSDOSession 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.

This method also causes an offline or online event to fire if the ping detects that there has been a change in the JSDOSession object's online state.

This method throws an exception if the JSDOSession object has not logged into its web application or has since logged out.

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.

Return type: jQuery Promise

Applies to: progress.data.JSDOSession class

Syntax

ping ( )

Promise method signatures

jQuery Promise objects define methods that you can call to 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 ping( ) 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 ping( ) 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 ping( ) was called.
result
A boolean that indicates the online state of the JSDOSession object on which ping( ) is called. If set to true, ping( ) has determined that the current JSDOSession object is connected and logged into a web application (and its associated application server, for an OpenEdge Data Object Service), or if set to false, the object is disconnected from any web application (or its associated application server, for an OpenEdge Data Object Service).
info
A JavaScript object that can have the following properties:
  • xhr — A reference to the XMLHttpRequest object sent to the web server to make the ping request to the web application.
  • offlineReason — A string constant that ping( ) sets only if it determines that the JSDOsession object is disconnected from any web application or its associated application server. The constant value indicates the reason for its offline state. Possible values are the same as those that can be passed to the offline event callback function as the value of its off-line-reason parameter, and include:
    • progress.data.Session.APPSERVER_OFFLINE — (OpenEdge Data Object Services only) The other components necessary to run the service are available, but the associated OpenEdge application server is offline.
    • progress.data.Session.DEVICE_OFFLINE — The device itself is offline. For example, it might be in airplane mode, or it might be unable to pick up a Wi-Fi or cell signal.
    • progress.data.Session.SERVER_OFFLINE — The web server is not available. For a Rollbase Data Object Service, this is the web server for the public or private cloud. For an OpenEdge Data Object Service, this is the Tomcat Java servlet container.
    • progress.data.Session.WEB_APPLICATION_OFFLINE — The server is running, but the Java web application that implements the Data Object Service is not deployed.

Detailed ping behavior

A JSDOSession object is considered to be in an online state if all of the following are true:

  • The object can communicate with its web application. That is, the web server is running, the web application is started, and it has accessible Data Object Services.
  • For OpenEdge Data Object Services only, the associated OpenEdge application server that the web application accesses is running and accessible.
  • The ping() service defined in the Progress Application Server for OpenEdge catalog is available.

When you execute ping( ) on a JSDOSession instance, the method indicates the instance's current online status through its returned Promise object using the most commonly registered callbacks as follows:

  • If the instance is online, the returned Promise object invokes any callback you register using the object's done( ) method. The done( ) callback's result parameter is always set to true.
  • If the instance is offline, the returned Promise object invokes any callback you register using the object's fail( ) method. The fail( ) callback's result parameter is always set to false.
  • The returned Promise object invokes any callback you register using the object's always( ) method with the value of the callback's result parameter indicating the instance's online status as described for the Promise method signatures above.
Note: You can have ping( ) executed automatically by setting the pingInterval property on the JSDOSession object, which specifies the time interval between invocations of ping( ). However, automatic invocations do not return Promise objects, but only fire offline and online events appropriately when a change in the JSDOSession instance's online status is detected.
Note: For OpenEdge Data Object Services, an OpenEdge application server supports ping( ) using an OpenEdge-defined ABL class, OpenEdge.Rest.Admin.AppServerStatus. This class responds to a REST ping service call to its ServerStatus( ) method, which indicates that the application server is available when the method returns successfully. You can also define a version of this method in your own user-defined ABL class that returns a custom string value when ping( ) returns successfully, and you can retrieve this value from the xhr object reference returned by ping( ). For more information, see the sections on constructing and debugging REST requests in the administration documentation for the Progress Application Server for OpenEdge.

Example

The following code fragment shows how you can use ping( ) to check the online state of a given JSDOSession object after logging in:

var mySession = new progress.data.JSDOSession ( { . . . } );

/* These session events can fire on device online 
   status changes even prior to logging in */
mySession.subscribe('offline', onSessionOffline );
mySession.subscribe('online', onSessionOnline );

. . .

mySession.login().done( // Anonymous login
    function( session, result, info ) {

        . . .

        ping().done( 
            function( session, result, info ) {
                console.log("Session ping result: Online");
                }
            }).fail(
            function( session, result, info ) {
                console.log("Session ping result: Offline -- " 
                               + info.offlineReason);
                // Process info.xhr, if necessary, for more information
            });

        . . .

    }).fail( /* Process failed login . . . */ );

. . .

function onSessionOffline( pSession , pOfflineReason , pRequest ) {
  console.log("The session status has changed to: Offline -- " 
              + pOfflineReason);
};

function onSessionOnline( pSession , pRequest ) {
  console.log("The session status has changed to: Online");
};

See also:

connected property, offline event, online event, pingInterval property