/** * This is a dummy constructor not to be used in any case. */ export class Logger { constructor(); /** * Receives log messages at FATAL level. * @param message - The message to be logged. * @param [exception] - An Exception instance related to the current log message. */ fatal(message: string, exception?: Error): void; /** * Checks if this Logger is enabled for the FATAL level. * The method should return true if this Logger is enabled for FATAL events, * false otherwise. *
This property is intended to let the library save computational cost by suppressing the generation of * log FATAL statements. However, even if the method returns false, FATAL log * lines may still be received by the {@link Logger#fatal} method * and should be ignored by the Logger implementation. * @returns true if FATAL logging is enabled, false otherwise */ isFatalEnabled(): boolean; /** * Receives log messages at ERROR level. * @param message - The message to be logged. * @param [exception] - An Exception instance related to the current log message. */ error(message: string, exception?: Error): void; /** * Checks if this Logger is enabled for the ERROR level. * The method should return true if this Logger is enabled for ERROR events, * false otherwise. *
This property is intended to let the library save computational cost by suppressing the generation of * log ERROR statements. However, even if the method returns false, ERROR log * lines may still be received by the {@link Logger#error} method * and should be ignored by the Logger implementation. * @returns true if ERROR logging is enabled, false otherwise */ isErrorEnabled(): boolean; /** * Receives log messages at WARN level. * @param message - The message to be logged. * @param [exception] - An Exception instance related to the current log message. */ warn(message: string, exception?: Error): void; /** * Checks if this Logger is enabled for the WARN level. * The method should return true if this Logger is enabled for WARN events, * false otherwise. *
This property is intended to let the library save computational cost by suppressing the generation of * log WARN statements. However, even if the method returns false, WARN log * lines may still be received by the {@link Logger#warn} method * and should be ignored by the Logger implementation. * @returns true if WARN logging is enabled, false otherwise */ isWarnEnabled(): boolean; /** * Receives log messages at INFO level. * @param message - The message to be logged. * @param [exception] - An Exception instance related to the current log message. */ info(message: string, exception?: Error): void; /** * Checks if this Logger is enabled for the INFO level. * The method should return true if this Logger is enabled for INFO events, * false otherwise. *
This property is intended to let the library save computational cost by suppressing the generation of * log INFO statements. However, even if the method returns false, INFO log * lines may still be received by the {@link Logger#info} method * and should be ignored by the Logger implementation. * @returns true if INFO logging is enabled, false otherwise */ isInfoEnabled(): boolean; /** * Receives log messages at DEBUG level. * @param message - The message to be logged. * @param [exception] - An Exception instance related to the current log message. */ debug(message: string, exception?: Error): void; /** * Checks if this Logger is enabled for the DEBUG level. * The method should return true if this Logger is enabled for DEBUG events, * false otherwise. *
This property is intended to let the library save computational cost by suppressing the generation of * log DEBUG statements. However, even if the method returns false, DEBUG log * lines may still be received by the {@link Logger#debug} method * and should be ignored by the Logger implementation. * @returns true if DEBUG logging is enabled, false otherwise */ isDebugEnabled(): boolean; /** * Receives log messages at TRACE level. * @param message - The message to be logged. * @param [exception] - An Exception instance related to the current log message. */ trace(message: string, exception?: Error): void; /** * Checks if this Logger is enabled for the TRACE level. * The method should return true if this Logger is enabled for TRACE events, * false otherwise. *
This property is intended to let the library save computational cost by suppressing the generation of * log TRACE statements. However, even if the method returns false, TRACE log * lines may still be received by the {@link Logger#trace} method * and should be ignored by the Logger implementation. * @returns true if TRACE logging is enabled, false otherwise */ isTraceEnabled(): boolean; } /** * This is a dummy constructor not to be used in any case. */ export class LoggerProvider { constructor(); /** * Invoked to request a {@link Logger} instance that will be used for logging occurring * on the given category. It is suggested, but not mandatory, that subsequent * calls to this method related to the same category return the same {@link Logger} * instance. * @param category - the log category all messages passed to the given * Logger instance will pertain to. * @returns A Logger instance that will receive log lines related to * the given category. */ getLogger(category: string): Logger; } /** * This is a dummy constructor not to be used in any case. */ export class ClientListener { constructor(); /** * 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 {@link 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. * @param errorCode - The error code. It can be one of the * following: * * @param errorMessage - The description of the error as sent * by the Server. */ onServerError?(errorCode: number, errorMessage: string): void; /** * 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 {@link LightstreamerClient#disconnect}) or by * internal actions. *

The normal cases are the following: * *
Possible special cases are the following: * * *
By setting a custom handler it is possible to perform * actions related to connection and disconnection occurrences. Note that * {@link LightstreamerClient#connect} and {@link LightstreamerClient#disconnect}, * as any other method, can be issued directly from within a handler. * @param chngStatus - The new status. It can be one of the * following values: * */ onStatusChange?(chngStatus: string): void; /** * Event handler that receives a notification each time the value of a property of * {@link LightstreamerClient#connectionDetails} or {@link LightstreamerClient#connectionOptions} * is changed. * @param the - name of the changed property. *
Possible values are: * */ onPropertyChange?(the: string): void; /** * Event handler that receives a notification when the ClientListener instance * is added to a LightstreamerClient through * {@link LightstreamerClient#addListener}. * This is the first event to be fired on the listener. */ onListenStart?(): void; /** * Event handler that receives a notification when the ClientListener instance * is removed from a LightstreamerClient through * {@link LightstreamerClient#removeListener}. * This is the last event to be fired on the listener. */ onListenEnd?(): void; } /** * This is a dummy constructor not to be used in any case. */ export class ClientMessageListener { constructor(); /** * Event handler that is called by Lightstreamer when any notifications * of the processing outcome of the related message haven't been received * yet and can no longer be received. * Typically, this happens after the session has been closed. * In this case, the client has no way of knowing the processing outcome * and any outcome is possible. * @param originalMessage - the message to which this notification * is related. * @param sentOnNetwork - true if the message was probably sent on the * network, false otherwise. *
Event if the flag is true, it is not possible to infer whether the message * actually reached the Lightstreamer Server or not. */ onAbort?(originalMessage: string, sentOnNetwork: boolean): void; /** * Event handler that is called by Lightstreamer when the related message * has been processed by the Server but the processing has failed for any * reason. The level of completion of the processing by the Metadata Adapter * cannot be determined. * @param originalMessage - the message to which this notification * is related. */ onError?(originalMessage: string): void; /** * Event handler that is called by Lightstreamer to notify that the related * message has been discarded by the Server. This means that the message * has not reached the Metadata Adapter and the message next in the sequence * is considered enabled for processing. * @param originalMessage - the message to which this notification * is related. */ onDiscarded?(originalMessage: string): void; /** * Event handler that is called by Lightstreamer when the related message * has been processed by the Server but the expected processing outcome * could not be achieved for any reason. * @param originalMessage - the message to which this notification * is related. * @param code - the error code sent by the Server. It can be one * of the following: * * @param message - the description of the error sent by the Server. */ onDeny?(originalMessage: string, code: number, message: string): void; /** * Event handler that is called by Lightstreamer when the related message * has been processed by the Server with success. * @param originalMessage - the message to which this notification * is related. * @param response - the response from the Metadata Adapter. If not supplied (i.e. supplied as null), an empty message is received here. */ onProcessed?(originalMessage: string, response: string): void; } /** * Used by the client library to provide a value object to each call of the * {@link SubscriptionListener#onItemUpdate} event. */ export class ItemUpdate { constructor(); /** * Inquiry method that retrieves the name of the item to which this update * pertains. *
The name will be null if the related Subscription was initialized * using an "Item Group". * @returns the name of the item to which this update pertains. */ getItemName(): string; /** * Inquiry method that retrieves the position in the "Item List" or "Item Group" * of the item to which this update pertains. * @returns the 1-based position of the item to which this update pertains. */ getItemPos(): number; /** * Inquiry method that gets the value for a specified field, as received * from the Server with the current or previous update. * @param fieldNameOrPos - The field name or the 1-based position of the field * within the "Field List" or "Field Schema". * @returns The value of the specified field; it can be null in the following * cases: * */ getValue(fieldNameOrPos: string): string; /** * Inquiry method that gets the difference between the new value and the previous one * as a JSON Patch structure, provided that the Server has used the JSON Patch format * to send this difference, as part of the "delta delivery" mechanism. * This, in turn, requires that: * Note that the last condition can be enforced by leveraging the Server's * <jsonpatch_min_length> configuration flag, so that the availability of the * JSON Patch form would only depend on the Client and the Data Adapter. *
When the above conditions are not met, the method just returns null; in this * case, the new value can only be determined through {@link ItemUpdate#getValue}. For instance, * this will always be needed to get the first value received. * @param fieldNameOrPos - The field name or the 1-based position of the field * within the "Field List" or "Field Schema". * @returns A JSON Patch structure representing the difference between * the new value and the previous one, or null if the difference in JSON Patch format * is not available for any reason. */ getValueAsJSONPatchIfAvailable(fieldNameOrPos: string): any; /** * Inquiry method that asks whether the value for a field has changed after * the reception of the last update from the Server for an item. * If the Subscription mode is COMMAND then the change is meant as * relative to the same key. * @param fieldNameOrPos - The field name or the 1-based position of the field * within the field list or field schema. * @returns Unless the Subscription mode is COMMAND, the return value is true * in the following cases: * * If the Subscription mode is COMMAND, the return value is true in the * following cases: * * In all other cases, the return value is false. */ isValueChanged(fieldNameOrPos: string): boolean; /** * Inquiry method that asks whether the current update belongs to the * item snapshot (which carries the current item state at the time of * Subscription). Snapshot events are sent only if snapshot information * was requested for the items through {@link Subscription#setRequestedSnapshot} * and precede the real time events. * Snapshot information take different forms in different subscription * modes and can be spanned across zero, one or several update events. * In particular: * * Note that, in case of two-level behavior, snapshot-related updates * for both the first-level item (which is in COMMAND mode) and any * second-level items (which are in MERGE mode) are qualified with this flag. * @returns true if the current update event belongs to the item snapshot; * false otherwise. */ isSnapshot(): boolean; /** * Receives an iterator function and invokes it once per each field such that {@link ItemUpdate#isValueChanged} is true. *
Note that if the Subscription mode of the involved Subscription is * COMMAND, then changed fields are meant as relative to the previous update * for the same key. On such tables if a DELETE command is received, all the * fields, excluding the key field, will be iterated as changed, with null value. All of this * is also true on tables that have the two-level behavior enabled, but in * case of DELETE commands second-level fields will not be iterated. *
Note that the iterator is executed before this method returns. * @param iterator - Function instance that will be called once * per each field changed on the last update received from the server. */ forEachChangedField(iterator: ItemUpdateChangedFieldCallback): void; /** * Receives an iterator function and invokes it once per each field * in the Subscription. *
Note that the iterator is executed before this method returns. * @param iterator - Function instance that will be called once * per each field in the Subscription. */ forEachField(iterator: ItemUpdateChangedFieldCallback): void; } /** * Callback for {@link ItemUpdate#forEachChangedField} and {@link ItemUpdate#forEachField} * @param fieldName - of the involved changed field. If the related Subscription was * initialized using a "Field Schema" it will be null. * @param fieldPos - 1-based position of the field within * the "Field List" or "Field Schema". * @param value - the value for the field. See {@link ItemUpdate#getValue} for details. */ declare type ItemUpdateChangedFieldCallback = (fieldName: string, fieldPos: number, value: string) => void; /** * This is a dummy constructor not to be used in any case. */ export class SubscriptionListener { constructor(); /** * Event handler that is called by Lightstreamer each time an update * pertaining to an item in the Subscription has been received from the * Server. * @param updateInfo - a value object containing the * updated values for all the fields, together with meta-information about * the update itself and some helper methods that can be used to iterate through * all or new values. */ onItemUpdate?(updateInfo: ItemUpdate): void; /** * Event handler that is called by Lightstreamer to notify that, due to * internal resource limitations, Lightstreamer Server dropped one or more * updates for an item in the Subscription. Such notifications are sent only * if the items are delivered in an unfiltered mode; this occurs if the * subscription mode is: * * By implementing this method it is possible to perform recovery actions. * @param itemName - name of the involved item. If the Subscription * was initialized using an "Item Group" then a null value is supplied. * @param itemPos - 1-based position of the item within the "Item List" * or "Item Group". * @param lostUpdates - The number of consecutive updates dropped * for the item. */ onItemLostUpdates?(itemName: string, itemPos: number, lostUpdates: number): void; /** * Event handler that is called by Lightstreamer to notify that, due to * internal resource limitations, Lightstreamer Server dropped one or more * updates for an item that was subscribed to as a second-level subscription. * Such notifications are sent only if the Subscription was configured in * unfiltered mode (second-level items are always in "MERGE" mode and * inherit the frequency configuration from the first-level Subscription). *
By implementing this method it is possible to perform recovery actions. * @param lostUpdates - The number of consecutive updates dropped * for the item. * @param key - The value of the key that identifies the * second-level item. */ onCommandSecondLevelItemLostUpdates?(lostUpdates: number, key: string): void; /** * Event handler that is called by Lightstreamer to notify that all * snapshot events for an item in the Subscription have been received, * so that real time events are now going to be received. The received * snapshot could be empty. * Such notifications are sent only if the items are delivered in * DISTINCT or COMMAND subscription mode and snapshot information was * indeed requested for the items. * By implementing this method it is possible to perform actions which * require that all the initial values have been received. *
Note that, if the involved Subscription has a two-level behavior enabled, the notification * refers to the first-level item (which is in COMMAND mode). * Snapshot-related updates for the second-level items (which are in * MERGE mode) can be received both before and after this notification. * @param itemName - name of the involved item. If the Subscription * was initialized using an "Item Group" then a null value is supplied. * @param itemPos - 1-based position of the item within the "Item List" * or "Item Group". */ onEndOfSnapshot?(itemName: string, itemPos: number): void; /** * Event handler that is called by Lightstreamer each time a request * to clear the snapshot pertaining to an item in the Subscription has been * received from the Server. * More precisely, this kind of request can occur in two cases: * *
Note that, if the involved Subscription has a two-level behavior enabled, * the notification refers to the first-level item (which is in COMMAND mode). * This kind of notification is not possible for second-level items (which are in * MERGE mode). *
This event can be sent by the Lightstreamer Server since version 6.0 * @param itemName - name of the involved item. If the Subscription * was initialized using an "Item Group" then a null value is supplied. * @param itemPos - 1-based position of the item within the "Item List" * or "Item Group". */ onClearSnapshot?(itemName: string, itemPos: number): void; /** * Event handler that is called by Lightstreamer to notify that a Subscription * has been successfully subscribed to through the Server. * This can happen multiple times in the life of a Subscription instance, * in case the Subscription is performed multiple times through * {@link LightstreamerClient#unsubscribe} and {@link LightstreamerClient#subscribe}. * This can also happen multiple times in case of automatic recovery after a connection * restart. *
This notification is always issued before the other ones related * to the same subscription. It invalidates all data that has been received * previously. *
Note that two consecutive calls to this method are not possible, as before * a second onSubscription event is fired an onUnsubscription event is eventually * fired. *
If the involved Subscription has a two-level behavior enabled, * second-level subscriptions are not notified. */ onSubscription?(): void; /** * Event handler that is called by Lightstreamer to notify that a Subscription * has been successfully unsubscribed from. * This can happen multiple times in the life of a Subscription instance, * in case the Subscription is performed multiple times through * {@link LightstreamerClient#unsubscribe} and {@link LightstreamerClient#subscribe}. * This can also happen multiple times in case of automatic recovery after a connection * restart. * *
After this notification no more events can be recieved until a new * {@link SubscriptionListener#onSubscription} event. *
Note that two consecutive calls to this method are not possible, as before * a second onUnsubscription event is fired an onSubscription event is eventually * fired. *
If the involved Subscription has a two-level behavior enabled, * second-level unsubscriptions are not notified. */ onUnsubscription?(): void; /** * Event handler that is called when the Server notifies an error on a Subscription. By implementing this method it * is possible to perform recovery actions.
* Note that, in order to perform a new subscription attempt, {@link LightstreamerClient#unsubscribe} * and {@link LightstreamerClient#subscribe} should be issued again, even if no change to the Subscription * attributes has been applied. * @param code - The error code sent by the Server. It can be one of the following: * * @param message - The description of the error sent by the Server; * it can be null. */ onSubscriptionError?(code: number, message: string): void; /** * Event handler that is called when the Server notifies an error on a second-level subscription.
* By implementing this method it is possible to perform recovery actions. * @param code - The error code sent by the Server. It can be one of the following: * * @param message - The description of the error sent by the Server; it can be null. * @param key - The value of the key that identifies the second-level item. */ onCommandSecondLevelSubscriptionError?(code: number, message: string, key: string): void; /** * Event handler that receives a notification when the SubscriptionListener instance * is added to a Subscription through * {@link Subscription#addListener}. * This is the first event to be fired on the listener. */ onListenStart?(): void; /** * Event handler that receives a notification when the SubscriptionListener instance * is removed from a Subscription through * {@link Subscription#removeListener}. * This is the last event to be fired on the listener. */ onListenEnd?(): void; /** * Event handler that is called by Lightstreamer to notify the client with the real maximum update frequency of the Subscription. * It is called immediately after the Subscription is established and in response to a requested change * (see {@link Subscription#setRequestedMaxFrequency}). * Since the frequency limit is applied on an item basis and a Subscription can involve multiple items, * this is actually the maximum frequency among all items. For Subscriptions with two-level behavior * (see {@link Subscription#setCommandSecondLevelFields} and {@link Subscription#setCommandSecondLevelFieldSchema}) * , the reported frequency limit applies to both first-level and second-level items.
* The value may differ from the requested one because of restrictions operated on the server side, * but also because of number rounding.
* Note that a maximum update frequency (that is, a non-unlimited one) may be applied by the Server * even when the subscription mode is RAW or the Subscription was done with unfiltered dispatching. * @param frequency - A decimal number, representing the maximum frequency applied by the Server * (expressed in updates per second), or the string "unlimited". A null value is possible in rare cases, * when the frequency can no longer be determined. */ onRealMaxFrequency?(frequency: string): void; } /** * Used by LightstreamerClient to provide an extra connection properties data object. */ export class ConnectionOptions { constructor(); /** * 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. *
NOTE that this setting only applies to the "HTTP-STREAMING" case (i.e. not to WebSockets). * *

Default value: A length decided by the library, to ensure * the best performance. It can be of a few MB or much higher, depending on the environment.

* *

Lifecycle: The content length should be set before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next streaming connection (either a bind * or a brand new session).

* *

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

* @param contentLength - The length to be used by the Server for the * response body on a HTTP stream connection. */ setContentLength(contentLength: number): void; /** * 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 */ getContentLength(): number; /** * 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 before calling the * {@link 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 {@link ClientListener#onPropertyChange} with argument "idleTimeout" on any * {@link ClientListener} * .

* @param idleTimeout - The time (in milliseconds) the Server is * allowed to wait for data to send upon polling requests. */ setIdleTimeout(idleTimeout: number): void; /** * 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. * @returns The time (in milliseconds) the Server is allowed to wait for * data to send upon polling requests. */ getIdleTimeout(): number; /** * 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. * If 0 is specified, the interval will be decided by the Server. * *

Default value: 0 (meaning that the Server * will send keepalive packets based on its own configuration).

* *

Lifecycle: The keepalive interval should be set before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next streaming connection (either a bind * or a brand new session). *
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 {@link ClientListener#onPropertyChange} with argument "keepaliveInterval" on any * {@link ClientListener} * .

* @param keepaliveInterval - The time, expressed in milliseconds, * between two keepalive packets, or 0. */ setKeepaliveInterval(keepaliveInterval: number): void; /** * 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. * If the returned value is 0, it means that the interval is to be decided * by the Server upon the next connection. * @returns The time, expressed in milliseconds, between two keepalive * packets sent by the Server, or 0. */ getKeepaliveInterval(): number; /** * 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: Bandwidth Control is * an optional feature, available depending on Edition and License Type. * To know what features are enabled by your license, please see the License tab of the * Monitoring Dashboard (by default, available at /dashboard).

* *

Default value: "unlimited".

* *

Lifecycle: The bandwidth limit can be set and changed at any time. If a connection is currently active, the bandwidth * limit for the connection is changed on the fly. Remember that the Server may apply a different limit. * *

Notification: A change to this setting will be notified through a call to * {@link ClientListener#onPropertyChange} with argument "requestedMaxBandwidth" on any * {@link ClientListener} * . *
* Moreover, upon any change or attempt to change the limit, the Server will notify the client * and such notification will be received through a call to * {@link ClientListener#onPropertyChange} with argument "realMaxBandwidth" on any * {@link ClientListener} * .

* @param maxBandwidth - A decimal number, which represents 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 entirely decided on the Server side (the check is case insensitive). */ setRequestedMaxBandwidth(maxBandwidth: number): void; /** * Inquiry method that gets the maximum bandwidth that can be consumed for the data coming from * Lightstreamer Server, as requested for this session. * The maximum bandwidth limit really applied by the Server on the session is provided by * {@link ConnectionOptions#getRealMaxBandwidth} * @returns A decimal number, which represents the maximum bandwidth requested for the streaming * or polling connection expressed in kbps (kilobits/sec), or the string "unlimited". */ getRequestedMaxBandwidth(): number | string; /** * Inquiry method that gets the maximum bandwidth that can be consumed for the data coming from * Lightstreamer Server. This is the actual maximum bandwidth, in contrast with the requested * maximum bandwidth, returned by {@link ConnectionOptions#getRequestedMaxBandwidth}.
* The value may differ from the requested one because of restrictions operated on the server side, * or because bandwidth management is not supported (in this case it is always "unlimited"), * but also because of number rounding. * *

Lifecycle:IIf a connection to Lightstreamer Server is not currently active, null is returned; * soon after the connection is established, the value will become available.

* *

Notification: A change to this setting will be notified through a call to * {@link ClientListener#onPropertyChange} with argument "realMaxBandwidth" on any * ClientListener listening to the related LightstreamerClient. *

* @returns A decimal number, which represents the maximum bandwidth applied by the Server for the * streaming or polling connection expressed in kbps (kilobits/sec), or the string "unlimited", or null. */ getRealMaxBandwidth(): number | string; /** * 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 {@link 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 before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next polling 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 {@link ClientListener#onPropertyChange} with argument "pollingInterval" on any * {@link ClientListener} *

* @param pollingInterval - 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. */ setPollingInterval(pollingInterval: number): void; /** * 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. * @returns The time (in milliseconds) between subsequent polling requests. */ getPollingInterval(): number; /** * Setter method that sets the time the client, after entering "STALLED" status, * is allowed to keep waiting for a keepalive packet or any data on a stream connection, * before disconnecting and trying to reconnect to the Server. * The new connection may be either the opening of a new session or an attempt to recovery * the current session, depending on the kind of interruption. * *

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 {@link ClientListener#onPropertyChange} with argument "reconnectTimeout" on any * {@link ClientListener} * .

* @param reconnectTimeout - The idle time (in milliseconds) * allowed in "STALLED" status before trying to reconnect to the * Server. */ setReconnectTimeout(reconnectTimeout: number): void; /** * Inquiry method that gets the time the client, after entering "STALLED" status, * is allowed to keep waiting for a keepalive packet or any data on a stream connection, * before disconnecting and trying to reconnect to the Server. * @returns The idle time (in milliseconds) admitted in "STALLED" * status before trying to reconnect to the Server. */ getReconnectTimeout(): number; /** * 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 {@link ClientListener#onPropertyChange} with argument "stalledTimeout" on any * {@link ClientListener} * .

* @param stalledTimeout - The idle time (in milliseconds) * allowed before entering the "STALLED" status. */ setStalledTimeout(stalledTimeout: number): void; /** * 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. * @returns The idle time (in milliseconds) admitted before entering the * "STALLED" status. */ getStalledTimeout(): number; /** * Setter method that sets *
    *
  1. the minimum time to wait before trying a new connection * to the Server in case the previous one failed for any reason; and
    2. *
  2. the maximum time to wait for a response to a request * before dropping the connection and trying with a different approach.
    3. *
* *

* Enforcing a delay between reconnections prevents strict loops of connection attempts when these attempts * always fail immediately because of some persisting issue. * This applies both to reconnections aimed at opening a new session and to reconnections * aimed at attempting a recovery of the current session.
* Note that the delay is calculated from the moment the effort to create a connection * is made, not from the moment the failure is detected. * As a consequence, when a working connection is interrupted, this timeout is usually * already consumed and the new attempt can be immediate (except that * {@link ConnectionOptions#setFirstRetryMaxDelay} will apply in this case). * As another consequence, when a connection attempt gets no answer and times out, * the new attempt will be immediate. * *

* As a timeout on unresponsive connections, it is applied in these cases: *

* *

* This setting imposes only a minimum delay. In order to avoid network congestion, the library may use a longer delay if the issue preventing the * establishment of a session persists. * *

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 {@link ClientListener#onPropertyChange} with argument "retryDelay" on any * {@link ClientListener} * .

* @param retryDelay - The time (in milliseconds) * to wait before trying a new connection. */ setRetryDelay(retryDelay: number): void; /** * Inquiry method that gets the minimum time to wait before trying a new connection * to the Server in case the previous one failed for any reason, which is also the maximum time to wait for a response to a request * before dropping the connection and trying with a different approach. * Note that the delay is calculated from the moment the effort to create a connection * is made, not from the moment the failure is detected or the connection timeout expires. * @returns The time (in milliseconds) to wait before trying a new connection. */ getRetryDelay(): number; /** * Setter method that sets the maximum time to wait before trying a new connection to the Server * in case the previous one is unexpectedly closed while correctly working. * The new connection may be either the opening of a new session or an attempt to recovery * the current session, depending on the kind of interruption. *
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, only the setting of {@link ConnectionOptions#setRetryDelay} will be 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 {@link ClientListener#onPropertyChange} with argument "firstRetryMaxDelay" on any * {@link ClientListener} * .

* @param firstRetryMaxDelay - The max time (in milliseconds) * to wait before trying a new connection. */ setFirstRetryMaxDelay(firstRetryMaxDelay: number): void; /** * Inquiry method that gets the maximum time to wait before trying a new connection to the Server * in case the previous one is unexpectedly closed while correctly working. * @returns The max time (in milliseconds) * to wait before trying a new connection. */ getFirstRetryMaxDelay(): number; /** * 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: false.

* *

Lifecycle:This setting should be performed before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next streaming connection (either a bind * or a brand new session).

* *

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

* @param slowingEnabled - true or false, to enable or disable * the heuristic algorithm that lowers the item update frequency. */ setSlowingEnabled(slowingEnabled: boolean): void; /** * Inquiry method that checks if the slowing algorithm is enabled or not. * @returns Whether the slowing algorithm is enabled or not. */ isSlowingEnabled(): boolean; /** * 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 {@link ClientListener#onPropertyChange} with argument "forcedTransport" on any * {@link ClientListener} * .

* @param forcedTransport - can be one of the following: *
* */ setForcedTransport(forcedTransport: string): void; /** * Inquiry method that gets the value of the forced transport (if any). * @returns The forced transport or null */ getForcedTransport(): string; /** * 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 {@link 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 * an optional feature, available depending on Edition and License Type. * To know what features are enabled by your license, please see the License tab of the * Monitoring Dashboard (by default, available at /dashboard).

* *

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 {@link ClientListener#onPropertyChange} with argument "serverInstanceAddressIgnored" on any * {@link ClientListener} * .

* @param serverInstanceAddressIgnored - true or false, to ignore * or not the server instance address sent by the server. */ setServerInstanceAddressIgnored(serverInstanceAddressIgnored: boolean): void; /** * Inquiry method that checks if the client is going to ignore the server * instance address that will possibly be sent by the server. * @returns Whether or not to ignore the server instance address sent by the * server. */ isServerInstanceAddressIgnored(): boolean; /** * 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. *
This holds only for cookies returned by the Server (possibly affinity cookies * inserted by a Load Balancer standing in between). If other cookies received * by the application also pertain to Lightstreamer Server host, they must be * manually set through the static {@link LightstreamerClient.addCookies} method. * Likewise, cookies set by Lightstreamer Server and also pertaining to other hosts * accessed by the application must be manually extracted through the static * {@link LightstreamerClient.getCookies} method and handled properly. *
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 setting should be performed before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next HTTP request or WebSocket establishment.

* *

Notification: A change to this setting will be notified through a * call to {@link ClientListener#onPropertyChange} with argument "cookieHandlingRequired" on any * {@link ClientListener}.

* @param cookieHandlingRequired - true/false to enable/disable the * cookies-are-required policy. */ setCookieHandlingRequired(cookieHandlingRequired: boolean): void; /** * 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. * @returns true/false if the cookies-are-required policy is enabled or not. */ isCookieHandlingRequired(): boolean; /** * Setter method that enables/disables the reverse-heartbeat mechanism * 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 ensure that there is at most * the specified interval between a control request and the following one, * by sending empty control requests (the "reverse heartbeats") if necessary. *
This can serve various purposes: * *

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

* *

Lifecycle: This setting should be performed before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the setting will be obeyed immediately, unless a higher heartbeat * frequency was notified to the Server for the current connection. The setting * will always be obeyed upon the next connection (either a bind or a brand new session).

* *

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

* @param reverseHeartbeatInterval - the interval, expressed in milliseconds, * between subsequent reverse-heartbeats, or 0. */ setReverseHeartbeatInterval(reverseHeartbeatInterval: number): void; /** * Inquiry method that gets the reverse-heartbeat interval expressed in * milliseconds. * A 0 value is possible, meaning that the mechanism is disabled. * @returns the reverse-heartbeat interval, or 0. */ getReverseHeartbeatInterval(): number; /** * Setter method that enables/disables the setting of extra HTTP headers to all the * request performed to the Lightstreamer server by the client. *
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. *
For instance, you cannot use this method to specify custom cookies to be sent to * Lightstreamer Server. Use the static {@link LightstreamerClient.addCookies} instead * (and {@link LightstreamerClient.getCookies} for inquiries).
* 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 setting should be performed before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next HTTP request or WebSocket establishment.

* *

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

* @param headersObj - a JSON object containing header-name header-value pairs. * Null can be specified to avoid extra headers to be sent. */ setHttpExtraHeaders(headersObj: any): void; /** * Inquiry method that gets the JSON object containing the extra headers * to be sent to the server. * @returns the JSON object containing the extra headers * to be sent */ getHttpExtraHeaders(): any; /** * Setter method that enables/disables a restriction on the forwarding of the extra http headers * specified through {@link 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 false, the specified extra * headers will be sent to the server on every request * . * *

Default value: false.

* *

Lifecycle:This setting should be performed before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next HTTP request or WebSocket establishment.

* *

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

* @param httpExtraHeadersOnSessionCreationOnly - true/false to enable/disable the * restriction on extra headers forwarding. */ setHttpExtraHeadersOnSessionCreationOnly(httpExtraHeadersOnSessionCreationOnly: boolean): void; /** * Inquiry method that checks if the restriction on the forwarding of the * configured extra http headers applies or not. * @returns true/false if the restriction applies or not. */ isHttpExtraHeadersOnSessionCreationOnly(): boolean; /** * Setter method that sets the maximum time allowed for attempts to recover * the current session upon an interruption, after which a new session will be created. * If the given value (expressed in milliseconds) equals 0, then any attempt * to recover the current session will be prevented in the first place. *
In fact, in an attempt to recover the current session, the client will * periodically try to access the Server at the address related with the current * session. In some cases, this timeout, by enforcing a fresh connection attempt, * may prevent an infinite sequence of unsuccessful attempts to access the Server. *
Note that, when the Server is reached, the recovery may fail due to a * Server side timeout on the retention of the session and the updates sent. * In that case, a new session will be created anyway. * A setting smaller than the Server timeouts may prevent such useless failures, * but, if too small, it may also prevent successful recovery in some cases.

* *

Default value: 15000 (15 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 {@link ClientListener#onPropertyChange} with argument "sessionRecoveryTimeout" on any * {@link ClientListener} * .

* @param sessionRecoveryTimeout - the maximum time allowed * for recovery attempts, expressed in milliseconds, including 0. */ setSessionRecoveryTimeout(sessionRecoveryTimeout: number): void; /** * Inquiry method that gets the maximum time allowed for attempts to recover * the current session upon an interruption, after which a new session will be created. * A 0 value also means that any attempt to recover the current session is prevented * in the first place. * @returns the maximum time allowed for recovery attempts, possibly 0. */ getSessionRecoveryTimeout(): number; } /** * Used by LightstreamerClient to provide a basic connection properties data object. */ export class ConnectionDetails { constructor(); /** * Setter method that sets the address of Lightstreamer Server. *
Note that the addresses specified must always have the http: or https: scheme. * In case WebSockets are used, the specified scheme is * internally converted to match the related WebSocket protocol * (i.e. http becomes ws while https becomes wss). * *

Edition Note: HTTPS is an optional * feature, available depending on Edition and License Type. * To know what features are enabled by your license, please see the License tab of the * Monitoring Dashboard (by default, available at /dashboard).

* * *

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. *
This setting can also be specified in the {@link LightstreamerClient} * constructor.

* *

Notification: A change to this setting will be notified through a * call to {@link ClientListener#onPropertyChange} with argument "serverAddress" on any * {@link ClientListener} * .

* @param serverAddress - The full address of Lightstreamer Server. * A null value can also be used, to restore the default value. * An IPv4 or IPv6 can also be used in place of a hostname, if compatible with * the environment in use (see the notes in the summary of this documentation). * Some examples of valid values include: *
http://push.mycompany.com *
http://push.mycompany.com:8080 *
http://79.125.7.252 *
http://[2001:0db8:85a3:0000:0000:8a2e:0370:7334] *
http://[2001:0db8:85a3::8a2e:0370:7334]:8080 */ setServerAddress(serverAddress: string): void; /** * Inquiry method that gets the configured address of Lightstreamer Server. * @returns the configured address of Lightstreamer Server. */ getServerAddress(): string; /** * Setter method that sets the name of the Adapter Set mounted on * Lightstreamer Server to be used to handle all requests in the session. *
An Adapter Set defines the Metadata Adapter and one or several * Data Adapters. It is configured on the server side through an * "adapters.xml" file; the name is configured through the "id" attribute * in the <adapters_conf> element. * *

Default value: The default Adapter Set, configured as * "DEFAULT" on the Server.

* *

Lifecycle: The Adapter Set name should be set on the * {@link LightstreamerClient#connectionDetails} object before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next time a new session is * requested to the server. *
This setting can also be specified in the {@link LightstreamerClient} * constructor.

* *

Notification: A change to this setting will be notified through a * call to {@link ClientListener#onPropertyChange} with argument "adapterSet" on any * {@link ClientListener} * .

* @param adapterSet - The name of the Adapter Set to be used. A null value * is equivalent to the "DEFAULT" name. */ setAdapterSet(adapterSet: string): void; /** * Inquiry method that gets the name of the Adapter Set (which defines * the Metadata Adapter and one or several Data Adapters) mounted on * Lightstreamer Server that supply all the items used in this application. * @returns the name of the Adapter Set; returns null if no name * has been configured, so that the "DEFAULT" Adapter Set is used. */ getAdapterSet(): string; /** * Setter method that sets the username to be used for the authentication * on Lightstreamer Server when initiating the push session. * The Metadata Adapter is responsible for checking the credentials * (username and password). * *

Default value: If no username is supplied, no user * information will be sent at session initiation. The Metadata Adapter, * however, may still allow the session.

* *

Lifecycle: The username should be set on the * {@link LightstreamerClient#connectionDetails} object before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next time a new session is * requested to the server.

* *

Notification: A change to this setting will be notified through a * call to {@link ClientListener#onPropertyChange} with argument "user" on any * {@link ClientListener} * .

* @param user - The username to be used for the authentication * on Lightstreamer Server. The username can be null. */ setUser(user: string): void; /** * Inquiry method that gets the username to be used for the authentication * on Lightstreamer Server when initiating the push session. * @returns the username to be used for the authentication * on Lightstreamer Server; returns null if no user name * has been configured. */ getUser(): string; /** * Setter method that sets the password to be used for the authentication * on Lightstreamer Server when initiating the push session. * The Metadata Adapter is responsible for checking the credentials * (username and password). * *

Default value: If no password is supplied, no password * information will be sent at session initiation. The Metadata Adapter, * however, may still allow the session.

* *

Lifecycle: The username should be set on the * {@link LightstreamerClient#connectionDetails} object before calling the * {@link LightstreamerClient#connect} method. However, the value can be changed * at any time: the supplied value will be used for the next time a new session is * requested to the server. *
NOTE: The password string will be stored as a JavaScript * variable. * That is necessary in order to allow automatic reconnection/reauthentication * for fail-over. For maximum security, avoid using an actual private * password to authenticate on Lightstreamer Server; rather use * a session-id originated by your web/application server, that can be * checked by your Metadata Adapter.

* *

Notification: A change to this setting will be notified through a * call to {@link ClientListener#onPropertyChange} with argument "password" on any * {@link ClientListener} * .

* @param password - The password to be used for the authentication * on Lightstreamer Server. The password can be null. */ setPassword(password: string): void; /** * Inquiry method that gets the server address to be used to issue all requests * related to the current session. In fact, when a Server cluster is in * place, the Server address specified through * {@link 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. * When this is the case, this address is returned by the method; * otherwise, null is returned. *
Note that the addresses will always have the http: or https: scheme. * In case WebSockets are used, the specified scheme is * internally converted to match the related WebSocket protocol * (i.e. http becomes ws while https becomes wss). * *

Edition Note: Server Clustering is * an optional feature, available depending on Edition and License Type. * To know what features are enabled by your license, please see the License tab of the * Monitoring Dashboard (by default, available at /dashboard).

* *

Lifecycle: If a session is not currently active, null is returned; * soon after a session is established, the value may become available.

* *

Notification: A change to this setting will be notified through a * call to {@link ClientListener#onPropertyChange} with argument "serverInstanceAddress" on any * {@link ClientListener} * .

* @returns address used to issue all requests related to the current * session, or null. */ getServerInstanceAddress(): string; /** * 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 * an optional feature, available depending on Edition and License Type. * To know what features are enabled by your license, please see the License tab of the * Monitoring Dashboard (by default, available at /dashboard).

* *

Lifecycle: If a session is not currently active, null is returned; * soon after a session is established, the value will become available.

* *

Notification: A change to this setting will be notified through a * call to {@link ClientListener#onPropertyChange} with argument "serverSocketName" on any * {@link ClientListener} * .

* @returns name configured for the Server instance which is managing the * current session, or null. */ getServerSocketName(): string; /** * Inquiry method that gets the ID associated by the server * to this client session. * *

Lifecycle: If a session is not currently active, null is returned; * soon after a session is established, the value will become available.

* *

Notification: A change to this setting will be notified through a * call to {@link ClientListener#onPropertyChange} with argument "sessionId" on any * {@link ClientListener} * .

* @returns ID assigned by the Server to this client session, or null. */ getSessionId(): string; /** * Inquiry method that gets the IP address of this client as seen by the Server which is serving * the current session as the client remote address (note that it may not correspond to the client host; * for instance it may refer to an intermediate proxy). If, upon a new session, this address changes, * it may be a hint that the intermediary network nodes handling the connection have changed, hence the network * capabilities may be different. The library uses this information to optimize the connection.
* Note that in case of polling or in case rebind requests are needed, subsequent requests related to the same * session may, in principle, expose a different IP address to the Server; these changes would not be reported. * *

Lifecycle: If a session is not currently active, null is returned; * soon after a session is established, the value may become available.

* *

Notification: A change to this setting will be notified through a call to * {@link ClientListener#onPropertyChange} with argument "clientIp" on any * ClientListener listening to the related LightstreamerClient.

* @returns A canonical representation of an IP address (it can be either IPv4 or IPv6), or null. */ getClientIp(): string; } /** * Creates an object to be configured to connect to a Lightstreamer server * and to handle all the communications with it. * It is possible to instantiate as many LightstreamerClient as needed. * Each LightstreamerClient is the entry point to connect to a Lightstreamer server, * subscribe to as many items as needed and to send messages. * @param [serverAddress] - the address of the Lightstreamer Server to * which this LightstreamerClient will connect to. It is possible not to specify * it at all or to specify it later. See {@link ConnectionDetails#setServerAddress} * for details. * @param [adapterSet] - the name of the Adapter Set mounted on Lightstreamer Server * to be used to handle all requests in the Session associated with this LightstreamerClient. * It is possible not to specify it at all or to specify it later. See * {@link ConnectionDetails#setAdapterSet} for details. */ export class LightstreamerClient { constructor(serverAddress?: string, adapterSet?: string); /** * Data object that contains options and policies for the connection to * the server. This instance is set up by the LightstreamerClient object at * its own creation. *
Properties of this object can be overwritten by values received from a * Lightstreamer Server. Such changes will be notified through a * {@link ClientListener#onPropertyChange} event on listeners of this instance. */ connectionOptions: ConnectionOptions; /** * Data object that contains the details needed to open a connection to * a Lightstreamer Server. This instance is set up by the LightstreamerClient object at * its own creation. *
Properties of this object can be overwritten by values received from a * Lightstreamer Server. Such changes will be notified through a * {@link ClientListener#onPropertyChange} event on listeners of this instance. */ connectionDetails: ConnectionDetails; /** * Static method that can be used to share cookies between connections to the Server * (performed by this library) and connections to other sites that are performed * by the application. With this method, cookies received by the application * can be added (or replaced if already present) to the cookie set used by the * library to access the Server. Obviously, only cookies whose domain is compatible * with the Server domain will be used internally. * *

Lifecycle:This method can be called at any time; * it will affect the internal cookie set immediately and the sending of cookies * on future requests.

* @param uri - String representation of the URI from which the supplied * cookies were received. * @param cookies - An array of String representations of the various * cookies to be added. Each cookie should be represented in the text format * provided for the Set-Cookie HTTP header by RFC 6265. */ static addCookies(uri: string, cookies: String[]): void; /** * Static inquiry method that can be used to share cookies between connections to the Server * (performed by this library) and connections to other sites that are performed * by the application. With this method, cookies received from the Server can be * extracted for sending through other connections, according with the URI to be accessed. * @param uri - String representation of the URI to which the cookies should * be sent, or null. * @returns An array of String representations of the various cookies that can * be sent in a HTTP request for the specified URI. If a null URI was supplied, * the export of all available cookies, including expired ones, will be returned. * Each cookie is represented in the text format provided for the Set-Cookie HTTP header * by RFC 6265. */ static getCookies(uri: string): String[]; /** * Static method that permits to configure the logging system used by the library. * The logging system must respect the {@link LoggerProvider} interface. A custom * class can be used to wrap any third-party JavaScript logging system. *
A ready-made LoggerProvider implementation is available within the * library in the form of the {@link SimpleLoggerProvider} class. *
If no logging system is specified, all the generated log is discarded. *
The following categories are available to be consumed: * * @param provider - A LoggerProvider instance that will be used * to generate log messages by the library classes. */ static setLoggerProvider(provider: LoggerProvider): void; /** * A constant string representing the name of the library. */ static LIB_NAME: string; /** * A constant string representing the version of the library. */ static LIB_VERSION: string; /** * Operation method that requests to open a Session against the configured * Lightstreamer Server. *
When connect() is called, unless a single transport was forced through * {@link ConnectionOptions#setForcedTransport}, * the so called "Stream-Sense" mechanism is started: if the client does not * receive any answer for some seconds from the streaming connection, then it * will automatically open a polling connection. *
A polling connection may also be opened if the environment is not suitable * for a streaming connection. *
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: * Note that the request to connect is accomplished by the client * asynchronously; this means that an invocation to {@link LightstreamerClient#getStatus} * right after connect() might not reflect the change yet. Also if a * CPU consuming task is performed right after the call the connection will * be delayed. *
When the request to connect is finally being executed, if the current status * of the client is not DISCONNECTED, then nothing will be done.

*/ connect(): void; /** * Operation method that requests to close the Session opened against the * configured Lightstreamer Server (if any). *
When disconnect() is called, the "Stream-Sense" mechanism is stopped. *
Note that active {@link Subscription} instances, associated with this * LightstreamerClient instance, are preserved to be re-subscribed to on future * Sessions. * *

Lifecycle: * Note that the request to disconnect is accomplished by the client * asynchronously; this means that an invocation to {@link LightstreamerClient#getStatus} * right after disconnect() might not reflect the change yet. Also if a * CPU consuming task is performed right after the call the disconnection will * be delayed. *
When the request to disconnect is finally being executed, if the status of the client is * "DISCONNECTED", then nothing will be done.

*/ disconnect(): void; /** * Inquiry method that gets the current client status and transport * (when applicable). * @returns The current client status. It can be one of the following * values: * */ getStatus(): string; /** * Operation method that sends a message to the Server. The message is * interpreted and handled by the Metadata Adapter associated to the * current Session. This operation supports in-order guaranteed message * delivery with automatic batching. In other words, messages are * guaranteed to arrive exactly once and respecting the original order, * whatever is the underlying transport (HTTP or WebSockets). Furthermore, * high frequency messages are automatically batched, if necessary, * to reduce network round trips. *
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 * . *
If a message, for any reason, doesn't reach the Server (this is possible with the HTTP transport), * it will be resent; however, this may cause the subsequent messages to be delayed. * For this reason, each message can specify a "delayTimeout", which is the longest time the message, after * reaching the Server, can be kept waiting if one of more preceding messages haven't been received yet. * If the "delayTimeout" expires, these preceding messages will be discarded; any discarded message * will be notified to the listener through {@link ClientMessageListener#onDiscarded}. * Note that, because of the parallel transport of the messages, if a zero or very low timeout is * set for a message and the previous message was sent immediately before, it is possible that the * latter gets discarded even if no communication issues occur. * The Server may also enforce its own timeout on missing messages, to prevent keeping the subsequent * messages for long time. *
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. 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, in order to ensure that the listener eventually gets a notification. *
Moreover, if "UNORDERED_MESSAGES" is used and no listener is supplied, * a "fire and forget" scenario is assumed. In this case, no checks on * missing, duplicated or overtaken messages are performed at all, so as to * optimize the processing and allow the highest possible throughput. * *

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. * If the special enqueueWhileDisconnected flag is specified it is possible to * call the method at any time and the client will take care of sending the * message as soon as a connection is available, otherwise, if the current status * is "DISCONNECTED*", the message will be abandoned and the * {@link ClientMessageListener#onAbort} event will be fired. *
Note that, in any case, as soon as the status switches again to * "DISCONNECTED*", any message still pending is aborted, including messages * that were queued with the enqueueWhileDisconnected flag set to true. *
Also note that forwarding of the message to the server is made * asynchronously; this means that if a CPU consuming task is * performed right after the call, the message will be delayed. Hence, * if a message is sent while the connection is active, it could be aborted * because of a subsequent disconnection. In the same way a message sent * while the connection is not active might be sent because of a subsequent * connection.

* @param msg - a text message, whose interpretation is entirely * demanded to the Metadata Adapter associated to the current connection. * @param [sequence = "UNORDERED_MESSAGES"] - 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, "UNORDERED_MESSAGES" is used * as the sequence name. * @param [delayTimeout] - a timeout, expressed in milliseconds. * If higher than the Server configured timeout on missing messages, * the latter will be used instead.
* The parameter is optional; if not supplied, the Server configured timeout on missing * messages will be applied. *
This timeout is ignored for the special "UNORDERED_MESSAGES" sequence, * although a server-side timeout on missing messages still applies. * @param [listener] - an * object suitable for receiving notifications about the processing outcome. *
The parameter is optional; if not supplied, no notification will be * available. * @param [enqueueWhileDisconnected = false] - if this flag is set to true, and * the client is in a disconnected status when the provided message * is handled, then the message is not aborted right away but is queued waiting * for a new session. Note that the message can still be aborted later when a new * session is established. */ sendMessage(msg: string, sequence?: string, delayTimeout?: number, listener?: ClientMessageListener, enqueueWhileDisconnected?: boolean): void; /** * Inquiry method that returns an array containing all the {@link Subscription} * instances that are currently "active" on this LightstreamerClient. *
Internal second-level Subscription are not included. * @returns An array, containing all the {@link Subscription} currently * "active" on this LightstreamerClient. *
The array can be empty. */ getSubscriptions(): String[]; /** * Operation method that adds a {@link Subscription} to the list of "active" * Subscriptions. * The Subscription cannot already be in the "active" state. *
Active subscriptions are subscribed to through the server as soon as possible * (i.e. as soon as there is a session available). Active Subscription are * automatically persisted across different sessions as long as a related * unsubscribe call is not issued. * *

Lifecycle: Subscriptions can be given to the LightstreamerClient at * any time. Once done the Subscription immediately enters the "active" state. *
Once "active", a {@link Subscription} instance cannot be provided again * to a LightstreamerClient unless it is first removed from the "active" state * through a call to {@link LightstreamerClient#unsubscribe}. *
Also note that forwarding of the subscription to the server is made * asynchronously; this means that if a CPU consuming task is * performed right after the call the subscription will be delayed. *
A successful subscription to the server will be notified through a * {@link SubscriptionListener#onSubscription} event.

* @param subscription - A {@link Subscription} object, carrying * all the information needed to process its pushed values. */ subscribe(subscription: Subscription): void; /** * Operation method that removes a {@link Subscription} that is currently in * the "active" state. *
By bringing back a Subscription to the "inactive" state, the unsubscription * from all its items is requested to Lightstreamer Server. * *

Lifecycle: Subscription can be unsubscribed from at * any time. Once done the Subscription immediately exits the "active" state. *
Note that forwarding of the unsubscription to the server is made * asynchronously; this means that if a CPU consuming task is * performed right after the call the unsubscription will be delayed. *
The unsubscription will be notified through a * {@link SubscriptionListener#onUnsubscription} event.

* @param subscription - An "active" {@link Subscription} object * that was activated by this LightstreamerClient instance. */ unsubscribe(subscription: Subscription): void; /** * Adds a listener that will receive events from the LightstreamerClient * instance. *
The same listener can be added to several different LightstreamerClient * instances. * *

Lifecycle: a listener can be added at any time.

* @param listener - An object that will receive the events * as shown in the {@link ClientListener} interface. *
Note that the given instance does not have to implement all of the * methods of the ClientListener interface. In fact it may also * implement none of the interface methods and still be considered a valid * listener. In the latter case it will obviously receive no events. */ addListener(listener: ClientListener): void; /** * Removes a listener from the LightstreamerClient instance so that it * will not receive events anymore. * *

Lifecycle: a listener can be removed at any time.

* @param listener - The listener to be removed. */ removeListener(listener: ClientListener): void; /** * Returns an array containing the {@link ClientListener} instances that * were added to this client. * @returns an array containing the listeners that were added to this client. * Listeners added multiple times are included multiple times in the array. */ getListeners(): ClientListener[]; } /** * Creates an object to be used to describe a Subscription that is going * to be subscribed to through Lightstreamer Server. * The object can be supplied to {@link LightstreamerClient#subscribe} and * {@link LightstreamerClient#unsubscribe}, in order to bring the Subscription to * "active" or back to "inactive" state. *
Note that all of the methods used to describe the subscription to the server * can only be called while the instance is in the "inactive" state; the only * exception is {@link Subscription#setRequestedMaxFrequency}. * @param subscriptionMode - the subscription mode for the * items, required by Lightstreamer Server. Permitted values are: * * @param [items] - an array of Strings containing a list of items to * be subscribed to through the server. In case of a single-item subscription the String * containing the item name can be passed in place of the array; both of the * following examples represent a valid subscription: *
new Subscription(mode,"item1",fieldList); *
new Subscription(mode,["item1","item2"],fieldList); *
It is also possible to pass null (or nothing) and specify the * "Item List" or "Item Group" later through {@link Subscription#setItems} and * {@link Subscription#setItemGroup}. In this case the fields parameter must not be specified. * @param [fields] - An array of Strings containing a list of fields * for the items to be subscribed to through Lightstreamer Server. *
It is also possible to pass null (or nothing) and specify the * "Field List" or "Field Schema" later through {@link Subscription#setFields} and * {@link Subscription#setFieldSchema}. In this case the items parameter must not be specified. */ export class Subscription { constructor(subscriptionMode: string, items?: string | String[], fields?: String[]); /** * Inquiry method that checks if the Subscription is currently "active" or not. * Most of the Subscription properties cannot be modified if a Subscription is "active". *
The status of a Subscription is changed to "active" through the * {@link LightstreamerClient#subscribe} method and back to "inactive" through the * {@link LightstreamerClient#unsubscribe} one. * *

Lifecycle: This method can be called at any time.

* @returns true/false if the Subscription is "active" or not. */ isActive(): boolean; /** * Inquiry method that checks if the Subscription is currently subscribed to * through the server or not. *
This flag is switched to true by server sent Subscription events, and * back to false in case of client disconnection, * {@link LightstreamerClient#unsubscribe} calls and server sent unsubscription * events. * *

Lifecycle: This method can be called at any time.

* @returns true/false if the Subscription is subscribed to * through the server or not. */ isSubscribed(): boolean; /** * Setter method that sets the "Item List" to be subscribed to through * Lightstreamer Server. *
Any call to this method will override any "Item List" or "Item Group" * previously specified. * *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param items - An array of Strings containing an "Item List" to * be subscribed to through the server. */ setItems(items: String[]): void; /** * Inquiry method that can be used to read the "Item List" specified for this * Subscription. *
Note that if a single item was specified in the constructor, this method * will return an array of length 1 containing such item. * *

Lifecycle: This method can only be called if the Subscription has * been initialized with an "Item List". *

* @returns the "Item List" to be subscribed to through the server, or null if the Subscription was initialized with an "Item Group" or was not initialized at all. */ getItems(): String[]; /** * Setter method that sets the "Item Group" to be subscribed to through * Lightstreamer Server. *
Any call to this method will override any "Item List" or "Item Group" * previously specified. * *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param groupName - A String to be expanded into an item list by the * Metadata Adapter. */ setItemGroup(groupName: string): void; /** * Inquiry method that can be used to read the item group specified for this * Subscription. * *

Lifecycle: This method can only be called if the Subscription has * been initialized using an "Item Group" *

* @returns the "Item Group" to be subscribed to through the server, or null if the Subscription was initialized with an "Item List" or was not initialized at all. */ getItemGroup(): string; /** * Setter method that sets the "Field List" to be subscribed to through * Lightstreamer Server. *
Any call to this method will override any "Field List" or "Field Schema" * previously specified. * *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param fields - An array of Strings containing a list of fields to * be subscribed to through the server. */ setFields(fields: String[]): void; /** * Inquiry method that can be used to read the "Field List" specified for this * Subscription. * *

Lifecycle: This method can only be called if the Subscription has * been initialized using a "Field List". *

* @returns the "Field List" to be subscribed to through the server, or null if the Subscription was initialized with a "Field Schema" or was not initialized at all. */ getFields(): String[]; /** * Setter method that sets the "Field Schema" to be subscribed to through * Lightstreamer Server. *
Any call to this method will override any "Field List" or "Field Schema" * previously specified. * *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param schemaName - A String to be expanded into a field list by the * Metadata Adapter. */ setFieldSchema(schemaName: string): void; /** * Inquiry method that can be used to read the field schema specified for this * Subscription. * *

Lifecycle: This method can only be called if the Subscription has * been initialized using a "Field Schema" *

* @returns the "Field Schema" to be subscribed to through the server, or null if the Subscription was initialized with a "Field List" or was not initialized at all. */ getFieldSchema(): string; /** * Inquiry method that can be used to read the mode specified for this * Subscription. * *

Lifecycle: This method can be called at any time.

* @returns the Subscription mode specified in the constructor. */ getMode(): string; /** * Setter method that sets the name of the Data Adapter * (within the Adapter Set used by the current session) * that supplies all the items for this Subscription. *
The Data Adapter name is configured on the server side through * the "name" attribute of the "data_provider" element, in the * "adapters.xml" file that defines the Adapter Set (a missing attribute * configures the "DEFAULT" name). *
Note that if more than one Data Adapter is needed to supply all the * items in a set of items, then it is not possible to group all the * items of the set in a single Subscription. Multiple Subscriptions * have to be defined. * *

Default value: The default Data Adapter for the Adapter Set, * configured as "DEFAULT" on the Server.

* *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param dataAdapter - the name of the Data Adapter. A null value * is equivalent to the "DEFAULT" name. */ setDataAdapter(dataAdapter: string): void; /** * Inquiry method that can be used to read the name of the Data Adapter * specified for this Subscription through {@link Subscription#setDataAdapter}. * *

Lifecycle: This method can be called at any time.

* @returns the name of the Data Adapter; returns null if no name * has been configured, so that the "DEFAULT" Adapter Set is used. */ getDataAdapter(): string; /** * Setter method that sets the selector name for all the items in the * Subscription. The selector is a filter on the updates received. It is * executed on the Server and implemented by the Metadata Adapter. * *

Default value: null (no selector).

* *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param selector - name of a selector, to be recognized by the * Metadata Adapter, or null to unset the selector. */ setSelector(selector: string): void; /** * Inquiry method that can be used to read the selctor name * specified for this Subscription through {@link Subscription#setSelector}. * *

Lifecycle: This method can be called at any time.

* @returns the name of the selector. */ getSelector(): string; /** * Setter method that sets the maximum update frequency to be requested to * Lightstreamer Server for all the items in the Subscription. It can * be used only if the Subscription mode is MERGE, DISTINCT or * COMMAND (in the latter case, the frequency limitation applies to the * UPDATE events for each single key). For Subscriptions with two-level behavior * (see {@link Subscription#setCommandSecondLevelFields} and {@link Subscription#setCommandSecondLevelFieldSchema}) * , the specified frequency limit applies to both first-level and second-level items.
* Note that frequency limits on the items can also be set on the * server side and this request can only be issued in order to furtherly * reduce the frequency, not to rise it beyond these limits.
* This method can also be used to request unfiltered dispatching * for the items in the Subscription. However, unfiltered dispatching * requests may be refused if any frequency limit is posed on the server * side for some item. * *

Edition Note: A further global frequency limit could also * be imposed by the Server, depending on Edition and License Type; this specific limit also applies to RAW mode * and to unfiltered dispatching. * To know what features are enabled by your license, please see the License tab of the * Monitoring Dashboard (by default, available at /dashboard).

* *

Default value: null, meaning to lean on the Server default based on the subscription * mode. This consists, for all modes, in not applying any frequency * limit to the subscription (the same as "unlimited"); see the "General Concepts" * document for further details.

* *

Lifecycle: This method can can be called at any time with some * differences based on the Subscription status: *

*

* @param freq - A decimal number, representing the maximum update frequency (expressed in updates * per second) for each item in the Subscription; for instance, with a setting * of 0.5, for each single item, no more than one update every 2 seconds * will be received. If the string "unlimited" is supplied, then no frequency * limit is requested. It is also possible to supply the string * "unfiltered", to ask for unfiltered dispatching, if it is allowed for the * items, or a null value to stick to the Server default (which currently * corresponds to "unlimited"). * The check for the string constants is case insensitive. */ setRequestedMaxFrequency(freq: number): void; /** * Inquiry method that can be used to read the max frequency, configured * through {@link Subscription#setRequestedMaxFrequency}, to be requested to the * Server for this Subscription. * *

Lifecycle: This method can be called at any time.

* @returns A decimal number, representing the max frequency to be requested to the server * (expressed in updates per second), or the strings "unlimited" or "unfiltered", or null. */ getRequestedMaxFrequency(): string; /** * Setter method that sets the length to be requested to Lightstreamer * Server for the internal queueing buffers for the items in the Subscription. * A Queueing buffer is used by the Server to accumulate a burst * of updates for an item, so that they can all be sent to the client, * despite of bandwidth or frequency limits. It can be used only when the * subscription mode is MERGE or DISTINCT and unfiltered dispatching has * not been requested. Note that the Server may pose an upper limit on the * size of its internal buffers. * *

Default value: null, meaning to lean * on the Server default based on the subscription mode. This means that * the buffer size will be 1 for MERGE subscriptions and "unlimited" for * DISTINCT subscriptions. See the "General Concepts" document for further details.

* *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param size - The length of the internal queueing buffers to be * used in the Server. If the string "unlimited" is supplied, then no buffer * size limit is requested (the check is case insensitive). It is also possible * to supply a null value to stick to the Server default (which currently * depends on the subscription mode). */ setRequestedBufferSize(size: number): void; /** * Inquiry method that can be used to read the buffer size, configured though * {@link Subscription#setRequestedBufferSize}, to be requested to the Server for * this Subscription. * *

Lifecycle: This method can be called at any time.

* @returns the buffer size to be requested to the server. */ getRequestedBufferSize(): string; /** * Setter method that enables/disables snapshot delivery request for the * items in the Subscription. The snapshot can be requested only if the * Subscription mode is MERGE, DISTINCT or COMMAND. * *

Default value: "yes" if the Subscription mode is not "RAW", * null otherwise.

* *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param required - "yes"/"no" to request/not request snapshot * delivery (the check is case insensitive). If the Subscription mode is * DISTINCT, instead of "yes", it is also possible to supply a number, * to specify the requested length of the snapshot (though the length of * the received snapshot may be less than requested, because of insufficient * data or server side limits); * passing "yes" means that the snapshot length should be determined * only by the Server. Null is also a valid value; if specified no snapshot * preference will be sent to the server that will decide itself whether * or not to send any snapshot. */ setRequestedSnapshot(required: string): void; /** * Inquiry method that can be used to read the snapshot preferences, configured * through {@link Subscription#setRequestedSnapshot}, to be requested to the Server for * this Subscription. * *

Lifecycle: This method can be called at any time.

* @returns the snapshot preference to be requested to the server. */ getRequestedSnapshot(): string; /** * Setter method that sets the "Field List" to be subscribed to through * Lightstreamer Server for the second-level items. It can only be used on * COMMAND Subscriptions. *
Any call to this method will override any "Field List" or "Field Schema" * previously specified for the second-level. *
Calling this method enables the two-level behavior: *
in synthesis, each time a new key is received on the COMMAND Subscription, * the key value is treated as an Item name and an underlying Subscription for * this Item is created and subscribed to automatically, to feed fields specified * by this method. This mono-item Subscription is specified through an "Item List" * containing only the Item name received. As a consequence, all the conditions * provided for subscriptions through Item Lists have to be satisfied. The item is * subscribed to in "MERGE" mode, with snapshot request and with the same maximum * frequency setting as for the first-level items (including the "unfiltered" * case). All other Subscription properties are left as the default. When the * key is deleted by a DELETE command on the first-level Subscription, the * associated second-level Subscription is also unsubscribed from. *
Specifying null as parameter will disable the two-level behavior. * *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param fields - An array of Strings containing a list of fields to * be subscribed to through the server. *
Ensure that no name conflict is generated between first-level and second-level * fields. In case of conflict, the second-level field will not be accessible * by name, but only by position. */ setCommandSecondLevelFields(fields: String[]): void; /** * Inquiry method that can be used to read the "Field List" specified for * second-level Subscriptions. * *

Lifecycle: This method can only be called if the second-level of * this Subscription has been initialized using a "Field List" *

* @returns the list of fields to be subscribed to through the server, or null if the Subscription was initialized with a "Field Schema" or was not initialized at all. */ getCommandSecondLevelFields(): String[]; /** * Setter method that sets the "Field Schema" to be subscribed to through * Lightstreamer Server for the second-level items. It can only be used on * COMMAND Subscriptions. *
Any call to this method will override any "Field List" or "Field Schema" * previously specified for the second-level. *
Calling this method enables the two-level behavior: *
in synthesis, each time a new key is received on the COMMAND Subscription, * the key value is treated as an Item name and an underlying Subscription for * this Item is created and subscribed to automatically, to feed fields specified * by this method. This mono-item Subscription is specified through an "Item List" * containing only the Item name received. As a consequence, all the conditions * provided for subscriptions through Item Lists have to be satisfied. The item is * subscribed to in "MERGE" mode, with snapshot request and with the same maximum * frequency setting as for the first-level items (including the "unfiltered" * case). All other Subscription properties are left as the default. When the * key is deleted by a DELETE command on the first-level Subscription, the * associated second-level Subscription is also unsubscribed from. *
Specify null as parameter will disable the two-level behavior. * *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param schemaName - A String to be expanded into a field list by the * Metadata Adapter. */ setCommandSecondLevelFieldSchema(schemaName: string): void; /** * Inquiry method that can be used to read the "Field Schema" specified for * second-level Subscriptions. * *

Lifecycle: This method can only be called if the second-level of * this Subscription has been initialized using a "Field Schema". *

* @returns the "Field Schema" to be subscribed to through the server, or null if the Subscription was initialized with a "Field List" or was not initialized at all. */ getCommandSecondLevelFieldSchema(): string; /** * Setter method that sets the name of the second-level Data Adapter (within * the Adapter Set used by the current session) that supplies all the * second-level items. * All the possible second-level items should be supplied in "MERGE" mode * with snapshot available. * The Data Adapter name is configured on the server side through the * "name" attribute of the <data_provider> element, in the "adapters.xml" * file that defines the Adapter Set (a missing attribute configures the * "DEFAULT" name). * *

Default value: The default Data Adapter for the Adapter Set, * configured as "DEFAULT" on the Server.

* *

Lifecycle: This method can only be called while the Subscription * instance is in its "inactive" state.

* @param dataAdapter - the name of the Data Adapter. A null value * is equivalent to the "DEFAULT" name. */ setCommandSecondLevelDataAdapter(dataAdapter: string): void; /** * Inquiry method that can be used to read the second-level Data * Adapter name configured through {@link Subscription#setCommandSecondLevelDataAdapter}. * *

Lifecycle: This method can be called at any time.

* @returns the name of the second-level Data Adapter. */ getCommandSecondLevelDataAdapter(): string; /** * Returns the latest value received for the specified item/field pair. *
It is suggested to consume real-time data by implementing and adding * a proper {@link SubscriptionListener} rather than probing this method. * In case of COMMAND Subscriptions, the value returned by this * method may be misleading, as in COMMAND mode all the keys received, being * part of the same item, will overwrite each other; for COMMAND Subscriptions, * use {@link Subscription#getCommandValue} instead. *
Note that internal data is cleared when the Subscription is * unsubscribed from. * *

Lifecycle: This method can be called at any time; if called * to retrieve a value that has not been received yet, then it will return null. *

* @param itemIdentifier - a String representing an item in the * configured item list or a Number representing the 1-based position of the item * in the specified item group. (In case an item list was specified, passing * the item position is also possible). * @param fieldIdentifier - a String representing a field in the * configured field list or a Number representing the 1-based position of the field * in the specified field schema. (In case a field list was specified, passing * the field position is also possible). * @returns the current value for the specified field of the specified item * (possibly null), or null if no value has been received yet. */ getValue(itemIdentifier: string, fieldIdentifier: string): string; /** * Returns the latest value received for the specified item/key/field combination. * This method can only be used if the Subscription mode is COMMAND. * Subscriptions with two-level behavior are also supported, hence the specified * field can be either a first-level or a second-level one. *
It is suggested to consume real-time data by implementing and adding * a proper {@link SubscriptionListener} rather than probing this method. *
Note that internal data is cleared when the Subscription is * unsubscribed from. * *

Lifecycle: This method can be called at any time; if called * to retrieve a value that has not been received yet, then it will return null. *

* @param itemIdentifier - a String representing an item in the * configured item list or a Number representing the 1-based position of the item * in the specified item group. (In case an item list was specified, passing * the item position is also possible). * @param keyValue - a String containing the value of a key received * on the COMMAND subscription. * @param fieldIdentifier - a String representing a field in the * configured field list or a Number representing the 1-based position of the field * in the specified field schema. (In case a field list was specified, passing * the field position is also possible). * @returns the current value for the specified field of the specified * key within the specified item (possibly null), or null if the specified * key has not been added yet (note that it might have been added and eventually deleted). */ getCommandValue(itemIdentifier: string, keyValue: string, fieldIdentifier: string): string; /** * Returns the position of the "key" field in a COMMAND Subscription. *
This method can only be used if the Subscription mode is COMMAND * and the Subscription was initialized using a "Field Schema". * *

Lifecycle: This method can be called at any time.

* @returns the 1-based position of the "key" field within the "Field Schema". */ getKeyPosition(): number; /** * Returns the position of the "command" field in a COMMAND Subscription. *
This method can only be used if the Subscription mode is COMMAND * and the Subscription was initialized using a "Field Schema". * *

Lifecycle: This method can be called at any time.

* @returns the 1-based position of the "command" field within the "Field Schema". */ getCommandPosition(): number; /** * Adds a listener that will receive events from the Subscription * instance. *
The same listener can be added to several different Subscription * instances. * *

Lifecycle: a listener can be added at any time.

* @param listener - An object that will receive the events * as shown in the {@link SubscriptionListener} interface. *
Note that the given instance does not have to implement all of the * methods of the SubscriptionListener interface. In fact it may also * implement none of the interface methods and still be considered a valid * listener. In the latter case it will obviously receive no events. */ addListener(listener: SubscriptionListener): void; /** * Removes a listener from the Subscription instance so that it * will not receive events anymore. * *

Lifecycle: a listener can be removed at any time.

* @param listener - The listener to be removed. */ removeListener(listener: SubscriptionListener): void; /** * Returns an array containing the {@link SubscriptionListener} instances that * were added to this client. * @returns an Array containing the listeners that were added to this client. * Listeners added multiple times are included multiple times in the array. */ getListeners(): SubscriptionListener[]; } /** * This is a dummy constructor not to be used in any case. */ export class ConsoleLogLevel { constructor(); /** * Trace logging level. * * This level enables all logging. */ static readonly TRACE: number; /** * Debug logging level. * * This level enables all logging except tracing. */ static readonly DEBUG: number; /** * Info logging level. * * This level enables logging for information, warnings, errors and fatal errors. */ static readonly INFO: number; /** * Warn logging level. * * This level enables logging for warnings, errors and fatal errors. */ static readonly WARN: number; /** * Error logging level. * * This level enables logging for errors and fatal errors. */ static readonly ERROR: number; /** * Fatal logging level. * * This level enables logging for fatal errors only. */ static readonly FATAL: number; } /** * Creates an instance of the concrete system console logger. * @param level - The desired logging level. See {@link ConsoleLogLevel}. */ export class ConsoleLoggerProvider implements LoggerProvider { constructor(level: number); /** * Invoked to request a {@link Logger} instance that will be used for logging occurring * on the given category. It is suggested, but not mandatory, that subsequent * calls to this method related to the same category return the same {@link Logger} * instance. * @param category - the log category all messages passed to the given * Logger instance will pertain to. * @returns A Logger instance that will receive log lines related to * the given category. */ getLogger(category: string): Logger; } /** * Callback for {@link Chart#setXLabels} and {@link ChartLine#setYLabels}. * @param value - the value to be formatted before being print in a label. * @return the String to be set as content for the label. */ declare type LabelsFormatter = (value: number) => string; /** * Callback for {@link Chart#setXAxis} and {@link Chart#addYAxis}. * @param fieldValue - the field value to be parsed. * @param key - the key associated with the given value * @return a valid number to be plotted or null if the value has to be considered unchanged */ declare type CustomParserFunction = (fieldValue: string, key: string) => number; /** * Callback for {@link VisualUpdate#forEachChangedField}. * @param field - name of the involved changed field. * @param value - the new value for the field. See {@link VisualUpdate#getChangedFieldValue} for details. * Note that changes to the values made through {@link VisualUpdate#setCellValue} calls will not be reflected * by the iterator, as they don't affect the model. */ declare type ChangedFieldCallback = (filed: string, value: string) => void; declare module 'lightstreamer-client-node';