Web Client 8.0.2

ConnectionSharing

ConnectionSharing

Data object that contains information about if and how the connection is shared between different LightstreamerClient instances possibly living on different html pages.

Constructor

new ConnectionSharing(shareName, sharePolicyOnFound, sharePolicyOnNotFound, preventCrossWindowShareopt, shareRefopt)

Data object describing the sharing policies to be used by a 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. Note that Browser capabilities and/or restrictions might prevent the sharing. If sharing is enabled some Cookies or values on the Web Storage may be used to exchange preliminary information across windows. The used keys are prefixed with the "Lightstreamer_" string. Specifying 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.

Parameters:
Name Type Attributes Description
shareName String

A unique alphanumeric name for the shared connection. The name can be used by different 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. Obviously, this includes the user credentials.
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 might 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.
  • "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>

[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 might be impossible in certain circumstances.
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.
See:
Throws:

Methods

getShareName() → {String}

Inquiry method that returns the share name configured in this instance.

See:
Returns:

The configured share name.

Type
String

isPossible()

Connection sharing is possible only if the environment supports SharedWorkers or the user requested a local sharing.