Class LightstreamerEngine

Object
   |
   +--LightstreamerEngine

class LightstreamerEngine

Facade class for the management of the communication to Lightstreamer Server. Used to provide configuration settings, event handlers and operations for the control of the connection lifecycle.
Exactly one LightstreamerEngine instance is bound to the Engine page as a consequence of the PushPage.createEngine() call.
After page loading, a local proxy for this instance is made available to each Push-Page through the PushPage.onEngineCreation() and PushPage.onEngineReady() callbacks, in order to use operations, change settings and set event handlers to be executed locally on the Push-Page.
Defined in lsengine.js

Field Detail

connection

Connection connection

Bean object that contains connection properties for the client Engine. It can be accessed in order to provide connection properties. Set up by the Engine object at its own creation.

context

Context context

Bean object that contains context properties for the client Engine. It can be accessed in order to provide context properties. Set up by the Engine object at its own creation.

policy

Policy policy

Bean object that contains connection policy properties for the client Engine. It can be accessed in order to provide connection policy properties. Set up by the Engine object at its own creation.

LightstreamerEngine

LightstreamerEngine()

Used by Lightstreamer to create a LightstreamerEngine instance to be bound to the Engine page to provide configuration settings and event handlers for the management of the communication to Lightstreamer Server.

changeStatus

void changeStatus(<String> newStatus)

Operation method that requests to change the client Engine status. It can be used to start and stop the connection and to switch between streaming and polling connection types. For requests that require a new connection attempt, the Engine cannot instantly switch to the requested status, because entering a "CONNECTING" status phase is needed first. In some cases, the requested status may not even be reached, because of connection problems.
Moreover, for "STREAMING" requests, the so called "Stream-Sense" mechanism is started. If the Engine does not receive any answer for some seconds from the streaming connection, then it will open a new connection in polling mode. If, however, an answer were received from the streaming connection after the polling connection had been started, then the streaming connection could be recovered, depending on the Policy.setBufferedStreamingHandled() setting.
Note that as "polling connection" we mean a loop of polling requests, each of which requires opening a synchronous (i.e. not streaming) connection to Lightstreamer Server.

Lifecycle: An Engine status change can be requested at any time.

Parameters:
newStatus - The requested status. It can be one of the following values:
• "STREAMING"
• "POLLING"
• "DISCONNECTED"

See:
- getStatus()
- onStatusChange()

getApplicationName

String getApplicationName()

Inquiry method that gets the name of the application, as supplied to the Engine.

Returns:
application name supplied.

getPushPages

Array getPushPages()

Inquiry method that returns an Array containing all the PushPage instances that are currently bound to this LightstreamerEngine.

Returns:
An Array, containing all the PushPages currently bound to this LightstreamerEngine. The Array could be empty.

getSessionServerAddress

String getSessionServerAddress()

Inquiry method that gets the hostname to be used to issue all requests related to the current session. In fact, when a Server cluster is in place, the Server hostname specified through Connection.setLSHost() can identify various Server instances; in order to ensure that all requests related to a session are issued to the same Server instance, the Server can answer to the session opening request by providing a hostname which uniquely identifies its own instance. When this is the case, this hostname is returned by the method; otherwise, the hostname specified through Connection.setLSHost() is returned.
Edition Note: Server Clustering is not supported when using Lightstreamer in Moderato edition.

Lifecycle: The method gives a meaningful answer only when a session is currently active. This means that the current Engine status should be "STREAMING", "POLLING" or "STALLED".

Returns:
hostname used to issue all requests related to the current session.

getSessionServerName

String getSessionServerName()

Inquiry method that gets the instance name of the Server which is serving the current session. To be more precise, each answering port configured on a Server instance (through a <http_server> or <https_server> element in the Server configuration file) can be given a different name; the name related to the port to which the session opening request has been issued is returned.
Note that in case of polling or in case rebind requests are needed, subsequent requests related to the same session may be issued to a port different than the one used for the first request; the names configured for those ports would not be reported. This, however, can only happen when a Server cluster is in place and particular configurations for the load balancer are used.
Edition Note: Server Clustering is not supported when using Lightstreamer in Moderato edition.

Lifecycle: The method gives a meaningful answer only when a session is currently active. This means that the current Engine status should be "STREAMING", "POLLING" or "STALLED".

Returns:
name configured for the Server instance which is managing the current session.

getStatus

String getStatus()

Inquiry method that gets the current client Engine status.

Returns:
The current Engine status. It can be one of the following values:
• "CONNECTING" the Engine is waiting for a Server's response in order to establish a connection
• "STREAMING" a streaming connection is active
• "POLLING" a polling connection is in progress
• "STALLED" the Server has not been sending data on an active streaming connection for longer than a configured time
• "DISCONNECTED" no connection is currently active

onClientAlert

void onClientAlert(<Number> code,mex)

Event handler that is called whenever a browser related problem arises. By setting a custom handler it is possible to notify the problem in a consistent way; it is not advisable to suppress the notifications, because they warn the final user on critical conditions that prevent the application from working.
Note: Any Push-Page can supply its own event handler, by assigning a proper method to its local proxy of the LightstreamerEngine object. The handler will be executed in the Push-Page context.

Default implementation: The handler is initially undefined for each Push-Page. As long as no Push-Page declares its own handler, an alert with the error code and information message is shown.
Note: In order to just suppress the default handling, set the handler as null at the beginning of PushPage.onEngineReady() in the Master Push-Page (in case the Engine is created by specifying "SHARE_SESSION" as onSimilarEngineFound in the PushPage.createEngine() call, consider that any Push-Page may become a Master Push-Page).

Parameters:
code - The error code related to the error. It can be one of the following:
• 100 - A specific antivirus software installed on the client machine could prevent the framework from working properly.
• 110 - The JavaScript engine of the browser is not respecting the timeouts in setTimeout method calls.
• 120 - There are probably other web applications connected to the same Lightstreamer Server within the same browser instance. That could prevent the current application from connecting to the Server.
errorMex - The text of the alert that will be displayed to the user.

onClientError

void onClientError(<String> errorMex)

Event handler that is called whenever an incorrect operation invocation or an incorrect configuration property setting is done on the client Engine. The handler is also called whenever a custom event handler defined in the Engine page (other than onClientError) raises an exception (provided that exception handling is supported by the browser). By setting a custom handler it is possible to perform recovery actions. However, such notifications should never occur.
Note: Any Push-Page can supply its own event handler, by assigning a proper method to its local proxy of the LightstreamerEngine object. The handler will be executed in the Push-Page context.
Notifications for errors occurring in the Engine initialization phase (i.e. before the Push-Page has supplied its handler) are lost, but for the Master Push-Page. For this page, the notifications are kept and sent, upon PushPage.onEngineReady() return, to the handler currently set.

Default implementation: The handler is initially undefined for each Push-Page. As long as no Push-Page declares its own handler, nothing is done.

Parameters:
errorMex - The description of the error generated on the Engine.

onServerError

void onServerError(<Number> errorCode, <String> 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. By setting a custom handler it is possible to perform recovery actions.
Note: Any Push-Page can supply its own event handler, by assigning a proper method to its local proxy of the LightstreamerEngine object. The handler will be executed in the Push-Page context.

Default implementation: The handler is initially undefined for each Push-Page. As long as no Push-Page declares its own handler, an alert with the error code and information message is shown.
Note: In order to just suppress the default handling, set the handler as null at the beginning of PushPage.onEngineReady() in the Master Push-Page (in case the Engine is created by specifying "SHARE_SESSION" as onSimilarEngineFound in the PushPage.createEngine() call, consider that any Push-Page may become a Master Push-Page).

Parameters:
errorCode - The error code. It can be one of the following:
• 1 - user/password check failed
• 2 - requested Adapter Set not available
• 7 - maximum allowed number of sessions reached
• 8 - maximum number of concurrent connections reached
• 9 - maximum server load reached
• 10 - new connections temporarily blocked
• 11 - streaming is not available because of Server license restrictions (this can only happen with special licenses)
• 30-39 - the current session has been closed by external agents; the possible cause may be:
  • The session was closed by the administrator, through JMX or through a "kill" request
  • 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
  • An unexpected error occurred on the Server while the session was in activity
  A detailed description and error code for the specific cause is currently not supplied
• <= 0 - the Metadata Adapter has refused the user connection; the code value is dependent on the specific Metadata Adapter implementation
errorMessage - The description of the error as sent by the Server.

See:
- Connection.setAdapterName()

onStatusChange

void onStatusChange(<String> chngStatus)

Event handler that receives a notification each time the Engine status has changed. By setting a custom handler it is possible to perform actions related to connection and disconnection occurrences.
Note: Any Push-Page can supply its own event handler, by assigning a proper method to its local proxy of the LightstreamerEngine object. The handler will be executed in the Push-Page context.

Default implementation: The handler is initially undefined for each Push-Page. As long as no Push-Page declares its own handler, the default handling is to substitute the status bar message with a message that indicates the new Engine status (on browsers where this operation is allowed). This default behaviour can be suppressed by setting the "suppressDefaultStatusChangeHandler" argument as true when calling PushPage.createEngine() in the Master Push-Page.
Setting a null handler from any Push-Page also causes the default handling to be ceased.

Parameters:
chngStatus - The new Engine status. It can be one of the following values:
• "CONNECTING" the Engine has started a connection attempt and is waiting for a Server answer
• "STREAMING" a streaming connection has been established
• "POLLING" a polling connection has been started
• "STALLED" the Server has not been sending data on an active streaming connection for longer than a configured time
• "DISCONNECTED" a connection or connection attempt has been closed

See:
- getStatus()

sendMessage

Boolean sendMessage(<String> msg)

Operation method that sends a text message to the Server. The message is interpreted and handled by the Metadata Adapter associated to the current connection.
No information can be received to confirm that the message has reached the Server and has been accepted by the Metadata Adapter.

Lifecycle: Since a message is handled by the Metadata Adapter associated to the current connection, a message can be sent only if a connection is currently active. More precisely, it is possible to send a message if the current Engine status is "STREAMING", "POLLING" or even "STALLED". In the latter case, however, the Server session associated to the current connection may have already been closed.

Parameters:
msg - A text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.

Returns:
true if the message could be sent to the Server (i.e. the current Engine status is "STREAMING", "POLLING" or "STALLED"); false otherwise.

See:
- getStatus()