com.lightstreamer.javameclient.midp

Interface ConnectionListener

public interface ConnectionListener

Receives notifications of connection activity and errors.
The listener is called directly from the worker threads. The method implementations should be fast and nonblocking. Any slow operations should be enqueued and performed asynchronously.

Method Summary

Modifier and Type	Method and Description
void	onBufferFull() Notification that the local buffer is full and no more data will be read until the buffer is empty.
void	onClientError(java.lang.String error) Notification of a Client error.
void	onConnectionEnd(int cause) Notification of the closure of the Connection because of a Server decision.
void	onServerError(int code, java.lang.String msg) Notification that the Server has refused a connection request because of the constraints imposed by the Metadata Adapter or by Server configuration.
void	onStatusChange(java.lang.String newStatus) Notification of each time the client status has changed.

Method Detail

onStatusChange

void onStatusChange(java.lang.String newStatus)

Notification of each time the client status has changed. Handle this event to perform actions related to connection and disconnection occurrences.

Parameters:

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

LSClient.OFF

LSClient.CONNECTING

LSClient.POLLING

LSClient.STREAMING

LSClient.STALLED

See Also:

LSClient.getStatus()

onBufferFull

void onBufferFull()

Notification that the local buffer is full and no more data will be read until the buffer is empty. Receiving this notification too frequently indicates that there is too much data respect what the client hardware can handle.

See Also:

LSClient.setBufferMax(int), LSClient.setMaxBandwidth(int), SimpleTableInfo.setRequestedMaxFrequency(double)

onServerError

void onServerError(int code,
                   java.lang.String msg)

Notification that the Server has refused a connection request because of the constraints imposed by the Metadata Adapter or by Server configuration. A detailed error code is supplied. Both the error code and the message are received from the Server. In particular:

• A positive error code is issued by the Server after checking the request against the constraints imposed by the Metadata Adapter or by its own configuration. See the text protocol documentation for a reference of the error codes that can be issued in response to stream/poll requests.
• The special error code 19 is issued by the Server if single connection mode is used and the connection request fails because of an error in the subscription part of the request; a detailed error code is not available in this case.
• A zero or negative error code is issued directly by the Metadata Adapter because of capability restrictions that may be applied to the specific user.

As a consequence of the event, the connection status will be switched to LSClient.OFF and no automatic reconnection attempt will be performed.
By handling the event, it is possible to perform recovery actions. Note that setting the status to LSClient.OFF is needed before trying a reconnection. In case the connection status is changed in the handler, no further switch to LSClient.OFF status will be performed.

Parameters:

code - The detailed error code, as received from the Server. Its meaning depends on Lightstreamer Server or the Metadata Adapter.

msg - An error detail message, sent by Lightstreamer Server or by the Metadata Adapter.

See Also:

SimpleTableListener.onControlError(int, java.lang.String), ExtendedTableListener.onControlError(int, java.lang.String), HandyTableListener.onControlError(int, java.lang.String)

onConnectionEnd

void onConnectionEnd(int cause)

Notification of the closure of the Connection because of a Server decision. As a consequence, the connection status will be switched to LSClient.OFF and no automatic reconnection attempt will be performed.
Upon this notification, it is possible to perform recovery actions, such as trying a reconnection (though it may be advisable not to try a new connection immediately). Note that setting the status to LSClient.OFF is needed before trying a reconnection. In case the connection status is changed in the handler, no further switch to LSClient.OFF status will be performed.

Parameters:

cause - An integer code that describes the cause of the connection ending or 0 if no cause information is supplied. See the "END" message in the text protocol documentation for details on the possible causes.

onClientError

void onClientError(java.lang.String error)

Notification of a Client error. The error could be:

• A wrap of an exception thrown by a listener method (ConnectionListener, SimpleTableListener, ExtendedTableListener, HandyTableListener) (note that this method is the only one not wrapped, so an exception thrown by this method could block the entire client).
• An error occurred while connecting to the Server for a stream/poll connection.
• An error occurred while connecting to the Server in order to either request a subscription/unsubscription, send a message or change the bandwidth limits.
• An unexpected answer from the Server for a stream/poll connection (this condition should never occur).
• An unexpected answer from the Server upon a request to either perform a subscription/unsubscription, send a message or change the bandwidth limits (this condition should never occur).
• A refusal by the Server to accomplish an unsubscription request (this condition should never occur).

Error conditions of these kinds don't stop the processing. In any case of an unsuccessful stream/poll attempt, the library will perform further attempts, using the timeout configured through ConnectionPolicy.setRetryTimeout(int). In any other cases of unsuccessful requests to the Server, no further attempts will be performed.
The notification is only provided for diagnostic purposes; it is not meant as a way to make specific recovery actions possible.

Parameters:

error - A string representing the error occurred.

See Also:

LSClient.setBandwidthUnlimited(), LSClient.setMaxBandwidth(int), LSClient.sendMessage(MessageInfo,SendMessageListener)