public class LSClient
extends java.lang.Object
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
CONNECTING
String constant for the "connecting" status of LSClient:
The Client is trying to reach Lightstreamer Server.
|
static java.lang.String |
OFF
String constant for the "off" status of LSClient:
The Client is waiting for connection commands.
|
static java.lang.String |
POLLING
Represent the polling status of LSClient.
|
static java.lang.String |
STALLED
String constant for the "stalled" status of LSClient:
The Client was receiving data from a Lightstreamer Server
but it now seems to be isolated.
|
static java.lang.String |
STREAMING
String constant for the "streaming" status of LSClient:
The Client is receiving real-time updates from
Lightstreamer Server.
|
Constructor and Description |
---|
LSClient()
Constructor LSClient.
|
Modifier and Type | Method and Description |
---|---|
static void |
closeApp()
Calling this method will stops all the LSClient's thread.
|
void |
closeConnection()
Closes the connection to the Server, if one is open.
|
ConnectionProvider |
getConnectionProvider()
Getter method that returns the ConnectionProvider instance in use.
|
long |
getReverseHeartbeatMillis()
Getter method that returns the configured interval used for the reverse-heartbeat mechanism.
|
java.lang.String |
getStatus()
Inquiry method that gets the current client status.
|
boolean |
isUsingReusableItemUpdates()
Getter method that returns true if this instance is using reusable update instances, false otherwise.
|
boolean |
isUsingSingleConnection()
Getter method that returns true if LSClient will be permitted to open only one connection
at a time, false otherwise.
|
boolean |
isUsingSocketConnection()
Getter method that returns true if this instance is going to expect a SocketConnection
instance from
ConnectionProvider.getNextConnection(String, boolean) calls,
while returns false if a HttpConnection is expected. |
void |
openConnection(ConnectionInfo info,
ConnectionListener listener)
Open a stream connection to the Server with the supplied parameters and default policies.
|
void |
openConnection(ConnectionInfo info,
ConnectionListener listener,
ConnectionPolicy policy)
Open a stream connection to the Server with the supplied parameters and policies.
|
void |
openPollingConnection(ConnectionInfo info,
ConnectionListener listener)
Open a poll connection to the Server with the supplied parameters and default policies.
|
void |
openPollingConnection(ConnectionInfo info,
ConnectionListener listener,
ConnectionPolicy policy)
Open a poll connection to the Server with the supplied parameters and policies.
|
int |
sendMessage(MessageInfo message,
SendMessageListener listener)
Send a message to Lightstreamer Server.
|
void |
setBandwidthUnlimited()
Request unlimited bandwidth for the next/current connection.
|
void |
setBufferMax(int bufferMax)
This method establishes how large the Client buffer must be.
|
void |
setConnectionProvider(ConnectionProvider connProvider)
Setter method that sets the
ConnectionProvider instance that will be
internally used to obtain Connection instances to communicate with Lightstreamer
server. |
void |
setFrequencyUnlimited(SubscribedTableKey key)
Request unlimited frequency for a table currently subscribed to.
|
void |
setMaxBandwidth(int maxBandwidth)
Request a new maximum bandwidth for the next/current connection.
|
void |
setMaxFrequency(SubscribedTableKey key,
double maxFrequency)
Request a new maximum frequency for a table currently subscribed to.
|
void |
setReverseHeartbeatMillis(long reverseHeartbeatMillis)
This methods permits to enable/disable the reverse-heartbeat mechanism on the control connection by
setting the heartbeat interval: if the given value (expressed in milliseconds) equals 0 then the
reverse-heartbeat mechanism will be disabled; otherwise if the given value is greater than 0 the mechanism
will be enabled with the specified interval.
|
SubscribedTableKey |
subscribeTable(ExtendedTableInfo info,
ExtendedTableListener tListener)
Subscribes to a table through the Server.
|
SubscribedTableKey |
subscribeTable(ExtendedTableInfo info,
HandyTableListener tListener,
boolean commandLogic)
Subscribes to a table through the Server.
|
SubscribedTableKey |
subscribeTable(SimpleTableInfo info,
HandyTableListener tListener,
boolean commandLogic)
Subscribes to a table through the Server.
|
SubscribedTableKey |
subscribeTable(SimpleTableInfo info,
SimpleTableListener tListener)
Subscribes to a table through the Server.
|
java.lang.String |
toString()
Returns a string representing the LSClient attributes
and the actual state.
|
void |
unsubscribeTable(SubscribedTableKey key)
Unsubscribes from a table previously subscribed to.
|
void |
useReusableItemUpdates(boolean useReusable)
This method establishes if the LSClient instance can reuse
the
SimpleItemUpdate and ExtendedItemUpdate
object instances it supplies to the listeners. |
void |
useSingleConnection(boolean useOneConnection)
This method establish if LSClient will use one
or more connections to communicate with Lightstreamer Server.
|
void |
useSocketConnection(boolean useSocket)
This method establishes if LSClient will request Connection instances to its
ConnectionProvider using the "socket://" and "ssl://" prefixes
or the "http://" "https://" ones. |
public static final java.lang.String OFF
public static final java.lang.String CONNECTING
public static final java.lang.String STREAMING
public static final java.lang.String STALLED
public static final java.lang.String POLLING
public void useSingleConnection(boolean useOneConnection)
useOneConnection
- If true only one socket will be opened (default is false).openConnection(ConnectionInfo, ConnectionListener)
,
openConnection(ConnectionInfo, ConnectionListener, ConnectionPolicy)
,
openPollingConnection(ConnectionInfo, ConnectionListener)
,
openPollingConnection(ConnectionInfo, ConnectionListener, ConnectionPolicy)
,
subscribeTable(ExtendedTableInfo, ExtendedTableListener)
,
subscribeTable(SimpleTableInfo, SimpleTableListener)
,
subscribeTable(ExtendedTableInfo, HandyTableListener, boolean)
,
subscribeTable(SimpleTableInfo, HandyTableListener, boolean)
,
unsubscribeTable(SubscribedTableKey)
,
setBandwidthUnlimited()
,
setMaxBandwidth(int)
,
sendMessage(MessageInfo, SendMessageListener)
,
ConnectionPolicy.setBufferedStreamingHandled(boolean)
public boolean isUsingSingleConnection()
useSingleConnection(boolean)
public void useSocketConnection(boolean useSocket)
ConnectionProvider
using the "socket://" and "ssl://" prefixes
or the "http://" "https://" ones.
ConnectionProvider.getNextConnection(String, boolean)
method must be an HttpConnection instance, otherwise a SocketConnection is expected.
useSocket
- Use socket connections or do not (default is true).ConnectionProvider
public boolean isUsingSocketConnection()
ConnectionProvider.getNextConnection(String, boolean)
calls,
while returns false if a HttpConnection is expected.useSocketConnection(boolean)
public void useReusableItemUpdates(boolean useReusable)
SimpleItemUpdate
and ExtendedItemUpdate
object instances it supplies to the listeners.
HandyTableListener
is used, the setting has no effect,
as UpdateInfo
objects are always returned; supplied objects
of this type are never reused by library code.useReusable
- Use reusable objects or do not (default is true).SimpleItemUpdate.isReusable()
,
ExtendedItemUpdate.isReusable()
public boolean isUsingReusableItemUpdates()
useReusableItemUpdates(boolean)
public void setBufferMax(int bufferMax)
ConnectionListener.onBufferFull()
is issued
and no more data is read from the connection until the buffer is empty.bufferMax
- The dimension of the client buffer (default is 10).public long getReverseHeartbeatMillis()
setReverseHeartbeatMillis(long)
public void setReverseHeartbeatMillis(long reverseHeartbeatMillis)
reverseHeartbeatMillis
- either an interval in milliseconds or 0 to disable heartbeats.java.lang.IllegalStateException
- Thrown in single connection mode.#see #getReverseHeartbeatMillis
public void openPollingConnection(ConnectionInfo info, ConnectionListener listener)
The Stream-sense feature is disabled, only poll connections will be used until a call to any openConnection is issued.
info
- The connection parameters.
A copy of the object is stored internally.listener
- The connection listener which will receive state changes and errors
of the LSClient instance. If a previous instance of ConnectionListener was supplied
(via any openConnection/openPollingConnection call), that instance will
be overwritten and will not receives any updates.java.lang.IllegalStateException
- Thrown in single connection mode if no tables are
subscribed yet.ConnectionListener
,
ConnectionInfo
,
useSingleConnection(boolean)
public void openPollingConnection(ConnectionInfo info, ConnectionListener listener, ConnectionPolicy policy)
The Stream-sense feature is disabled, only poll connection will be used until a call to any openConnection is issued.
info
- The connection parameters.
A copy of the object is stored internally.listener
- The connection listener which will receive state changes and errors
of the LSClient instance. If a previous instance of ConnectionListener was supplied
(via any openConnection/openPollingConnection call), that instance will
be overwritten and will not receives any updates.policy
- The connection policies.
A copy of the object is stored internally.java.lang.IllegalStateException
- Thrown in single connection mode if no tables are
subscribed yet.ConnectionListener
,
ConnectionInfo
,
ConnectionPolicy
,
useSingleConnection(boolean)
public void openConnection(ConnectionInfo info, ConnectionListener listener)
The Stream-sense feature is enabled, if the network infrastructure is not able to sustain streaming then the Client will switch to polling mode.
info
- The connection parameters.
A copy of the object is stored internally.listener
- The connection listener which will receive state changes and errors
of the LSClient instance. If a previous instance of ConnectionListener
was supplied
(via any openConnection/openPollingConnection call), that instance will
be overwritten and will not receives any updates.java.lang.IllegalStateException
- Thrown in single connection mode if no tables are
subscribed yet.ConnectionListener
,
ConnectionInfo
,
useSingleConnection(boolean)
public void openConnection(ConnectionInfo info, ConnectionListener listener, ConnectionPolicy policy)
The Stream-sense feature is enabled, if the network infrastructure is not able to sustain streaming then the Client will switch to polling mode.
info
- The connection parameters.
A copy of the object is stored internally.listener
- The connection listener which will receive state changes and errors
of the LSClient instance. If a previous instance of ConnectionListener was supplied
(via any openConnection/openPollingConnection call), that instance will
be overwritten and will not receives any updates.policy
- The connection policies.
A copy of the object is stored internally.java.lang.IllegalStateException
- Thrown in single connection mode if no tables are
subscribed yet.ConnectionListener
,
ConnectionInfo
,
ConnectionPolicy
,
useSingleConnection(boolean)
public void closeConnection()
public SubscribedTableKey subscribeTable(ExtendedTableInfo info, ExtendedTableListener tListener)
info
- Contains the specification and request parameters
of the table to subscribe to.
A copy of the object is stored internally.tListener
- Receives notification of data updates and other messages
related to this subscription.java.lang.IllegalStateException
- Thrown in single connection mode if the
client is already connected (or connecting) to Lightstreamer Server.
In single connection mode, subscription requests can only be issued
while the client is disconnected; the subscription requests are issued,
together with the connection request, upon the next call to
any openConnection/openPollingConnection.useSingleConnection(boolean)
public SubscribedTableKey subscribeTable(SimpleTableInfo info, SimpleTableListener tListener)
info
- Contains the specification and request parameters
of the table to subscribe to.
A copy of the object is stored internally.tListener
- Receives notification of data updates and other messages
related to this subscription.java.lang.IllegalStateException
- Thrown in single connection mode if the
client is already connected (or connecting) to Lightstreamer Server.
In single connection mode, subscription requests can only be issued
while the client is disconnected; the subscription requests are issued,
together with the connection request, upon the next call to
any openConnection/openPollingConnection.useSingleConnection(boolean)
public SubscribedTableKey subscribeTable(ExtendedTableInfo info, HandyTableListener tListener, boolean commandLogic)
info
- Contains the specification and request parameters
of the table to subscribe to.
A copy of the object is stored internally.tListener
- Receives notification of data updates and other messages
related to this subscription.commandLogic
- if true, enables the notification of item updates
with "COMMAND logic", as specified in HandyTableListener
.
This requires that the items are subscribed to in COMMAND mode or
behave equivalently; in particular, that the special "key" and "command"
fields are included in the schema.java.lang.IllegalStateException
- Thrown in single connection mode if the
client is already connected (or connecting) to Lightstreamer Server.
In single connection mode, subscription requests can only be issued
while the client is disconnected; the subscription requests are issued,
together with the connection request, upon the next call to
any openConnection/openPollingConnection.useSingleConnection(boolean)
public SubscribedTableKey subscribeTable(SimpleTableInfo info, HandyTableListener tListener, boolean commandLogic)
info
- Contains the specification and request parameters
of the table to subscribe to.
A copy of the object is stored internally.tListener
- Receives notification of data updates and other messages
related to this subscription.commandLogic
- if true, enables the management of item values
in "COMMAND logic", as specified in HandyTableListener
.
This requires that the items are subscribed to in COMMAND mode or
behave equivalently. This also requires that the special "key" and
"command" fields are the first and second field in the schema,
respectively.java.lang.IllegalStateException
- Thrown in single connection mode if the
client is already connected (or connecting) to Lightstreamer Server.
In single connection mode, subscription requests can only be issued
while the client is disconnected; the subscription requests are issued,
together with the connection request, upon the next call to
any openConnection/openPollingConnection.useSingleConnection(boolean)
public void setMaxFrequency(SubscribedTableKey key, double maxFrequency)
setFrequencyUnlimited(com.lightstreamer.javameclient.midp.SubscribedTableKey)
method.
The limit can only be used in order to restrict the constraints
set by Lightstreamer Server Metadata Adapter.
key
- Handle to a table as returned by any subscribeTable call.maxFrequency
- Frequency constraint, in Kbit/sec,
applied to the stream/poll connections.useSingleConnection(boolean)
public void setFrequencyUnlimited(SubscribedTableKey key)
setMaxFrequency(com.lightstreamer.javameclient.midp.SubscribedTableKey, double)
.
This setting does not override constraints set by Lightstreamer
Server Metadata Adapter.
setMaxFrequency(com.lightstreamer.javameclient.midp.SubscribedTableKey, double)
for further notes.key
- Handle to a table as returned by any subscribeTable call.public void unsubscribeTable(SubscribedTableKey key)
key
- Handle to a table as returned by any subscribeTable call.java.lang.IllegalStateException
- Thrown in single connection mode if the
client is still connected (or connecting) to Lightstreamer Server.
In single connection mode, unsubscription requests can only be issued
while the client is disconnected; the remaining subscription requests
are then issued, together with the new connection request, upon the next
call to any openConnection/openPollingConnection.useSingleConnection(boolean)
public int sendMessage(MessageInfo message, SendMessageListener listener)
SendMessageListener
instance. Unless the return value is 0, one of those events will be eventually sent. Calls associated with
the same sequence are guaranteed to be issued in sequence.message
- An instance containing the message string to be interpreted by the Metadata Adapter, the sequence
this message has to be associated with and a delay timeout to be waited by the server for missing previous messages
to be received before being declared lost.listener
- A listener instance to receive a call representing the outcome of the message request.SendMessageListener.onAbort(com.lightstreamer.javameclient.midp.MessageInfo, int)
will be made.java.lang.IllegalStateException
- Thrown in any case in single connection mode.
In fact, sendMessage is not supported in single connection mode.useSingleConnection(boolean)
public void setMaxBandwidth(int maxBandwidth)
setBandwidthUnlimited()
method.
The limit can only be used in order to restrict the constraints
set by Lightstreamer Server Metadata Adapter.
ConnectionListener.onClientError(java.lang.String)
.
maxBandwidth
- Bandwidth constraint, in Kbit/sec,
applied to the stream/poll connections.useSingleConnection(boolean)
public void setBandwidthUnlimited()
setMaxBandwidth(int)
.
This setting does not override constraints set by Lightstreamer
Server Metadata Adapter.
setMaxBandwidth(int)
for further notes.public ConnectionProvider getConnectionProvider()
ConnectionProvider
instance.public void setConnectionProvider(ConnectionProvider connProvider)
ConnectionProvider
instance that will be
internally used to obtain Connection instances to communicate with Lightstreamer
server.connProvider
- The ConnectionProvider
instance to be used. If
not specified a simple implementation will be used. It must not be null.public java.lang.String getStatus()
public java.lang.String toString()
toString
in class java.lang.Object
public static void closeApp()