com.lightstreamer.javameclient.midp
Class LSClient

java.lang.Object
  com.lightstreamer.javameclient.midp.LSClient

public class LSClient
extends java.lang.Object

Incapsulates a single connector to Lightstreamer Server. Since mobile's JVM have small capabilities, we advise to use only one instance of LSClient per MIDlet.

Nested Class Summary

static class

LSClient.Util Class Util.

Field Summary

static java.lang.String	CONNECTING String constant for the "connecting" status of LSClient: The Client is trying to reach Lightstreamer Server.
static boolean	isMidp2 Boolean value that can be tested to know whenever the application is running with MIDP 1.0 or MIDP 2.0 library.
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 Summary

LSClient()
Constructor LSClient.

Method Summary

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.
java.lang.String	getStatus() Inquiry method that gets the current client status.
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.
boolean	sendMessage(java.lang.String message) 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	setMaxBandwidth(int maxBandwidth) Request a new maximum bandwidth for the next/current connection.
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() Method toString.
void	unsubscribeTable(SubscribedTableKey key) Unsubscribes from a table previously subscribed to.
void	useReusableItemUpdates(boolean useReusable) This method establishes if the LSClient instance will use SimpleItemUpdate and ExtendedItemUpdate or ReusableSimpleItemUpdate and ReusableExtendedItemUpdate.
void	useSingleConnection(boolean useOneConnection) This method establish if LSClient will use one or more connections to comunicate with Lightstreamer Server.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OFF

public static final java.lang.String OFF

String constant for the "off" status of LSClient: The Client is waiting for connection commands.

See Also:

getStatus(), ConnectionListener.onStatusChange(String), Constant Field Values

CONNECTING

public static final java.lang.String CONNECTING

String constant for the "connecting" status of LSClient: The Client is trying to reach Lightstreamer Server.

See Also:

getStatus(), ConnectionListener.onStatusChange(String), Constant Field Values

STREAMING

public static final java.lang.String STREAMING

String constant for the "streaming" status of LSClient: The Client is receiving real-time updates from Lightstreamer Server.

See Also:

getStatus(), openConnection(ConnectionInfo, ConnectionListener), openConnection(ConnectionInfo, ConnectionListener, ConnectionPolicy), ConnectionListener.onStatusChange(String), Constant Field Values

STALLED

public static final 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.

See Also:

getStatus(), ConnectionListener.onStatusChange(String), ConnectionPolicy.setTimeoutForStalled(int), ConnectionPolicy.setKeepAliveInterval(int), Constant Field Values

POLLING

public static final java.lang.String POLLING

Represent the polling status of LSClient. The Client is polling a Lightstreamer Server. Note that this status represent both "standard" polling and "asynchronous" polling (AKA "smart" polling).

See Also:

getStatus(), openPollingConnection(ConnectionInfo, ConnectionListener), openPollingConnection(ConnectionInfo, ConnectionListener, ConnectionPolicy), ConnectionListener.onStatusChange(String), Constant Field Values

isMidp2

public static final boolean isMidp2

Boolean value that can be tested to know whenever the application is running with MIDP 1.0 or MIDP 2.0 library. The value is true if the embedded Lightstreamer Client Library is the MIDP 2.0 version.

See Also:

Constant Field Values

Constructor Detail

LSClient

public LSClient()

Constructor LSClient. Empty constructor

Method Detail

useSingleConnection

public void useSingleConnection(boolean useOneConnection)

This method establish if LSClient will use one or more connections to comunicate with Lightstreamer Server.
This selection should be made based on which kind of mobile phones you are targeting. Some older devices will not permit the use of multiple connections and actually there is no auto-recover for this case.
Note that if single connection mode is used, some limitations apply to the use of the API and the Stream-sense feature has a different behaviour. See each method for details.

Parameters:

useOneConnection - If true only one socket will be opened (default is false).

See Also:

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(String), ConnectionPolicy.setBufferedStreamingHandled(boolean)

useReusableItemUpdates

public void useReusableItemUpdates(boolean useReusable)

This method establishes if the LSClient instance will use SimpleItemUpdate and ExtendedItemUpdate or ReusableSimpleItemUpdate and ReusableExtendedItemUpdate.
If a 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.

Parameters:

useReusable - Use reusable objects or do not (default is true).

See Also:

SimpleItemUpdate, ExtendedItemUpdate, ReusableSimpleItemUpdate, ReusableExtendedItemUpdate

setBufferMax

public void setBufferMax(int bufferMax)

This method establishes how large the Client buffer must be. This buffer is used to store updates coming from the Server, while waiting for the Client application to handle them. When the buffer is full a call to ConnectionListener.onBufferFull() is issued and no more data is read from the connection until the buffer is empty.

Parameters:

bufferMax - The dimension of the client buffer (default is 10).

openPollingConnection

public void openPollingConnection(ConnectionInfo info,
                                  ConnectionListener listener)

Open a poll connection to the Server with the supplied parameters and default policies. If a connection is already open, it is closed first.

The Stream-sense feature is disabled, only poll connections will be used until a call to any openConnection is issued.

Parameters:

info - The connection parameters.

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.

Throws:

java.lang.IllegalStateException - Thrown in single connection mode if no tables are subscribed yet.

See Also:

ConnectionListener, ConnectionInfo, useSingleConnection(boolean)

Edition Note:

Connections from the MIDP2 Client Library are not supported by the Server, if it runs in Allegro edition.

Edition Note:

Connections from the MIDP2 Client Library are not supported by the Server, if it runs in Moderato edition.

openPollingConnection

public void openPollingConnection(ConnectionInfo info,
                                  ConnectionListener listener,
                                  ConnectionPolicy policy)

Open a poll connection to the Server with the supplied parameters and policies. If a connection is already open, it is closed first.

The Stream-sense feature is disabled, only poll connection will be used until a call to any openConnection is issued.

Parameters:

info - The connection parameters.

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.

Throws:

java.lang.IllegalStateException - Thrown in single connection mode if no tables are subscribed yet.

See Also:

ConnectionListener, ConnectionInfo, ConnectionPolicy, useSingleConnection(boolean)

Edition Note:

Connections from the MIDP2 Client Library are not supported by the Server, if it runs in Allegro edition.

Edition Note:

Connections from the MIDP2 Client Library are not supported by the Server, if it runs in Moderato edition.

openConnection

public void openConnection(ConnectionInfo info,
                           ConnectionListener listener)

Open a stream connection to the Server with the supplied parameters and default policies. If a connection is already open, it is closed first.

The Stream-sense feature is enabled, if the network infrastructure is not able to sustain streaming then the Client will switch to polling mode.

Parameters:

info - The connection parameters.

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.

Throws:

java.lang.IllegalStateException - Thrown in single connection mode if no tables are subscribed yet.

See Also:

ConnectionListener, ConnectionInfo, useSingleConnection(boolean)

Edition Note:

Connections from the MIDP2 Client Library are not supported by the Server, if it runs in Allegro edition.

Edition Note:

Connections from the MIDP2 Client Library are not supported by the Server, if it runs in Moderato edition.

openConnection

public void openConnection(ConnectionInfo info,
                           ConnectionListener listener,
                           ConnectionPolicy policy)

Open a stream connection to the Server with the supplied parameters and policies. If a connection is already open, it is closed first.

The Stream-sense feature is enabled, if the network infrastructure is not able to sustain streaming then the Client will switch to polling mode.

Parameters:

info - The connection parameters.

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.

Throws:

java.lang.IllegalStateException - Thrown in single connection mode if no tables are subscribed yet.

See Also:

ConnectionListener, ConnectionInfo, ConnectionPolicy, useSingleConnection(boolean)

Edition Note:

Connections from the MIDP2 Client Library are not supported by the Server, if it runs in Allegro edition.

Edition Note:

Connections from the MIDP2 Client Library are not supported by the Server, if it runs in Moderato edition.

closeConnection

public void closeConnection()

Closes the connection to the Server, if one is open.

subscribeTable

public SubscribedTableKey subscribeTable(ExtendedTableInfo info,
                                         ExtendedTableListener tListener)

Subscribes to a table through the Server.
The table is specified by providing item and field names. This requires that a LiteralBasedProvider or equivalent Metadata Adapter is configured on the Server, in order to understand the request.
A fast, though basic, listener interface is provided. The listener only gets low level notifications of changed field values received from the Server.
A distinct listener must be used for any distinct call.

Parameters:

info - Contains the specification and request parameters of the table to subscribe to.

tListener - Receives notification of data updates and other messages related to this subscription.

Returns:

A handle to the subscribed table, to be used for unsubscription.

Throws:

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.

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.

See Also:

useSingleConnection(boolean)

subscribeTable

public SubscribedTableKey subscribeTable(SimpleTableInfo info,
                                         SimpleTableListener tListener)

Subscribes to a table through the Server.
The table is specified by group name and schema name. Specific item and field names have to be determined by the Metadata Adapter.
A fast, though basic, listener interface is provided. The listener only gets low level notifications of changed field values received from the Server. Specific items and fields are identified by positional information, as item and field names are not known.
A distinct listener must be used for any distinct call.

Parameters:

info - Contains the specification and request parameters of the table to subscribe to.

tListener - Receives notification of data updates and other messages related to this subscription.

Returns:

A handle to the subscribed table, to be used for unsubscription.

Throws:

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.

See Also:

useSingleConnection(boolean)

subscribeTable

public SubscribedTableKey subscribeTable(ExtendedTableInfo info,
                                         HandyTableListener tListener,
                                         boolean commandLogic)

Subscribes to a table through the Server.
The table is specified by providing item and field names. This requires that a LiteralBasedProvider or equivalent Metadata Adapter is configured on the Server, in order to understand the request.
A fully-featured listener interface is provided.
A distinct listener must be used for any distinct call.

Parameters:

info - Contains the specification and request parameters of the table to subscribe to.

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.

Returns:

A handle to the subscribed table, to be used for unsubscription.

Throws:

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.

See Also:

useSingleConnection(boolean)

subscribeTable

public SubscribedTableKey subscribeTable(SimpleTableInfo info,
                                         HandyTableListener tListener,
                                         boolean commandLogic)

Subscribes to a table through the Server.
The table is specified by group name and schema name. Specific item and field names have to be determined by the Metadata Adapter.
A fully-featured listener interface is provided. However, specific items and fields are identified to the listener only by positional information, as item and field names are not known.
A distinct listener must be used for any distinct call.

Parameters:

info - Contains the specification and request parameters of the table to subscribe to.

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.

Returns:

A handle to the subscribed table, to be used for unsubscription.

Throws:

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.

See Also:

useSingleConnection(boolean)

unsubscribeTable

public void unsubscribeTable(SubscribedTableKey key)

Unsubscribes from a table previously subscribed to. If the request fails, the table will be probably unsubscribed anyway.

Parameters:

key - Handle to a table as returned by any subscribeTable call.

Throws:

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.

See Also:

useSingleConnection(boolean)

sendMessage

public boolean sendMessage(java.lang.String message)

Send a message to Lightstreamer Server. The message is associated to the current session and is interpreted and managed by the Metadata Adapter related to the session.
Note that messages are sent to the Server asynchronously with respect to the Client thread. If the server session ends before the message is sent, then that message will never reach the Server. Any problem preventing the message from being processed will be notified through ConnectionListener.onClientError(java.lang.String).

Parameters:

message - Any text string, to be interpreted by the Metadata Adapter. It should not be null.

Returns:

true if a session is open; false in the other case.

Throws:

java.lang.IllegalStateException - Thrown in any case in single connection mode. In fact, sendMessage is not supported in single connection mode.

See Also:

useSingleConnection(boolean)

setMaxBandwidth

public void setMaxBandwidth(int maxBandwidth)

Request a new maximum bandwidth for the next/current connection. The new limit overrides any previous limit, even if set through a call to setBandwidthUnlimited() method. The limit can only be used in order to restrict the constraints set by Lightstreamer Server Metadata Adapter.
Note that, if the session is already active, the request is sent to the Server asynchronously with respect to the Client thread. Any problem preventing the request from reaching the Server will be notified through ConnectionListener.onClientError(java.lang.String).
Note: if single connection mode is used and the session is already active, the new bandwidth limit will only apply to the next session. The limit may be applied to current session only in case a new rebind connection happens to be issued for the current session (as in case of polling).

Parameters:

maxBandwidth - Bandwidth constraint, in Kbit/sec, applied to the stream/poll connections.

See Also:

useSingleConnection(boolean)

setBandwidthUnlimited

public void setBandwidthUnlimited()

Request unlimited bandwidth for the next/current connection. This call will override any limits previously set through a call to setMaxBandwidth(int). This setting does not override constraints set by Lightstreamer Server Metadata Adapter.
See setMaxBandwidth(int) for further notes.

getStatus

public java.lang.String getStatus()

Inquiry method that gets the current client status.

Returns:

The current client status. It can be one of the following values:

OFF

CONNECTING

POLLING

STREAMING

STALLED

toString

public java.lang.String toString()

Method toString.

Overrides:

toString in class java.lang.Object

Returns:

a string representing the LSClient object and his actual state

closeApp

public static void closeApp()

Calling this method will stops all the LSClient's thread. This is planned to be used on the MIDlet's destroyApp method.