public class LSClient
extends java.lang.Object
Constructor and Description |
---|
LSClient()
Empty constructor.
|
Modifier and Type | Method and Description |
---|---|
MpnSubscription |
activateMpn(MpnInfo mpnInfo,
boolean coalescing)
Activates a mobile push notification (MPN) subscription for specific table and with a specific format.
|
void |
batchRequests(int batchSize)
Signals that the next subscription and unsubscription requests can be
accumulated and sent to Lightstreamer Server with a single connection.
|
void |
changeConstraints(ConnectionConstraints constraints)
Requests new constraints to be applied on the overall data flow
from the current connection.
|
void |
changeSubscription(SubscribedTableKey tableKey,
SubscriptionConstraints constraints)
Dynamically changes subscription parameters on a table previously
subscribed to the Server.
|
void |
changeSubscriptions(SubscribedTableKey[] tableKeys,
SubscriptionConstraints constraints)
Dynamically changes subscription parameters on a set of tables previously
subscribed to the Server.
|
void |
closeBatch()
Closes a pending batch.
|
void |
closeConnection()
Closes the connection to the Server, if one is open.
|
void |
deactivateAllMpn()
Deactivates all the MPN subscriptions for this device and application.
|
void |
deactivateMpn(MpnSubscriptionStatus status)
Deactivates mobile push notification (MPN) subscriptions with the specified status.
|
void |
forceUnsubscribeTable(SubscribedTableKey tableKey)
Tries to unsubscribe from a table for which a previous unsubscribe
has been called but an exception has been received.
|
MpnSubscription |
getCachedMpnSubscription(MpnKey mpnKey)
Looks up the details of a mobile push notification (MPN) subscription in the local cache, with the specified MPN key.
|
java.util.List<MpnSubscription> |
getCachedMpnSubscriptions()
Looks up the details of mobile push notification (MPN) subscriptions currently stored in the local cache.
|
java.util.List<MpnSubscription> |
inquireAllMpn()
Inquires the details of all mobile push notification (MPN) subscriptions of this device and application.
|
MpnSubscription |
inquireMpn(MpnKey mpnKey)
Inquires the details of a mobile push notification (MPN) subscription with the specified MPN key.
|
java.util.List<MpnSubscription> |
inquireMpn(MpnSubscriptionStatus status)
Inquires the details of mobile push notification (MPN) subscriptions with the specified status.
|
void |
openConnection(ConnectionInfo info,
ConnectionListener listener)
Opens a connection to the Server with the supplied parameters.
|
static void |
registerForMpn(android.content.Context appContext,
java.lang.String senderId,
MpnRegistrationListener listener)
Registers the current device and application on the GCM service, obtaining an appropriate registration ID for
subsequent calls related to mobile push notifications (MPN).
|
int |
sendMessage(MessageInfo message,
SendMessageListener listener)
Send a message to Lightstreamer Server.
|
void |
sendMessage(java.lang.String message)
Sends a message to Lightstreamer Server.
|
SubscribedTableKey[] |
subscribeItems(ExtendedTableInfo items,
HandyTableListener listener)
Subscribes to a set of items, which share the same schema and other
subscription parameters.
|
SubscribedTableKey |
subscribeTable(ExtendedTableInfo table,
HandyTableListener listener,
boolean commandLogic)
Subscribes to a table through the Server.
|
SubscribedTableKey |
subscribeTable(SimpleTableInfo table,
HandyTableListener listener,
boolean commandLogic)
Subscribes to a table through the Server.
|
void |
unbatchRequest()
Signals that one of the requests previously scheduled for batching
is no longer going to be issued.
|
void |
unsubscribeTable(SubscribedTableKey tableKey)
Unsubscribes from a table previously subscribed to the Server.
|
void |
unsubscribeTables(SubscribedTableKey[] tableKeys)
Unsubscribes from a set of tables previously subscribed to the Server.
|
public void openConnection(ConnectionInfo info, ConnectionListener listener) throws PushConnException, PushServerException, PushUserException
ConnectionInfo
parameter. By the way, these settings will also apply
to connections used for subscriptions and other control requests.info
- Contains the Server address and the connection parameters.
A copy of the object is stored internally.listener
- Receives notification for connection events.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer.
In normal operation, this should not happen.PushUserException
- Thrown in case the Server has refused
the connection request because of the constraints imposed by the
Metadata Adapter or by Server configuration.public void closeConnection()
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.public void sendMessage(java.lang.String message) throws PushConnException, PushServerException, PushUserException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.
sendMessage(MessageInfo, SendMessageListener)
to send a batch of messagesmessage
- Any text string, to be interpreted by the Metadata
Adapter. It should not be null.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer.
In normal conditions, this exception should never happen.PushUserException
- Thrown in case the Server has refused
the message because of the constraints imposed by the Metadata Adapter
or by Server configuration.public int sendMessage(MessageInfo message, SendMessageListener listener) throws PushConnException, PushServerException, PushUserException
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.ls_client.MessageInfo, int, java.lang.Exception)
will be made.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer.
In normal conditions, this exception should never happen.PushUserException
- Thrown in case the Server has refused
the message because of the constraints imposed by the Metadata Adapter
or by Server configuration.public void changeConstraints(ConnectionConstraints constraints) throws PushConnException, PushServerException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.constraints
- Collects available constraints.
It should not be null; to unset all
constraints, use an empty structure, instead.
A copy of the object is stored internally.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer.
In normal conditions, this exception should never happen.public SubscribedTableKey subscribeTable(SimpleTableInfo table, HandyTableListener listener, boolean commandLogic) throws SubscrException, PushServerException, PushUserException, PushConnException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.table
- Contains the specification and request parameters
of the table to subscribe to.listener
- Receives notification of data updates and subscription
termination.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.SubscrException
- Thrown if the connection is closed.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer.
In normal conditions, this exception should never happen.PushUserException
- Thrown in case the subscription was refused
after the checks in Lightstreamer Server Metadata Adapter.public SubscribedTableKey subscribeTable(ExtendedTableInfo table, HandyTableListener listener, boolean commandLogic) throws SubscrException, PushServerException, PushUserException, PushConnException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.table
- Contains the specification and request parameters
of the table to subscribe to.
A copy of the object is stored internally.listener
- Receives notification of data updates and subscription
termination.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.SubscrException
- Thrown if the connection is closed.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer.
In normal conditions, this exception should never happen.PushUserException
- Thrown in case the subscription was refused
after the checks in Lightstreamer Server Metadata Adapter.public SubscribedTableKey[] subscribeItems(ExtendedTableInfo items, HandyTableListener listener) throws SubscrException, PushServerException, PushUserException, PushConnException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.items
- Contains the specification and request parameters
of the items to subscribe to. The structure is the same as that used in
subscribeTable, but the items will not be subscribed to as a table.
A copy of the object is stored internally.listener
- Receives notification of data updates and subscription
termination.SubscrException
- Thrown if the connection is closed.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer. In this case, some zombie subscriptions
may remain in the Server.
In normal conditions, this exception should never happen.PushUserException
- Thrown in case the subscription was refused
after the checks in Lightstreamer Server Metadata Adapter.public void changeSubscription(SubscribedTableKey tableKey, SubscriptionConstraints constraints) throws SubscrException, PushServerException, PushConnException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details
on timeout settings. This kind of request is not included in a batch.tableKey
- Handle to a table as returned by a subscribe* call.constraints
- Collects available constraints. It should not be null.SubscrException
- Thrown if the supplied table is not currently
subscribed. This occurs also if the table has already been unsubscribed
or the connection has already been closed; this may not be a problem
from the client's point of view.PushConnException
- Thrown in case of connection problems.
In this case, the request may or may not have been fulfilled by the Server.PushServerException
- Thrown in case the Server refuses the request.public void changeSubscriptions(SubscribedTableKey[] tableKeys, SubscriptionConstraints constraints) throws SubscrException, PushServerException, PushConnException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details
on timeout settings. This kind of request is not included in a batch.tableKeys
- Array of handles to tables as returned by one or more
subscribe* calls.constraints
- Collects available constraints. It should not be null.SubscrException
- Thrown if the connection has already been
closed; this may not be a problem from the client's point of view.PushConnException
- Thrown in case of connection problems.
In this case, the request may or may not have been fulfilled by the Server.PushServerException
- Thrown in case the Server refuses the request.
Note that if changing the max frequency and any of the involved tables
has been subscribed to as unfiltered, the whole request will be refused.
Including any tables already unsubscribed from the Server may also cause
this exception; in this case, the request may have been partially fulfilled.public void unsubscribeTable(SubscribedTableKey tableKey) throws SubscrException, PushServerException, PushConnException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.tableKey
- Handle to a table as returned by a subscribe* call.SubscrException
- Thrown if the supplied table is not currently
subscribed. This occurs also if the table has already been unsubscribed
or the connection has already been closed; this may not be a problem
from the client's point of view.PushConnException
- Thrown in case of connection problems.
In this case, a zombie subscription will probably remain in the Server.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer. In this case, a zombie subscription
may remain in the Server.
In normal conditions, this exception should never happen.public void unsubscribeTables(SubscribedTableKey[] tableKeys) throws SubscrException, PushServerException, PushConnException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.tableKeys
- Array of handles to tables as returned by one
or more subscribe* calls.SubscrException
- Thrown if the connection has already been
closed; this may not be a problem from the client's point of view.PushConnException
- Thrown in case of connection problems.
In this case, zombie subscriptions will probably remain in the Server.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer. In this case, some zombie subscriptions
may remain in the Server.
In normal conditions, this exception should never happen.public void forceUnsubscribeTable(SubscribedTableKey tableKey) throws SubscrException, PushServerException, PushConnException
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details
on timeout settings. This kind of request is not included in a batch.tableKey
- Handle to a table as returned by a subscribe* call.SubscrException
- Thrown if the connection has already been
closed or the supplied table is currently subscribed. In this case,
there wasn't a zombie subscription in the Server for the supplied
table.PushConnException
- Thrown in case of connection problems.
In this case, nothing has changed in the Server.PushServerException
- Thrown in case of errors in the supplied
parameters or in Server answer. In this case there wasn't a zombie
subscription in the Server for the supplied table.public void batchRequests(int batchSize) throws SubscrException
batchSize
- number of incoming subscription and unsubscription
requests that can be batched. A zero value means an unlimited number
of requests (the batch must be closed by calling closeBatch).SubscrException
- Thrown if the connection is currently closed.public void unbatchRequest()
public void closeBatch()
public static void registerForMpn(android.content.Context appContext, java.lang.String senderId, MpnRegistrationListener listener) throws MpnRegistrationException
MpnRegistrationListener
.
SharedPreferences
storage, and is checked whether it is
new, changed or unchanged. If the registration ID is changed and there is at least one instance of LSClient
connected,
it will try to change the registration ID on the Server. If there are no instances connected, the registration ID change
on the Server will be scheduled and tried when the first instance connects. The subsequent result of the update try
will be delivered through appropriate events of the MpnRegistrationListener
. If successful, the registration ID change
may automatically reactivate previously suspended MPN subscriptions. An MPN subscription may become suspended when GCM service APIs
reports a registration ID as invalidated.
appContext
- the context of your application (usually obtained through getApplicationContext()
).senderId
- the project number associated with your application (may be obtained through Google's Developer Console).listener
- the listener that will receive the results of the registration and of the registration ID change (if needed).MpnRegistrationException
- Thrown in case the necessary Android APIs (in particular Google Play Services) are not present
or not available.public MpnSubscription activateMpn(MpnInfo mpnInfo, boolean coalescing) throws SubscrException, PushServerException, PushUserException, PushConnException
MpnInfo
.
MPNs can be sent each time the table updates or only one time when a specific trigger passes evaluation.
MpnSubscription.deactivate()
,
deactivateMpn(com.lightstreamer.ls_client.mpn.MpnSubscriptionStatus)
, or deactivateAllMpn()
(within the current Session or any other one).
In special cases, the subscription may be forcibly deactivated on the Server side.
RAW
mode, COMMAND
mode, unfiltered dispatch and snapshot are not available with MPN subscriptions;
selector
field of SimpleTableInfo
field is ignored (but a trigger may be set in the triggerExpression
field of MpnInfo
, see for more information).
coalescing
flag is set, two activations with the same Adapter Set, Data Adapter, group, schema and trigger
expression are actually considered the same MPN subscription. Activating two such subscriptions will result in the second activation
returning an {link MpnSubscription} instance related with the first activation (remind that MPN subscriptions are persistent, hence the first
subscription may have been issued within a different Session). If other activation parameters, such as the data
field of MpnInfo
, are specified differently,
this will also cause the MPN subscription to be modified. As another consequence, if the subscription has a trigger and is currently
in triggered state, by activating again the subscription it will return to the active state (see MpnSubscriptionStatus
).
coalescing
flag is not set, two activations are always considered different MPN subscriptions, whatever the Adapter Set,
Data Adapter, group, schema and trigger expression are set.
coalescing
flag is to allow simple apps to always activate their MPN subscriptions
when the app starts, without worrying about receiving the related notifications multiple times because the same subscriptions
might have been issued in previous runs of the app.
MpnSubscription
description for more information.
This method always contacts the Server and updates the related MPN subscription in the local cache.
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.mpnInfo
- Contains the table and format specifications of the mobile push notifications to be activated. A copy of the object is stored internally.coalescing
- If set, two activations with the same Adapter Set, Data Adapter, group, schema and trigger
expression are actually considered the same MPN subscription. If not set, two such activations are considered
different MPN subscriptions.SubscrException
- Thrown if the connection is closed, or in case the parameters specify invalid or conflicting values.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in Server response. In normal conditions, this exception should never happen.PushUserException
- Thrown in case the operation has been refused by the Lightstreamer Server.public MpnSubscription inquireMpn(MpnKey mpnKey) throws SubscrException, PushServerException, PushUserException, PushConnException
MpnSubscription
object
is returned, with the details about the MPN subscription.
PushServerException
with error code 46 (subscription unknown) or 45 (device unknown, if no more subscriptions exist for this device and application).
MpnSubscription
description for more information.
This method always contacts the Server and updates the related MPN subscription in the local cache.
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.mpnKey
- A key to an active MPN subscription (possibly obtained within a different Session).MpnSubscription
object with the details the specified MPN subscription.SubscrException
- Thrown if the connection is closed, or in case the parameters specify invalid values.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in Server response. In normal conditions, this exception should never happen.PushUserException
- Thrown in case the operation has been refused by the Lightstreamer Server.public java.util.List<MpnSubscription> inquireAllMpn() throws SubscrException, PushServerException, PushUserException, PushConnException
MpnSubscription
objects is returned,
with the details about each MPN subscription.
MpnSubscription
description for more information.
This method always contacts the Server and updates the whole state of the local cache.
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.MpnSubscription
objects with the details for all MPN subscriptions.SubscrException
- Thrown if the connection is closed.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in Server response. In normal conditions, this exception should never happen.PushUserException
- Thrown in case the operation has been refused by the Lightstreamer Server.public java.util.List<MpnSubscription> inquireMpn(MpnSubscriptionStatus status) throws SubscrException, PushServerException, PushUserException, PushConnException
MpnSubscription
objects is
returned, with the details about each MPN subscription.
MpnSubscription
description for more information.
This method always contacts the Server and updates the involved MPN subscriptions in the local cache.
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.status
- An MPN subscription status.MpnSubscription
objects with the details for all MPN subscriptions in the specified status for this device and application.SubscrException
- Thrown if the connection is closed, or in case the parameters specify invalid or conflicting values.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in Server response. In normal conditions, this exception should never happen.PushUserException
- Thrown in case the operation has been refused by the Lightstreamer Server.public MpnSubscription getCachedMpnSubscription(MpnKey mpnKey)
MpnSubscription
object is returned, with the details about the MPN subscription, otherwise null is returned.
MpnSubscription
description.
This method never contacts the Server and does not update the local cache.
mpnKey
- A key to an active MPN subscription (possibly obtained within a different Session).MpnSubscription
object with the details the specified MPN subscription,
or null if the MPN subscription can not be found in the local cache.public java.util.List<MpnSubscription> getCachedMpnSubscriptions()
MpnSubscription
objects is returned, with the details about each MPN subscription.
MpnSubscription
description.
This method never contacts the Server and does not update the local cache.
MpnSubscription
objects with the details for all MPN subscriptions stored in the local cache.public void deactivateAllMpn() throws SubscrException, PushServerException, PushUserException, PushConnException
PushUserException
with error code 46 (subscription unknown)
or 45 (device unknown, if no more subscriptions exist for this device and application).
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.SubscrException
- Thrown if the connection is closed.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in Server response. In normal conditions, this exception should never happen.PushUserException
- Thrown in case the operation has been refused by the Lightstreamer Server.public void deactivateMpn(MpnSubscriptionStatus status) throws SubscrException, PushServerException, PushUserException, PushConnException
PushUserException
with error code 46 (subscription unknown)
or 45 (device unknown, if no more subscriptions exist for this device and application).
openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener)
for details on timeout settings.status
- An MPN subscription status.SubscrException
- Thrown if the connection is closed, or in case the parameters specify invalid or conflicting values.PushConnException
- Thrown in case of connection problems.PushServerException
- Thrown in case of errors in Server response. In normal conditions, this exception should never happen.PushUserException
- Thrown in case the operation has been refused by the Lightstreamer Server.