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 may instantly switch to the requested status. If that's not the case the client will enter a "CONNECTING" status before reaching the requested status. Also, 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 automatically switch to POLLING mode.
When changeStatus("STREAMING") is used to activate the Lightstreamer session on page start up, it is recommended to make this call as the latest action of the scripts in the page. Otherwise, if the stream connection is opened but third-party scripts are consuming most of the CPU for page initialization (initial rendering, etc.), the parsing of the streaming response could be delayed to the point that the Client switches to polling mode.
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. Note that the request to change the status is accomplished by the Engine asynchronously; this means that an invocation to getStatus() right after changeStatus might not reflect the change yet.

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. The method is not reliable and, in some cases, existing pushpages may not be reachable and may not be included in the returned list.

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.

See:
- getStatus()

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.

See:
- getStatus()

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

See:
- onStatusChange()

onClientAlert

void onClientAlert(<Number> code,<String> errorMex)

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 that 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 that in order to just suppress the default handling, the handler has to be set as null at the beginning of Master Push-Page's PushPage.onEngineCreation(), (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.
• 130 - Firebug is known to cause memory issues with
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 unexpected condition prevents some library operation on the Engine from working correctly. Possible cases usually fall into one of the following categories:
• An unexpected condition prevents an operation method from working correctly.
• A custom event handler defined for the Engine (other than onClientError) raises an exception.
• An unexpected condition occurs during an internal library task.
By setting a custom handler it is possible to log the problem or perform recovery actions, such as refreshing the page. When the error occurs during an API method invocation (i.e. the first case above), the handler is invoked in a blocking way before the method returns; however, any recovery action won't be able to restore the normal behavior of the affected method. Otherwise, the handler is invoked asynchronously with respect to application code.
In a normal operation scenario, such notification should never occur.
Note that 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.
Note that 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. In both cases, no recovery attempts would be performed and the connection status would eventually switch to "DISCONNECTED". By setting a custom handler, however, it is possible to prevent this and perform custom recovery actions.
Note that 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 that in order to just suppress the default handling, the handler has to be set as null at the beginning of the Master Push-Page's PushPage.onEngineCreation(), (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 - 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)
• 30-39 - the current connection or the whole session has been closed by external agents; the possible cause may be:
  • The session was closed by the administrator, through JMX (32) or through a "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).
• <= 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()

onStatusChange

void onStatusChange(<String> chngStatus)

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

The normal cases are the following:
• After issuing changeStatus("STREAMING") or changeStatus("POLLING"), if the current status is "DISCONNECTED" then the status switches to "CONNECTING" first; as soon as the new session is established, it will switch to the desired value.
  On the other hand if the status is already "STREAMING" or "POLLING" a switch to "CONNECTING" is usually not needed.
• After issuing changeStatus("DISCONNECTED"), the status always switches to "DISCONNECTED".
• In case of a server connection refusal, the status may switch from "CONNECTING" directly to "DISCONNECTED". Before that, however, the LightstreamerEngine.onServerError() event handler would be invoked.

Possible special cases are the following:
• In case of Server unavailability during streaming, the status may switch from "STREAMING" to "STALLED" (see Policy.setTimeoutForStalled()). If the unavailability ceases, the status will switch back to "STREAMING"; otherwise, if the unavailability persists (see Policy.setTimeoutForReconnect()), the status will switch to "CONNECTING" and eventually to "STREAMING".
• In case the connection or the whole session is forcibly closed by the Server, the status may switch from "STREAMING" or "POLLING" directly to "DISCONNECTED". Before that, however, the LightstreamerEngine.onServerError() event handler would be invoked.
• Depending on the setting in Policy.setSlowingEnabled(), in case of slow update processing, the status may switch from "STREAMING" to "POLLING".
• If the status is "POLLING" and any problem during an intermediate poll occurs, the status may switch to "CONNECTING" and eventually to "POLLING". The same holds for the "STREAMING" case, when a rebind is needed.
• Because of the Stream-sense algorithm, the status may switch from "CONNECTING" to "POLLING" even in case changeStatus("STREAMING") was issued.

Note the following caveats:
• In case of connection problems while the status is "CONNECTING", connection retries may occur with no change in the status.
• If changeStatus("STREAMING") or changeStatus("POLLING") is issued when the current status is "CONNECTING", no status change is notified. The same holds when changeStatus("DISCONNECTED") is issued and the current status is "DISCONNECTED".
• If changeStatus("STREAMING") is issued while the current status is "STREAMING" (and the call is not issued inside the LightstreamerEngine.onServerError() event handler), then the current session is kept but a new connection is performed. The same holds for the "POLLING" case.
• As soon as a successful streaming connection can be established, the Stream-sense algorithm is disabled for future connection attempts.

By setting a custom handler it is possible to perform actions related to connection and disconnection occurrences. changeStatus() can be issued directly from a handler (e.g. to prevent an automatic reconnection attempt).
Note that 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:
- changeStatus()
- getStatus()

sendMessage

Boolean sendMessage(<String> msg, <String> sequence, <MessageListener> listener, <Number> delayTimeout)

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.
Upon subsequent calls to the method, the sequential management of the involved messages is guaranteed. The ordering is determined by the order in which the calls to sendMessage are issued; in case of calls issued from different pages, the relative order is determined by the Engine.
However, any message that, for any reason, doesn't reach the Server can be discarded by the Server if this causes the subsequent message to be kept waiting for longer than a configurable timeout. Note that, because of the asynchronous transport of the requests, if a zero or very low timeout is set for a message, it is not guaranteed that the previous message can be processed, even if no communication issues occur.
Sequence identifiers can also be associated with the messages. In this case, the sequential management is restricted to all subsets of messages with the same sequence identifier associated.
Notifications of the operation outcome can be received by supplying a suitable listener. Unless the return value is false, the supplied listener is guaranteed to be eventually invoked; listeners associated with a sequence are guaranteed to be invoked sequentially.
The "UNORDERED_MESSAGES" sequence name has a special meaning. For such a sequence, immediate processing is guaranteed, while strict ordering and even sequentialization of the processing is not enforced. Likewise, strict ordering of the notifications is not enforced. However, messages that, for any reason, should fail to reach the Server whereas subsequent messages had succeeded, might still be discarded after a server-side timeout.

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 not "DISCONNECTED". Moreover, as soon as the status switches again to "DISCONNECTED", any messages still pending are abandoned and nothing more can be inferred about their processing outcome.

Parameters:
msg - A text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.
sequence - [optional] an alphanumeric identifier, used to identify a subset of messages to be managed in sequence; underscore characters are also allowed. If the "UNORDERED_MESSAGES" identifier is supplied, the message will be processed in the special way described above.
The parameter is optional; if not supplied, an empty string is used as the sequence name.
listener - [optional] an object suitable for receiving notifications about the processing outcome.
The parameter is optional; if not supplied, no notification will be available.
delayTimeout - [optional] a timeout, expressed in milliseconds. If higher than the Server default timeout, the latter will be used instead. It is ignored for the special "UNORDERED_MESSAGES" sequence, for which a server-side timeout applies.
The parameter is optional; if not supplied, the Server default timeout will be applied.

Returns:
true if the message could be sent to the Server (i.e. the current Engine status is not "DISCONNECTED"); false otherwise.

See:
- getStatus()