The progress.data.JSDOSession instance provides events, methods, and properties that you can use to identify and respond to changes in a client app's session online status. This online status reflects two basic network conditions, where:

  • The connection between the device (or JSDO login session) in which the client app is running and an available Internet access point (such as a Wi-Fi router) has either been broken or re-established, also referred to as the device online status (or the JSDO login session online status).
  • The availability of a web application to which the client app was previously connected has either been interrupted or re-established on a device (or JSDO login session) that is otherwise connected to the Internet, also referred to as web application online status or Data Object Service online status.

The following table briefly describes session instance events, methods, and properties that you can use to track a client app's online status.

Table 1. Events, methods, and properties for tracking app online status
Member Brief description (See also the reference entry)
connected property Returns a boolean that indicates the most recent online status of the current JSDOSession object when it last determined if the web application it manages was available.
offline event Fires when the current JSDOSession object detects that the device on which it is running has gone offline, or that the web application to which it has been connected is no longer available.
online event Fires when the current JSDOSession objectdetects that the device on which it is running has gone online after it was previously offline, or that the web application to which it is connected is now available after it was previously unavailable.
ping( ) method (JSDOSession class) 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.
pingInterval property A number that specifies the duration, in milliseconds, between one automatic execution of the current JSDOSession object's ping( ) method and the next.
subscribe( ) method (JSDOSession class) Subscribes a given event callback function to an event of the current JSDOSession object.
unsubscribe( ) method (JSDOSession class) Unsubscribes a given event callback function from an event of the current JSDOSession object.
unsubscribeAll( ) method Unsubscribes all event callback functions from a single named event of the current JSDO or JSDOSession object, or unsubscribes all event callback functions from all events of the current JSDO or JSDOSession object.

You can identify a change in a client app's session online status by subscribing handlers to the online and offline events of a JSDOSession instance using the object's subscribe( ) method any time after you create the object. When the JSDO login session detects that its previously online device has gone offline or its previously connected web application is no longer available, the session fires its offline event. When the session detects that its previously offline device has come back online or its previously unavailable web application connection has, again, become available, the session fires its online event.

When a subscribed event fires, the handler signature includes:

  • A reference to the session instance on which the event was fired
  • A reference to a request object (if any) that was sent for a Data Object Service request that triggered the event
  • For the offline event, a reason that an offline status was detected, such as its device going offline.
Note: If the offline or online event fires because of a change in device online status, no request object reference is returned and the handler's request object parameter is set to null.

A JSDO login session supports several ways to identify either the device online status or the web application online status for Data Object Services managed by a session instance:

  • Subscribing handlers to the online and offline events of the session instance using the instance's subscribe( ) method, as described above. Again, these events fire whenever there is a change in session online status for any reason.
  • Invoking the ping( ) method on the session instance. This method returns the current online status of the session instance. It sends a request to the web application that is managed by the session instance and attempts to determine if the Data Object Services provided by the web application are available.

    On a JSDOSession instance, this method immediately returns a Promise object on which you can register various callback functions using Promise object methods. These callbacks execute depending on the conditions of method completion. For example, if the callback executes that you register using the done( ) method, the JSDOSession instance is online with access to its Data Object Services. If the callback executes that you register using the fail( ) method, the JSDOSession instance is offline either because the device is offline or there is a problem with the web application or Data Object Service connections.

    In addition, if the current online status identified by ping( ) has changed from the most recent status detection (either from a call to ping( ) or a JSDO request for a Data Object Service), the session instance also fires its corresponding offline or online event, to which any subscribed event handler can respond. Note that ping( ) returns online status results only between a successful execution of the getSession( ) method and successful execution of the invalidate( ) method on the same session instance.

  • • Setting the pingInterval property on the session instance to a value in milliseconds greater than zero (0). This setting causes the instance to automatically and periodically invoke its ping( ) method once a session has been successfully instantiated using getSession( ). The minimum time between the completion of one execution of ping( ) and the start of the next execution of ping( ) is the number of milliseconds you assign. Each automatic execution of ping( ) only fires an offline or online event on its session instance if the method detects a change in session online status. Automatic ping( ) execution returns no other results
  • Testing the value of the connected property on the session instance. This boolean value indicates the most recent online status of the current session instance when it last determined if the web application it manages was available. If the property value is true, the instance most recently determined that the session is connected and logged in to its web application. If its value is false, the session was last found to be disconnected.

    This property is first set to true once a session has been successfully instantiated using getSession( ). However, to obtain the most current online status, if different, you must either invoke the instance's ping( ) method or make a JSDO request to one of the instance's Data Object Services, which updates the value of its connected property if its online status has changed. This property is also set to false after you invoke the invalidate( ) method on its session instance.

Note that once a JSDO session has been successfully instantiated using getSession( ), the session is always initially online. So, the first change in device or Data Object Service online status is indicated by a firing of the offline event by the session instance in response to detecting that the device or its most recently connected web application has gone offline.

Note also that all attempts to detect the current availability of Data Object Services provided by a connected web application, such as executing ping( ) or making JSDO requests, return results from the hosting web server only after successfully starting and maintaining a user login session on the web application from a device that is online (that is, by invoking getSession( ) on a session instance for the web application and not yet invoking invalidate( )). However, you can always receive results from changes in the device's online status by subscribing to offline and online events from the first point that you create a session instance (and regardless if you have yet started a JSDO login session) until you either destroy the session instance or unsubscribe to these events using the unsubscribe( ) or unsubscribeAll( ) methods.