Web Client 8.0.3

StatusWidget

StatusWidget

This class is a simple implementation of the ClientListener interface, which will display a small widget with details about the status of the connection. The widget contains the "S" logo and three tiny leds. The "S" logo changes color and luminosity to reflect the current connection status (connecting, disconnected, connected, and stalled).

  • The left led indicates the transport in use: green if WS/WSS; yellow if HTTP/HTTPS.
  • The center led indicates the mode in use: green if streaming; yellow if polling.
  • The right led indicates where the physical connection in held: green if this LightstreamerClient is the master instance, holding the connection; yellow if this LightstreamerClient instance is a slave attached to the master Lightstreamer Client instance.
By rolling over or clicking over the widget, a panel appears with full details.
Note that the widget is generated using some features not available on old browsers but as long as the "data" URL scheme is supported the minimal functions of the widget will work (for instance, IE<=7 does not have support for the "data" URL scheme).
Also note that on IE if "Quirks Mode" is activated the widget will not be displayed correctly. Specify a doctype on the document where the widget is going to be shown to prevent IE from entering the "Quirks Mode".

Constructor

new StatusWidget(attachToBorder, distance, fromTop, initialDisplayopt)

Creates an object to be used to listen to events from a LightstreamerClient instance. The new object will create a small visual widget to display the status of the connection. The created widget will have a fixed position so that it will not move when the page is scrolled.

Parameters:
Name Type Attributes Description
attachToBorder String

"left" "right" or "no" to specify if the generated widget should be attached to the left border, right border or should not be attached to any border. In the latter case, it should be immediately positioned manually, by acting on the DOM element obtained through StatusWidget#getDomNode.

distance String

The distance of the widget from the top/bottom (depending on the fromTop parameter). The specified distance must also contain the units to be used: all and only the units supported by CSS are accepted.

fromTop boolean

true or false to specify if the distance is related to the top or to the bottom of the page.

initialDisplay String <optional>

"open" "closed" or "dyna" to specify if the generated widget should be initialized open, closed or, in the "dyna" case, open and then immediately closed. By default "dyna" is used. If attachToBorder is set to "no" then this setting has no effects.

Throws:

if an invalid value was passed as attachToBorder parameter.

Type
IllegalArgumentException

Extends

Methods

getDomNode() → {Object}

Inquiry method that gets the DOM element that makes the widget container. It may be necessary to extract it to specify some extra styles or to position it in case "no" was specified as the attachToBorder constructor parameter.

Returns:

The widget DOM element.

Type
Object

onListenEnd(lsClient)

Event handler that receives a notification when the ClientListener instance is removed from a LightstreamerClient through LightstreamerClient#removeListener. This is the last event to be fired on the listener.

Parameters:
Name Type Description
lsClient LightstreamerClient

the LightstreamerClient this instance was removed from.

Overrides:

onListenStart(lsClient)

Event handler that receives a notification when the ClientListener instance is added to a LightstreamerClient through LightstreamerClient#addListener. This is the first event to be fired on the listener.

Parameters:
Name Type Description
lsClient LightstreamerClient

the LightstreamerClient this instance was added to.

Overrides:

onPropertyChange(the)

Event handler that receives a notification each time the value of a property of LightstreamerClient#connectionDetails or LightstreamerClient#connectionOptions is changed.
Properties of these objects can be modified by direct calls to them, but also by calls performed on other LightstreamerClient instances sharing the same connection and by server sent events.

Parameters:
Name Type Description
the String

name of the changed property.
Possible values are:

  • adapterSet
  • serverAddress
  • user
  • password
  • serverInstanceAddress
  • serverSocketName
  • sessionId
  • contentLength
  • idleTimeout
  • keepaliveInterval
  • maxBandwidth
  • pollingInterval
  • reconnectTimeout
  • stalledTimeout
  • retryDelay
  • firstRetryMaxDelay
  • slowingEnabled
  • forcedTransport
  • serverInstanceAddressIgnored
  • cookieHandlingRequired
  • reverseHeartbeatInterval
  • earlyWSOpenEnabled
  • httpExtraHeaders
  • httpExtraHeadersOnSessionCreationOnly
Inherited From:
See:

onServerError(errorCode, errorMessage)

Event handler that is called when the Server notifies a refusal on the client attempt to open a new connection or the interruption of a streaming connection. In both cases, the ClientListener#onStatusChange event handler has already been invoked with a "DISCONNECTED" status and no recovery attempt has been performed. By setting a custom handler, however, it is possible to override this and perform custom recovery actions.

Parameters:
Name Type Description
errorCode Number

The error code. It can be one of the following:

  • 1 - user/password check failed
  • 2 - requested Adapter Set not available
  • 7 - licensed maximum number of sessions reached (this can only happen with some licenses)
  • 8 - configured maximum number of sessions reached
  • 9 - configured maximum server load reached
  • 10 - new sessions temporarily blocked
  • 11 - streaming is not available because of Server license restrictions (this can only happen with special licenses)
  • 21 - a bind request has unexpectedly reached a wrong Server instance, which suggests that a routing issue may be in place
  • 30-41 - the current connection or the whole session has been closed by external agents; the possible cause may be:
    • The session was closed on the Server side (via software or by the administrator) (32) or through a client "destroy" request (31);
    • The Metadata Adapter imposes limits on the overall open sessions for the current user and has requested the closure of the current session upon opening of a new session for the same user on a different browser window (35);
    • An unexpected error occurred on the Server while the session was in activity (33, 34);
    • An unknown or unexpected cause; any code different from the ones identified in the above cases could be issued.
    A detailed description for the specific cause is currently not supplied (i.e. errorMessage is null in this case).
  • 60 - this version of the client is not allowed by the current license terms.
  • 61 - there was an error in the parsing of the server response thus the client cannot continue with the current session.
  • 66 - an unexpected exception was thrown by the Metadata Adapter while authorizing the connection.
  • 68 - the Server could not open or continue with the session because of an internal error.
  • 71 - this kind of client is not allowed by the current license terms.
  • <= 0 - the Metadata Adapter has refused the user connection; the code value is dependent on the specific Metadata Adapter implementation
errorMessage String

The description of the error as sent by the Server.

Inherited From:
See:

onServerKeepalive()

Notifies that the Server has sent a keepalive message because a streaming connection is in place and no update had been sent for the configured time (see ConnectionOptions#setKeepaliveInterval). However, note that the lack of both updates and keepalives is already managed by the library (see ConnectionOptions#setReconnectTimeout and ConnectionOptions#setStalledTimeout).

Inherited From:

onShareAbort()

Event handler that receives a notification in case a connection sharing is aborted. A connection sharing can only be aborted if one of the policies specified in the ConnectionSharing instance supplied to the LightstreamerClient#enableSharing method is "ABORT".
If this event is fired the client will never be able to connect to the server unless a new call to enableSharing is issued.

Inherited From:

onStatusChange(chngStatus)

Event handler that receives a notification each time the LightstreamerClient status has changed. The status changes may be originated either by custom actions (e.g. by calling LightstreamerClient#disconnect) or by internal actions.

The normal cases are the following:

  • After issuing connect(), if the current status is "DISCONNECTED*", the client will switch to "CONNECTING" first and to "CONNECTED:STREAM-SENSING" as soon as the pre-flight request receives its answer.
    As soon as the new session is established, it will switch to "CONNECTED:WS-STREAMING" if the browser/environment permits WebSockets; otherwise it will switch to "CONNECTED:HTTP-STREAMING" if the browser/environment permits streaming or to "CONNECTED:HTTP-POLLING" as a last resort.
    On the other hand if the status is already "CONNECTED:*" a switch to "CONNECTING" is usually not needed.
  • After issuing disconnect(), the status will switch to "DISCONNECTED".
  • In case of a server connection refusal, the status may switch from "CONNECTING" directly to "DISCONNECTED". After that, the ClientListener#onServerError event handler will be invoked.

Possible special cases are the following:
  • In case of Server unavailability during streaming, the status may switch from "CONNECTED:*-STREAMING" to "STALLED" (see ConnectionOptions#setStalledTimeout). If the unavailability ceases, the status will switch back to ""CONNECTED:*-STREAMING""; otherwise, if the unavailability persists (see ConnectionOptions#setReconnectTimeout), the status will switch to "DISCONNECTED:TRYING-RECOVERY" and eventually to "CONNECTED:*-STREAMING".
  • In case the connection or the whole session is forcibly closed by the Server, the status may switch from "CONNECTED:*-STREAMING" or "CONNECTED:*-POLLING" directly to "DISCONNECTED". After that, the ClientListener#onServerError event handler will be invoked.
  • Depending on the setting in ConnectionOptions#setSlowingEnabled, in case of slow update processing, the status may switch from "CONNECTED:WS-STREAMING" to "CONNECTED:WS-POLLING" or from "CONNECTED:HTTP-STREAMING" to "CONNECTED:HTTP-POLLING".
  • If the status is "CONNECTED:*-POLLING" and any problem during an intermediate poll occurs, the status may switch to "CONNECTING" and eventually to "CONNECTED:*-POLLING". The same may hold for the "CONNECTED:*-STREAMING" case, when a rebind is needed.
  • In case a forced transport was set through ConnectionOptions#setForcedTransport, only the related final status or statuses are possible. Note that if the transport is forced while a Session is active and this requires a reconnection, the status may do a preliminary switch to CONNECTED:STREAM-SENSING.
  • In case of connection problems, the status may switch from any value to "DISCONNECTED:WILL-RETRY" (see ConnectionOptions#setRetryDelay), then to "CONNECTING" and a new attempt will start. However, in most cases, the client will try to recover the current session; hence, the "DISCONNECTED:TRYING-RECOVERY" status will be entered and the recovery attempt will start.
  • In case of connection problems during a recovery attempt, the status may stay in "DISCONNECTED:TRYING-RECOVERY" for long time, while further attempts are made. On the other hand, if the connection is successful, the status will do a preliminary switch to CONNECTED:STREAM-SENSING. If the recovery is finally unsuccessful, the current session will be abandoned and the status will switch to "DISCONNECTED:WILL-RETRY" before the next attempts.
  • In case the local LightstreamerClient is exploiting the connection of a different LightstreamerClient (see ConnectionSharing) and such LightstreamerClient or its container window is disposed, the status will switch to "DISCONNECTED:WILL-RETRY" unless the current status is "DISCONNECTED". In the latter case it will remain "DISCONNECTED".


By setting a custom handler it is possible to perform actions related to connection and disconnection occurrences. Note that LightstreamerClient#connect and LightstreamerClient#disconnect, as any other method, can be issued directly from within a handler.

Parameters:
Name Type Description
chngStatus String

The new status. It can be one of the following values:

  • "CONNECTING" the client has started a connection attempt and is waiting for a Server answer.
  • "CONNECTED:STREAM-SENSING" the client received a first response from the server and is now evaluating if a streaming connection is fully functional.
  • "CONNECTED:WS-STREAMING" a streaming connection over WebSocket has been established.
  • "CONNECTED:HTTP-STREAMING" a streaming connection over HTTP has been established.
  • "CONNECTED:WS-POLLING" a polling connection over WebSocket has been started. Note that, unlike polling over HTTP, in this case only one connection is actually opened (see ConnectionOptions#setSlowingEnabled).
  • "CONNECTED:HTTP-POLLING" a polling connection over HTTP has been started.
  • "STALLED" a streaming session has been silent for a while, the status will eventually return to its previous CONNECTED:*-STREAMING status or will switch to "DISCONNECTED:WILL-RETRY" / "DISCONNECTED:TRYING-RECOVERY".
  • "DISCONNECTED:WILL-RETRY" a connection or connection attempt has been closed; a new attempt will be performed (possibly after a timeout).
  • "DISCONNECTED:TRYING-RECOVERY" a connection has been closed and the client has started a connection attempt and is waiting for a Server answer; if successful, the underlying session will be kept.
  • "DISCONNECTED" a connection or connection attempt has been closed. The client will not connect anymore until a new LightstreamerClient#connect call is issued.
Overrides:
See: