Class: ConnectionDetails

ConnectionDetails

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

new ConnectionDetails()

Used by LightstreamerClient to provide a basic connection properties bean.

Method Summary

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.

Setter method that sets the username to be used for the authentication
on Lightstreamer Server when initiating the push session.

Method Detail

getAdapterSet() → {String}

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.

Type

String

getServerAddress() → {String}

Inquiry method that gets the configured address of Lightstreamer Server.

Returns:

the configured address of Lightstreamer Server.

Type

String

getServerInstanceAddress() → {String}

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
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
not supported when using Lightstreamer in Moderato edition.

Lifecycle: The method gives a meaningful answer only when
a session is currently active.

Notification: A change to this setting will be notified through a
call to ClientListener#onPropertyChange with argument "serverInstanceAddress" on any
ClientListener
listening to any LightstreamerClient sharing the same
connection with the LightstreamerClient that received the setting from the
server
.

Returns:

address used to issue all requests related to the current
session.

Type

String

getServerSocketName() → {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
not supported when using Lightstreamer in Moderato edition.

Lifecycle: The method gives a meaningful answer only when
a session is currently active.

Notification: A change to this setting will be notified through a
call to ClientListener#onPropertyChange with argument "serverSocketName" on any
ClientListener
listening to any LightstreamerClient sharing the same
connection with the LightstreamerClient that received the setting from the
server
.

Returns:

name configured for the Server instance which is managing the
current session.

Type

String

getSessionId() → {String}

Inquiry method that gets the ID associated by the server
to this client session.

Lifecycle: The method gives a meaningful answer only when
a session is currently active.

Notification: A change to this setting will be notified through a
call to ClientListener#onPropertyChange with argument "sessionId" on any
ClientListener
listening to any LightstreamerClient sharing the same
connection with the LightstreamerClient that received the setting from the
server
.

Returns:

ID assigned by the Server to this client session.

Type

String

getUser() → {String}

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.

Type

String

setAdapterSet(adapterSet)

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.

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

Parameters:

Name

Type

Description

adapterSet

String

The name of the Adapter Set to be used. A null value
is equivalent to the "DEFAULT" name.

setPassword(password)

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
LightstreamerClient#connectionDetails object before calling the
LightstreamerClient#connect method. However, the value can be changed
at any time: the supplied value will be used for the next 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 ClientListener#onPropertyChange with argument "password" on any
ClientListener
listening to any LightstreamerClient sharing the same
connection with the LightstreamerClient owning the ConnectionDetails upon
which the setter was called
.

Parameters:

Name

Type

Description

password

String

The password to be used for the authentication
on Lightstreamer Server. The password can be null.

setServerAddress(serverAddress)

Setter method that sets the address of Lightstreamer Server.
Setting Lightstreamer Server address is not required when the front-end
pages are supplied by Lightstreamer Server itself (although this
scenario is advised only for demo purpose).
On the other hand, the setting should be configured if the front-end pages are
served by an external Web server or loaded directly from the file system or
the library is not running inside a browser.
When the client application is downloaded from a web server, the configured
server address should have the same protocol as the client page itself. If this
requirement is not respected, the client, depending on the browser in use,
may be unable to open a streaming connection and will try to resort
to polling.
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 connections are not
supported by the Server if it runs in Allegro edition.

Edition Note: HTTPS connections are not
supported by the Server if it runs in Moderato edition.

Default value: the address of the server
that supplies the library pages if any, null otherwise.

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 LightstreamerClient
constructor.

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

Parameters:

Name

Type

Description

serverAddress

String

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

Throws:

setUser(user)

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.

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

Parameters:

Name

Type

Description

user

String

The username to be used for the authentication
on Lightstreamer Server. The username can be null.