Class: ConnectionSharing

ConnectionSharing

Bean object that contains informations about if and how the connection is shared between different LightstreamerClient instances possibly living on different html pages.
The class constructor and its prototype should never be used directly; the library will create ConnectionSharing instances when needed.

new ConnectionSharing()

Used by LightstreamerClient to provide a enable/disable/verify connection sharing bean.
See:

Method Summary

enableSharing
Operation method that controls connection sharing policies for the current LightstreamerClient instance.
getSharedClients
Inquiry method that returns a list of LightstreamerClient instances sharing the same connection with the LightstreamerClient owning this instance.
getShareName
Inquiry method that returns the share name configured through an ConnectionSharing#enableSharing call (or null if no call to it nor to LightstreamerClient#connect was made).
isMaster
Inquiry method that checks if the LightstreamerClient owning this instance has its own connection / would create its own connection upon a connect call or not.

Method Detail

enableSharing(shareName, sharePolicyOnFound, sharePolicyOnNotFound, preventCrossWindowShare, shareRef)

Operation method that controls connection sharing policies for the current LightstreamerClient instance. If the front-end includes more than one LightstreamerClient instance that need to subscribe to the same server, it is advised that such instances share the same connection to avoid saturating the client connection pool and to open fewer sessions on the Lightstreamer Server. Note that sharing is also possible between clients living in different HTML pages, provided that they come from the same host and are handled by the same browser process. In this case some Cookies or values on the Web Storage may be used to exchange preliminary informations across windows. The used keys are prefixed with the "Lightstreamer_" string. Specifiyng true on the preventCrossWindowShare parameter it is possible to prevent the Cookies/Web Storage usage.
When different LightstreamerClient share the same connection, the one actually holding the connection is also known as the current "Master" client. Whenever possible, the Master LightstreamerClient should be hosted by a permanent page.
If the current Master, for any reason, disappears, then the connection to Lightstreamer Server has to be reestablished: the election algorithm will choose a new Master among the surviving LightstreamerClient instances and will restore the same status that was in place before the previous Master disappeared.

Default value: by default no sharing is configured.

Lifecycle: this method can be called at any time. However, in case LightstreamerClient#connect is called before this method has ever been called, then an automatic call will be performed with the following parameters:
enableSharing(randomGeneratedName, "IGNORE", "CREATE", true, null);
Note that if multiple calls to this method are performed, the last one will override the previous ones. Also if a call to enableSharing is made on a Master client, the current connection (if any) will be dropped and the remaining clients will enter the election algorithm.

Parameters:
Name Type Description
shareName String A unique alphanumeric name for the shared connection. The name can be used by other LightstreamerClient in order to recognize a compatible shared connection. Two LightstreamerClient instances should use the same shareName for their enableSharing calls only if they are going to configure the connection in the same way to connect to the same server.
sharePolicyOnFound String The action to be taken in case a client sharing a connection using the same shareName and coming from the same host is found in the browser (i.e. an active Master is found).
Can be one of the following:
  • "ATTACH" the client will try to become a Slave to the found Master.
    Note that this policy can only be used on clients living inside a browser window (i.e. no web workers nor non-browser environments). Also the "ATTACH" policy will not work as expected if the involved clients are instantiated in HTML pages loaded from the file system rather than downloaded from a web server.
    Note that it is an application responsibility to ensure that the configuration of the Master client (the user credentials, for instance) is consistent with the configuration required by the new instance of the application front-end. In particular, note that the allocated bandwidth would be shared among the two (or more) LightstreamerClient instances as well.
    Note that a connection, to be correctly shared between different pages, has to be created in the <BODY> part of the page. If this condition is not met, on some browsers, slave clients may waste some extra time before being able to access the shared connection.
    Sharing the connection also enables the so called "Master election" feature. If the Master client is closed and other clients share the connection with it, then one of the existing clients will be automatically chosen as the new Master; this client will restore the status and configuration of the previous Master client as it was before its death.
    Note that there may be cases in which the library is not able to determine whether a shared connection is currently active. Moreover, there may be cases in which the library is not able to obtain a reference to a currently active Master client. One such case is when the existing Master client page is in a different window in Opera browser.
  • "ATTACH:FAST" same as "ATTACH" but the client will take some risks of making a popup appear in order to speed up things.
  • "IGNORE" the found Master will be ignored and the sharePolicyOnNotFound behavior will be applied.
  • "ABORT" the client will give up in the search of an active shared connection and will neither try to create its own; the ClientListener#onShareAbort event will be fired.
    This policy may be useful in order to avoid that multiple streaming connections are open (note that the browser may have a limited pool of connections) or that multiple sessions for the same user are open.
sharePolicyOnNotFound String The action to be taken in case a client sharing a connection using the same shareName and coming from the same host is not found in the browser (i.e. no active Master is found).
Can be one of the following:
  • "CREATE" the client will create its own connection.
  • "ABORT" the client will give up in the search of an active shared connection and will neither try to create its own; the ClientListener#onShareAbort event will be fired.
  • "WAIT" the client will wait until it finds a connection using the same shareName and coming from the same host; then the sharePolicyOnFound behavior will be applied.
preventCrossWindowShare boolean [optional] Flag to enable/disable the sharing of a connection that belongs to a LightstreamerClient instances living in a different html page.
Note that cross-window sharing is only possible if both pages share the same document.domain value.
If this flag is set to true, a Master living on a different window will not trigger the sharePolicyOnFound policy; hence, only sharing with another LightstreamerClient instance belonging to the same page will be possible.
The parameter is optional; if not supplied, the default value is false.
shareRef Window [optional] If known, the reference to a Window containing a shared connection can be passed. For the passed reference to be used, "ATTACH" or "ATTACH:FAST" should be used as sharePolicyOnFound.
Throws:
  • if the sharename is not specified or is invalid.
    Type
    IllegalArgumentException
  • if a non-existent policy was specified or if the specified policy is not compatible with the current environment.
    Type
    IllegalArgumentException

getSharedClients() → {Array}

Inquiry method that returns a list of LightstreamerClient instances sharing the same connection with the LightstreamerClient owning this instance.
See:
Returns:
The list of LightstreamerClient instances sharing the same connection.
Type
Array

getShareName() → {String}

Inquiry method that returns the share name configured through an ConnectionSharing#enableSharing call (or null if no call to it nor to LightstreamerClient#connect was made).
See:
Returns:
The configured share name.
Type
String

isMaster() → {boolean}

Inquiry method that checks if the LightstreamerClient owning this instance has its own connection / would create its own connection upon a connect call or not. The LightstreamerClient is not a Master if it is attached to another LightstreamerClient connection or if no call to LightstreamerClient#connect or ConnectionSharing#enableSharing was performed on it.
See:
Returns:
Whenever the LightstreamerClient owning this instance is a Master or not.
Type
boolean