JSDO properties, methods, and events reference : ping( ) method (Session class)
  

ping( ) method (Session class)

Note: Deprecated in Progress Data Objects Version 4.4 and later. Please use the ping( ) method (JSDOSession class) instead.
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.
This method also causes an offline or online event to fire if the ping detects that there has been a change in the Session object's online state.
This method throws an exception if the Session object has not logged into its web application or has since logged out.
You can call this method either synchronously or asynchronously.
Return type: boolean
Applies to: progress.data.Session class

Syntax

ping ( [ parameter-object ] ) )
parameter-object
An object with any or all of the following properties:
*async — A boolean. If set to true, ping( ) executes asynchronously. If set to false, ping( ) executes synchronously. If you do not pass this property setting, ping( ) executes asynchronously.
*onCompleteFn — A callback function that is called only if ping( ) executes asynchronously. This function is called after the ping( ) method receives a response from the server (or times out), regardless of the online status returned:
Syntax:
function [ func-name ] ( completion-object )
Where func-name is the name of a callback function that you define external to parameter-object, and completion-object is an object parameter that ping( ) passes to the function with these properties:
*pingResult — A boolean that indicates the session online status that ping( ) returns. If set to true, ping( ) determined that the current Session object is connected and logged in to a web application (and its application server, for an OpenEdge Data Object Service), or if set to false, the session is disconnected from any web application (or its application server, for an OpenEdge Data Object Service).
*xhr — The XMLHttpRequest object that ping( ) used to make the request.
*offlineReason — A string constant that ping( ) sets only if it determines that the session is disconnected from any web application. The constant value indicates the reason for its offline status. 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, as shown below.
*xhr — If you call ping( ) synchronously, this is a property that you can initially set to any value (including null or undefined), but which ping( ) resets to a reference to the XMLHttpRequest object that ping( ) used to make the request. If you do not include an initial setting for this property in parameter-object, you cannot access this XMLHttpRequest object for synchronous ping( ) call.
*offlineReason — If you call ping( ) synchronously, this is a property that you can initially set to any value (including null or undefined), but which ping( ) resets to a string constant value if it determines that the session is disconnected from any web application. This constant value indicates the reason for its offline status. 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, as shown below.
Caution: If you do not include an initial setting for this property in parameter-object, any offlineReason value returned by ping( ) is unavailable for a synchronous call.
The possible values for the offlineReason properties described above 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

The ping( ) method always returns the overall session online status as a boolean value: true if the session's web application is fully available (online and with accessible Data Object Services) and false if the web application is not available (offline or with inaccessible Data Object Services). If you call ping( ) synchronously, it returns this online status as its method return value. If you call ping( ) asynchronously, the method always returns with a value of false, but passes its online status as the value of the pingResult property it passes to its onCompleteFn callback.
A Session 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.
Note: You can have ping( ) executed automatically by setting the pingInterval property on the Session object, which specifies the time interval between invocations of ping( ).
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 OpenEdge AppServer or the Progress Application Server for OpenEdge.

Example

The following code fragment shows how you can use ping( ) to check the online status of a given Session object after logging in:
var mySession = new progress.data.Session;

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

. . .

/* Code to set webapplURI, username, and password variables and log in . . . */
mySession.authenticationModel = progress.data.Session.AUTH_TYPE_FORM;
var username = . . . ;
var password = . . . ;
var webApplicationURI = . . . ;
mySession.login( webApplicationURI, username, password );

. . .

var pingParm = { async : false, offlineReason : null };

if ( !ping(pingParm) ) {
document.write("Session ping result: " + pingParm.offlineReason);
}
else {
document.write("Session ping result: Online");
}

. . .

function onSessionOffline( pSession , pOfflineReason , pRequest ) {
  document.write("The session status has changed to: " + pOfflineReason);
};

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

See also:

connected property, offline event, online event, pingInterval property