Class: ConnectionOptions

ConnectionOptions

Bean object that contains the policy settings used to connect to a Lightstreamer Server.
The class constructor, its prototype and any other properties should never be used directly; the library will create ConnectionOptions instances when needed.
Note that all the settings are applied asynchronously; this means that if a CPU consuming task is performed right after the call the effect of the setting will be delayed.

new ConnectionOptions()

Used by LightstreamerClient to provide an extra connection properties bean.
See:

Method Summary

getConnectTimeout
Inquiry method that gets the extra time the client can wait for a response on an opened connection.
getContentLength
Inquiry method that gets the length expressed in bytes to be used by the Server for the response body on a HTTP stream connection.
getCurrentConnectTimeout
Inquiry method that gets the extra time the client can wait for a response on an opened connection.
getFirstRetryMaxDelay
Inquiry method that gets the maximum time the client will wait before opening a new session in case the previous one is unexpectedly closed while correctly working.
getForcedTransport
Inquiry method that gets the value of the forced transport (if any).
getHttpExtraHeaders
Inquiry method that gets the JSON object containing the extra headers to be sent to the server.
getIdleTimeout
Inquiry method that gets the maximum time the Server is allowed to wait for any data to be sent in response to a polling request, if none has accumulated at request time.
getKeepaliveInterval
Inquiry method that gets the interval between two keepalive packets sent by Lightstreamer Server on a stream connection when no actual data is being transmitted.
getMaxBandwidth
Inquiry method that gets the maximum bandwidth that can be consumed for the data coming from Lightstreamer Server.
getPollingInterval
Inquiry method that gets the polling interval used for polling connections.
getReconnectTimeout
Inquiry method that gets the time the client, after entering "STALLED" status, can wait for a keepalive packet or any data on a stream connection, before disconnecting and trying to reconnect to the Server.
getRetryDelay
Inquiry method that gets the time the client can wait before opening a new session in case the previous one failed to open or was closed before it became stable.
getReverseHeartbeatInterval
Inquiry method that gets the reverse-heartbeat interval expressed in milliseconds.
getStalledTimeout
Inquiry method that gets the extra time the client can wait when an expected keepalive packet has not been received on a stream connection (and no actual data has arrived), before entering the "STALLED" status.
isCookieHandlingRequired
Inquiry method that checks if the client is going to connect only if it can guarantee that cookies pertaining to the server will be sent.
isEarlyWSOpenEnabled
Inquiry method that checks if the client is going to early-open the WebSocket connection to the address specified in ConnectionDetails#setServerAddress.
isHttpExtraHeadersOnSessionCreationOnly
Inquiry method that checks if the restriction on the forwarding of the configured extra http headers applies or not.
isServerInstanceAddressIgnored
Inquiry method that checks if the client is going to ignore the server instance address that will possibly be sent by the server.
isSlowingEnabled
Inquiry method that checks if the slowing algorithm is enabled or not.
setConnectTimeout
Setter method that sets the time the client is allowed to wait for a response to a request before dropping the connection and try with a different approach.
setContentLength
Setter method that sets the length in bytes to be used by the Server for the response body on a stream connection (a minimum length, however, is ensured by the server).
setCookieHandlingRequired
Setter method that enables/disables the cookies-are-required policy on the client side.
setCurrentConnectTimeout
Setter method that sets the time the client is allowed to wait for a response to a request before dropping the connection and try with a different approach.
setEarlyWSOpenEnabled
Setter method that enables/disables the "early-open" of the WebSocket connection.
setFirstRetryMaxDelay
Setter method that sets the maximum time to wait before opening a new session in case the previous one is unexpectedly closed while correctly working.
setForcedTransport
Setter method that can be used to disable/enable the Stream-Sense algorithm and to force the client to use a fixed transport or a fixed combination of a transport and a connection type.
setHttpExtraHeaders
Setter method that enables/disables the setting of extra HTTP headers to all the request performed to the Lightstreamer server by the client.
setHttpExtraHeadersOnSessionCreationOnly
Setter method that enables/disables a restriction on the forwarding of the extra http headers specified through ConnectionOptions#setHttpExtraHeaders.
setIdleTimeout
Setter method that sets the maximum time the Server is allowed to wait for any data to be sent in response to a polling request, if none has accumulated at request time.
setKeepaliveInterval
Setter method that sets the interval between two keepalive packets to be sent by Lightstreamer Server on a stream connection when no actual data is being transmitted.
setMaxBandwidth
Setter method that sets the maximum bandwidth expressed in kilobits/s that can be consumed for the data coming from Lightstreamer Server.
setPollingInterval
Setter method that sets the polling interval used for polling connections.
setReconnectTimeout
Setter method that sets the time the client, after entering "STALLED" status, is allowed to wait for a keepalive packet or any data on a stream connection, before disconnecting and trying to reconnect to the Server.
setRetryDelay
Setter method that sets the time to wait before opening a new session in case the previous one failed to open or was closed before it became stable.
setReverseHeartbeatInterval
Setter method that enables/disables the reverse-heartbeat mechanism on the control connection by setting the heartbeat interval.
setServerInstanceAddressIgnored
Setter method that can be used to disable/enable the automatic handling of server instance address that may be returned by the Lightstreamer server during session creation.
setSlowingEnabled
Setter method that turns on or off the slowing algorithm.
setStalledTimeout
Setter method that sets the extra time the client is allowed to wait when an expected keepalive packet has not been received on a stream connection (and no actual data has arrived), before entering the "STALLED" status.

Method Detail

getConnectTimeout() → {Number|String}

Inquiry method that gets the extra time the client can wait for a response on an opened connection. It can be either a string representation of the number of milliseconds the client can wait or the string "auto" meaning that the client will choose and change the value at will. If "auto" is returned it is possible to check the current value by calling the ConnectionOptions#getCurrentConnectTimeout method.
See:
Returns:
The time (in milliseconds) allowed before recovering a connection that received no data or the String "auto" if the allowed time is not fixed.
Type
Number | String

getContentLength() → {Number}

Inquiry method that gets the length expressed in bytes to be used by the Server for the response body on a HTTP stream connection.
Returns:
the length to be used by the Server for the response body on a HTTP stream connection
Type
Number

getCurrentConnectTimeout()

Inquiry method that gets the extra time the client can wait for a response on an opened connection. If ConnectionOptions#setConnectTimeout is set to "auto" this value might automatically change.
See:
Returns:
The time (in milliseconds) allowed before recovering a connection that received no data.

getFirstRetryMaxDelay() → {Number}

Inquiry method that gets the maximum time the client will wait before opening a new session in case the previous one is unexpectedly closed while correctly working.
See:
Returns:
The max time (in milliseconds) to wait before opening a new session.
Type
Number

getForcedTransport() → {String}

Inquiry method that gets the value of the forced transport (if any).
See:
Returns:
The forced transport or null
Type
String

getHttpExtraHeaders() → {Object}

Inquiry method that gets the JSON object containing the extra headers to be sent to the server.
See:
Returns:
the JSON object containing the extra headers to be sent
Type
Object

getIdleTimeout() → {Number}

Inquiry method that gets the maximum time the Server is allowed to wait for any data to be sent in response to a polling request, if none has accumulated at request time. The wait time used by the Server, however, may be different, because of server side restrictions.
See:
Returns:
The time (in milliseconds) the Server is allowed to wait for data to send upon polling requests.
Type
Number

getKeepaliveInterval() → {Number}

Inquiry method that gets the interval between two keepalive packets sent by Lightstreamer Server on a stream connection when no actual data is being transmitted.
If the value has just been set and a connection to Lightstreamer Server has not been established yet, the returned value is the time that is being requested to the Server. Afterwards, the returned value is the time used by the Server, that may be different, because of Server side constraints.
See:
Returns:
The time, expressed in milliseconds, between two keepalive packets sent by the Server.
Type
Number

getMaxBandwidth() → {Number}

Inquiry method that gets the maximum bandwidth that can be consumed for the data coming from Lightstreamer Server.
If the value has just been set and a connection to Lightstreamer Server has not been established yet, the returned value is the bandwidth limit that is being requested to the Server. Afterwards, the returned value is the limit applied by the Server, that may be different, because of Server side constraints.
See:
Returns:
The maximum bandwidth requested for the streaming or polling connection, expressed in kbps (kilobits/sec), or the string "unlimited".
Type
Number

getPollingInterval() → {Number}

Inquiry method that gets the polling interval used for polling connections.
If the value has just been set and a polling request to Lightstreamer Server has not been performed yet, the returned value is the polling interval that is being requested to the Server. Afterwards, the returned value is the the time between subsequent polling requests that is really allowed by the Server, that may be different, because of Server side constraints.
See:
Returns:
The time (in milliseconds) between subsequent polling requests.
Type
Number

getReconnectTimeout() → {Number}

Inquiry method that gets the time the client, after entering "STALLED" status, can wait for a keepalive packet or any data on a stream connection, before disconnecting and trying to reconnect to the Server.
See:
Returns:
The idle time (in milliseconds) admitted in "STALLED" status before trying to reconnect to the Server.
Type
Number

getRetryDelay() → {Number}

Inquiry method that gets the time the client can wait before opening a new session in case the previous one failed to open or was closed before it became stable.
See:
Returns:
The time (in milliseconds) to wait before opening a new session.
Type
Number

getReverseHeartbeatInterval() → {Number}

Inquiry method that gets the reverse-heartbeat interval expressed in milliseconds.
See:
Returns:
the reverse-heartbeat interval
Type
Number

getStalledTimeout() → {Number}

Inquiry method that gets the extra time the client can wait when an expected keepalive packet has not been received on a stream connection (and no actual data has arrived), before entering the "STALLED" status.
See:
Returns:
The idle time (in milliseconds) admitted before entering the "STALLED" status.
Type
Number

isCookieHandlingRequired() → {boolean}

Inquiry method that checks if the client is going to connect only if it can guarantee that cookies pertaining to the server will be sent.
See:
Returns:
true/false if the cookies-are-required policy is enabled or not.
Type
boolean

isEarlyWSOpenEnabled() → {boolean}

Inquiry method that checks if the client is going to early-open the WebSocket connection to the address specified in ConnectionDetails#setServerAddress.
See:
Returns:
true/false if the early-open of the WebSocket connection is enabled or not.
Type
boolean

isHttpExtraHeadersOnSessionCreationOnly() → {boolean}

Inquiry method that checks if the restriction on the forwarding of the configured extra http headers applies or not.
See:
Returns:
true/false if the restriction applies or not.
Type
boolean

isServerInstanceAddressIgnored() → {boolean}

Inquiry method that checks if the client is going to ignore the server instance address that will possibly be sent by the server.
See:
Returns:
Whether or not to ignore the server instance address sent by the server.
Type
boolean

isSlowingEnabled() → {boolean}

Inquiry method that checks if the slowing algorithm is enabled or not.
See:
Returns:
Whether the slowing algorithm is enabled or not.
Type
boolean

setConnectTimeout(connectTimeout)

Setter method that sets the time the client is allowed to wait for a response to a request before dropping the connection and try with a different approach. It can either be a fixed value, in which case the same timeout is always used, or the string "auto" meaning that the library might change this timeout at will.

Streaming: The timeout is applied on any attempt to setup the streaming connection. If after the timeout no data has arrived on the stream connection, the client may automatically switch transport or may resort to a polling connection.
Polling and pre-flight request: The timeout is applied to every connection. If after the timeout no data has arrived on the polling connection, the entire connection process restarts from scratch.

Default value: "auto".

Lifecycle: This value can be set and changed at any time.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "connectTimeout" on any ClientListener .

Parameters:
Name Type Description
connectTimeout Number | String The time (in milliseconds) allowed before recovering a connection that received no data.
Throws:
if a negative, zero, or a not-number value different from "auto" is passed.
Type
IllegalArgumentException

setContentLength(contentLength)

Setter method that sets the length in bytes to be used by the Server for the response body on a stream connection (a minimum length, however, is ensured by the server). After the content length exhaustion, the connection will be closed and a new bind connection will be automatically reopened. If it is 0, the length is decided by the Server.
NOTE that this setting only applies to the "HTTP-STREAMING" case (i.e. not to WebSockets).

Default value: 2000000 (2 MB).

Lifecycle: The content length should be set on the LightstreamerClient#connectionOptions object before calling the LightstreamerClient#connect method. However, the value can be changed at any time: the supplied value will be used for the next HTTP bind request.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "contentLength" on any ClientListener .

Parameters:
Name Type Description
contentLength Number The length to be used by the Server for the response body on a HTTP stream connection.
Throws:
if a negative, zero, decimal or a not-number value is passed.
Type
IllegalArgumentException

setCookieHandlingRequired(cookieHandlingRequired)

Setter method that enables/disables the cookies-are-required policy on the client side. Enabling this policy will guarantee that cookies pertaining to the Lightstreamer server will be sent with each request.
On the other hand enabling this setting may prevent the client from opening a streaming connection or even to connect at all depending on the browser/environment.

Default value: false.

Lifecycle:This method can be called at any time. If called while the client is already connected to the server, it will be applied to the next bind request (but for the "WS-STREAMING" case, where bind is never performed).

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "cookieHandlingRequired" on any ClientListener listening to any LightstreamerClient sharing the same connection with the LightstreamerClient owning the ConnectionOptions upon which the setter was called.

Parameters:
Name Type Description
cookieHandlingRequired boolean true/false to enable/disable the cookies-are-required policy.
Throws:
if a not boolean value is given.
Type
IllegalArgumentException

setCurrentConnectTimeout(connectTimeout)

Setter method that sets the time the client is allowed to wait for a response to a request before dropping the connection and try with a different approach. If ConnectionOptions#setConnectTimeout is set to auto this value might be later changed by the library, on the other hand if setConnectTimeout is configured to a fixed value this method will have no effect.

Default value: 4000 (4 seconds).

Lifecycle: This value can be set and changed at any time.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "currentConnectTimeout" on any ClientListener .

Parameters:
Name Type Description
connectTimeout Number The time (in milliseconds) allowed before recovering a connection that received no data.
Throws:
if a negative, zero, or a not-number value is passed.
Type
IllegalArgumentException

setEarlyWSOpenEnabled(earlyWSOpenEnabled)

Setter method that enables/disables the "early-open" of the WebSocket connection.
When enabled a WebSocket is open to the address specified through ConnectionDetails#setServerAddress before a potential server instance address is received during session creation. In this case if a server instance address is received, the previously open WebSocket is closed and a new one is open to the received server instance address.
If disabled, the session creation is completed to verify if such a server instance address is configured in the server before opening the WebSocket.
For these reasons this setting should be set to false if the server configuration specifies a <control_link_address> and/or a <control_link_machine_name> element in its configuration; viceversa it should be set to true if such elements are not set on the target server(s) configuration.

Edition Note: Server Clustering is not supported when using Lightstreamer in Moderato edition.

Default value: true.

Lifecycle:This method can be called at any time. If called while the client already owns a session it will be applied the next time a session is requested to a server.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "earlyWSOpenEnabled" on any ClientListener .

Parameters:
Name Type Description
earlyWSOpenEnabled boolean true/false to enable/disable the early-open of the WebSocket connection.
See:
Throws:
if a not boolean value is given.
Type
IllegalArgumentException

setFirstRetryMaxDelay(firstRetryMaxDelay)

Setter method that sets the maximum time to wait before opening a new session in case the previous one is unexpectedly closed while correctly working. The actual delay is a randomized value between 0 and this value. This randomization might help avoid a load spike on the cluster due to simultaneous reconnections, should one of the active servers be stopped. Note that this delay is only applied before the first reconnection: should such reconnection fail the setting of ConnectionOptions#setRetryDelay is applied.

Default value: 100 (0.1 seconds).

Lifecycle: This value can be set and changed at any time.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "firstRetryMaxDelay" on any ClientListener .

Parameters:
Name Type Description
firstRetryMaxDelay Number The max time (in milliseconds) to wait before opening a new session.
Throws:
if a negative, zero, or a not-number value is passed.
Type
IllegalArgumentException

setForcedTransport(forcedTransport)

Setter method that can be used to disable/enable the Stream-Sense algorithm and to force the client to use a fixed transport or a fixed combination of a transport and a connection type. When a combination is specified the Stream-Sense algorithm is completely disabled.
The method can be used to switch between streaming and polling connection types and between HTTP and WebSocket transports.
In some cases, the requested status may not be reached, because of connection or environment problems. In that case the client will continuously attempt to reach the configured status.
Note that if the Stream-Sense algorithm is disabled, the client may still enter the "CONNECTED:STREAM-SENSING" status; however, in that case, if it eventually finds out that streaming is not possible, no recovery will be tried.

Default value: null (full Stream-Sense enabled).

Lifecycle:This method can be called at any time. If called while the client is connecting or connected it will instruct to switch connection type to match the given configuration.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "forcedTransport" on any ClientListener .

Parameters:
Name Type Description
forcedTransport String can be one of the following:
  • null: the Stream-Sense algorithm is enabled and the client will automatically connect using the most appropriate transport and connection type among those made possible by the browser/environment.
  • "WS": the Stream-Sense algorithm is enabled as in the null case but the client will only use WebSocket based connections. If a connection over WebSocket is not possible because of the browser/environment the client will not connect at all.
  • "HTTP": the Stream-Sense algorithm is enabled as in the null case but the client will only use HTTP based connections. If a connection over HTTP is not possible because of the browser/environment the client will not connect at all.
  • "WS-STREAMING": the Stream-Sense algorithm is disabled and the client will only connect on Streaming over WebSocket. If Streaming over WebSocket is not possible because of the browser/environment the client will not connect at all.
  • "HTTP-STREAMING": the Stream-Sense algorithm is disabled and the client will only connect on Streaming over HTTP. If Streaming over HTTP is not possible because of the browser/environment the client will not connect at all.
  • "WS-POLLING": the Stream-Sense algorithm is disabled and the client will only connect on Polling over WebSocket. If Polling over WebSocket is not possible because of the browser/environment the client will not connect at all.
  • "HTTP-POLLING": the Stream-Sense algorithm is disabled and the client will only connect on Polling over HTTP. If Polling over HTTP is not possible because of the browser/environment the client will not connect at all.
Throws:
if the given value is not in the list of the admitted ones.
Type
IllegalArgumentException

setHttpExtraHeaders(headersObj)

Setter method that enables/disables the setting of extra HTTP headers to all the request performed to the Lightstreamer server by the client. Note that when the value is set WebSockets are disabled unless ConnectionOptions#setHttpExtraHeadersOnSessionCreationOnly is set to true. Also note that if the browser/environment does not have the possibility to send extra headers while some are specified through this method it will fail to connect. Also note that the Content-Type header is reserved by the client library itself, while other headers might be refused by the browser/environment and others might cause the connection to the server to fail. The use of custom headers might also cause the browser/environment to send an OPTIONS request to the server before opening the actual connection.

Default value: null (meaning no extra headers are sent).

Lifecycle:This method can be called at any time: each request will carry headers accordingly to the most recent setting. Note that if extra headers are specified while a WebSocket is open, then requests will continue to go through the WebSocket and thus will ignore this setting.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "httpExtraHeaders" on any ClientListener .

Parameters:
Name Type Description
headersObj Object a JSON object containing header-name header-value pairs. Null can be specified to avoid extra headers to be sent.

setHttpExtraHeadersOnSessionCreationOnly(httpExtraHeadersOnSessionCreationOnly)

Setter method that enables/disables a restriction on the forwarding of the extra http headers specified through ConnectionOptions#setHttpExtraHeaders. If true, said headers will only be sent during the session creation process (and thus will still be available to the Metadata Adapter notifyUser method) but will not be sent on following requests. On the contrary, when set to true, the specified extra headers will be sent to the server on every request: as a consequence, if any extra header is actually specified, WebSockets will be disabled (as the current browser client API does not support the setting of custom HTTP headers).

Default value: false.

Lifecycle:This method can be called at any time enabling/disabling the sending of headers on future requests. This might not result in a WebSocket being open until a new session is established.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "httpExtraHeadersOnSessionCreationOnly" on any ClientListener .

Parameters:
Name Type Description
httpExtraHeadersOnSessionCreationOnly boolean true/false to enable/disable the restriction on extra headers forwarding.
Throws:
if a not boolean value is given.
Type
IllegalArgumentException

setIdleTimeout(idleTimeout)

Setter method that sets the maximum time the Server is allowed to wait for any data to be sent in response to a polling request, if none has accumulated at request time. Setting this time to a nonzero value and the polling interval to zero leads to an "asynchronous polling" behaviour, which, on low data rates, is very similar to the streaming case. Setting this time to zero and the polling interval to a nonzero value, on the other hand, leads to a classical "synchronous polling".
Note that the Server may, in some cases, delay the answer for more than the supplied time, to protect itself against a high polling rate or because of bandwidth restrictions. Also, the Server may impose an upper limit on the wait time, in order to be able to check for client-side connection drops.

Default value: 19000 (19 seconds).

Lifecycle: The idle timeout should be set on the LightstreamerClient#connectionOptions object before calling the LightstreamerClient#connect method. However, the value can be changed at any time: the supplied value will be used for the next polling request.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "idleTimeout" on any ClientListener .

Parameters:
Name Type Description
idleTimeout Number The time (in milliseconds) the Server is allowed to wait for data to send upon polling requests.
See:
Throws:
if a negative or a decimal or a not-number value is passed.
Type
IllegalArgumentException

setKeepaliveInterval(keepaliveInterval)

Setter method that sets the interval between two keepalive packets to be sent by Lightstreamer Server on a stream connection when no actual data is being transmitted. The Server may, however, impose a lower limit on the keepalive interval, in order to protect itself. Also, the Server may impose an upper limit on the keepalive interval, in order to be able to check for client-side connection drops.

Default value: If no value is supplied, the Server will send keepalive packets based on its own configuration.

Lifecycle: The keepalive interval should be set on the LightstreamerClient#connectionOptions object before calling the LightstreamerClient#connect method. However, the value can be changed at any time: the supplied value will be used for the next bind request (this only applies to the "HTTP-STREAMING" case).
Note that, after a connection, the value may be changed to the one imposed by the Server.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "keepaliveInterval" on any ClientListener .

Parameters:
Name Type Description
keepaliveInterval Number The time, expressed in milliseconds, between two keepalive packets.
Throws:
if a negative or a decimal or a not-number value is passed.
Type
IllegalArgumentException

setMaxBandwidth(maxBandwidth)

Setter method that sets the maximum bandwidth expressed in kilobits/s that can be consumed for the data coming from Lightstreamer Server. A limit on bandwidth may already be posed by the Metadata Adapter, but the client can furtherly restrict this limit. The limit applies to the bytes received in each streaming or polling connection.

Edition Note: The request is ignored by the Server if it runs in Allegro edition (i.e. "unlimited" is assumed).

Edition Note: The request is ignored by the Server if it runs in Moderato edition (i.e. "unlimited" is assumed).

Default value: "unlimited".

Lifecycle: The bandwidth limit can be set and changed at any time. If a connection is currently active, the bandwith limit for the connection is changed on the fly.
Note that, after a connection, the value may be changed to the one imposed by the Server.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "maxBandwidth" on any ClientListener .

Parameters:
Name Type Description
maxBandwidth Number The maximum bandwidth requested for the streaming or polling connection, expressed in kbps (kilobits/sec). The string "unlimited" is also allowed, to mean that the maximum bandwidth can be decided on the Server side (the check is case insensitive).
Throws:
if a negative, zero, or a not-number value (excluding special values) is passed.
Type
IllegalArgumentException

setPollingInterval(pollingInterval)

Setter method that sets the polling interval used for polling connections. The client switches from the default streaming mode to polling mode when the client network infrastructure does not allow streaming. Also, polling mode can be forced by calling ConnectionOptions#setForcedTransport with "WS-POLLING" or "HTTP-POLLING" as parameter.
The polling interval affects the rate at which polling requests are issued. It is the time between the start of a polling request and the start of the next request. However, if the polling interval expires before the first polling request has returned, then the second polling request is delayed. This may happen, for instance, when the Server delays the answer because of the idle timeout setting. In any case, the polling interval allows for setting an upper limit on the polling frequency.
The Server does not impose a lower limit on the client polling interval. However, in some cases, it may protect itself against a high polling rate by delaying its answer. Network limitations and configured bandwidth limits may also lower the polling rate, despite of the client polling interval.
The Server may, however, impose an upper limit on the polling interval, in order to be able to promptly detect terminated polling request sequences and discard related session information.

Default value: 0 (pure "asynchronous polling" is configured).

Lifecycle:The polling interval should be set on the LightstreamerClient#connectionOptions object before calling the LightstreamerClient#connect method. However, the value can be changed at any time: the supplied value will be used for the next bind request.
Note that, after each polling request, the value may be changed to the one imposed by the Server.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "pollingInterval" on any ClientListener

Parameters:
Name Type Description
pollingInterval Number The time (in milliseconds) between subsequent polling requests. Zero is a legal value too, meaning that the client will issue a new polling request as soon as a previous one has returned.
See:
Throws:
if a negative or a decimal or a not-number value is passed.
Type
IllegalArgumentException

setReconnectTimeout(reconnectTimeout)

Setter method that sets the time the client, after entering "STALLED" status, is allowed to wait for a keepalive packet or any data on a stream connection, before disconnecting and trying to reconnect to the Server.

Default value: 3000 (3 seconds).

Lifecycle: This value can be set and changed at any time.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "reconnectTimeout" on any ClientListener .

Parameters:
Name Type Description
reconnectTimeout Number The idle time (in milliseconds) allowed in "STALLED" status before trying to reconnect to the Server.
See:
Throws:
if a negative, zero, or a not-number value is passed.
Type
IllegalArgumentException

setRetryDelay(retryDelay)

Setter method that sets the time to wait before opening a new session in case the previous one failed to open or was closed before it became stable. Note that the delay is calculated from the moment the effort to create a new connection is made, not from the moment the failure is detected or the connection timeout expired.

Default value: 5000 (5 seconds).

Lifecycle: This value can be set and changed at any time.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "retryDelay" on any ClientListener .

Parameters:
Name Type Description
retryDelay Number The time (in milliseconds) to wait before opening a new session.
See:
Throws:
if a negative, zero, or a not-number value is passed.
Type
IllegalArgumentException

setReverseHeartbeatInterval(reverseHeartbeatInterval)

Setter method that enables/disables the reverse-heartbeat mechanism on the control connection by setting the heartbeat interval. If the given value (expressed in milliseconds) equals 0 then the reverse-heartbeat mechanism will be disabled; otherwise if the given value is greater than 0 the mechanism will be enabled with the specified interval. When the mechanism is active the client will send a set of empty control requests to the server, so that there is at most the specified interval between a control request and the following one. The mechanism is not for general use and should only be activated if there is a need to keep the control HTTP connection open even when idle, to avoid connection reestablishment overhead. However it is not guaranteed that the connection will be kept open, as the underlying TCP implementation may open a new socket each time a HTTP request needs to be sent.
NOTE:The mechanism is automatically disabled during polling sessions and/or if the current session transport is a WebSocket.

Default value: 0 (meaning that the mechanism is disabled).

Lifecycle:This method can be called at any time enabling/disabling the reverse-heartbeat mechanism on the fly (if applicable).

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "reverseHeartbeatInterval" on any ClientListener .

Parameters:
Name Type Description
reverseHeartbeatInterval Number the interval, expressed in milliseconds, between subsequent reverse-heartbeats.
Throws:
if a negative, zero, decimal or a not-number value is passed.
Type
IllegalArgumentException

setServerInstanceAddressIgnored(serverInstanceAddressIgnored)

Setter method that can be used to disable/enable the automatic handling of server instance address that may be returned by the Lightstreamer server during session creation.
In fact, when a Server cluster is in place, the Server address specified through ConnectionDetails#setServerAddress 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 an address which uniquely identifies its own instance.
Setting this value to true permits to ignore that address and to always connect through the address supplied in setServerAddress. This may be needed in a test environment, if the Server address specified is actually a local address to a specific Server instance in the cluster.

Edition Note: Server Clustering is not supported when using Lightstreamer in Moderato edition.

Default value: false.

Lifecycle:This method can be called at any time. If called while connected, it will be applied when the next session creation request is issued.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "serverInstanceAddressIgnored" on any ClientListener .

Parameters:
Name Type Description
serverInstanceAddressIgnored boolean true or false, to ignore or not the server instance address sent by the server.
See:
Throws:
if a not boolean value is given.
Type
IllegalArgumentException

setSlowingEnabled(slowingEnabled)

Setter method that turns on or off the slowing algorithm. This heuristic algorithm tries to detect when the client CPU is not able to keep the pace of the events sent by the Server on a streaming connection. In that case, an automatic transition to polling is performed.
In polling, the client handles all the data before issuing the next poll, hence a slow client would just delay the polls, while the Server accumulates and merges the events and ensures that no obsolete data is sent.
Only in very slow clients, the next polling request may be so much delayed that the Server disposes the session first, because of its protection timeouts. In this case, a request for a fresh session will be reissued by the client and this may happen in cycle.

Default value: true.

Lifecycle:The algorithm should be enabled/disabled on the LightstreamerClient#connectionOptions object before calling the LightstreamerClient#connect method. However, the value can be changed at any time: the supplied value will be used for the next connection attempt.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "slowingEnabled" on any ClientListener .

Parameters:
Name Type Description
slowingEnabled boolean true or false, to enable or disable the heuristic algorithm that lowers the item update frequency.
Throws:
if a not boolean value is given.
Type
IllegalArgumentException

setStalledTimeout(stalledTimeout)

Setter method that sets the extra time the client is allowed to wait when an expected keepalive packet has not been received on a stream connection (and no actual data has arrived), before entering the "STALLED" status.

Default value: 2000 (2 seconds).

Lifecycle: This value can be set and changed at any time.

Notification: A change to this setting will be notified through a call to ClientListener#onPropertyChange with argument "stalledTimeout" on any ClientListener .

Parameters:
Name Type Description
stalledTimeout Number The idle time (in milliseconds) allowed before entering the "STALLED" status.
See:
Throws:
if a negative, zero, or a not-number value is passed.
Type
IllegalArgumentException