Determines the online state of the current JSDOSession object from its ability to access the Mobile Web application that it manages, and for an OpenEdge Web application, from detecting if its associated application server is running.
The method also causes an offline or online event to fire if the ping detects that there has been a change in the object's online state.
This method throws an exception if the JSDOSession object has not logged into its Mobile Web application or has since logged out.
Following are the signatures of methods that are observed in the jQuery Promise that ping( ) returns:
Syntax:
done: function ( session , result , info ) fail: function ( session , result , info ) always: function ( session , result , info )
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 Mobile Web application (and its associated application server, for an OpenEdge Mobile service), or if set to false, the object is disconnected from any Mobile Web application (or its associated application server, for an OpenEdge Mobile 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 Mobile 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 handler function as the value of its off-line-reason parameter, and include:
progress.data.Session.APPSERVER_OFFLINE — (OpenEdge Mobile 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.
This condition will fire the offline event on a JSDOSession or Session object even if the object has not yet invoked its login( ) method.
progress.data.Session.SERVER_OFFLINE — The Web server is not available. For a Rollbase Mobile service, this is the Web server for the public or private cloud. For an OpenEdge Mobile 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 Mobile service is not deployed.
Detailed ping behavior
The ping( ) method fires an online or offline event on its JSDOSession object if the method detects that the online state of its JSDOSession object has changed. A JSDOSession object is considered to be in an online state if all of the following are true:
The object can communicate with its Mobile Web application. That is, the Web server is running, the Web application is started, and it has accessible Mobile services.
For OpenEdge Mobile 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 JSDOSession object, which specifies the time interval between invocations of ping( ).
Note: For OpenEdge Mobile 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 and the Pacific 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. It also shows that the session online and offline events can fire both using ping( ) if the JSDOSession object's online state has changed after logging in, and without using ping( ) when the device online status has changed even prior to 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"); };
xhr — A reference to the XMLHttpRequest object sent to the Web server to make the ping request to the Web application.