com.kuka.comm
Interface Connection

All Known Implementing Classes:

AbstractConnection, NetConnection, TcpConnection, UdpConnection

public interface Connection

A Connection represents a communication channel that can be used to send and receive messages (data objects). It links a local endpoint of the communication channel to another (local or remote) endpoint. The connection might either represent an input, output, or input and output connection.

Messages can be send by calling the send(java.lang.Object) method. To receive messages, MessageHandlers need to be added using the addMessageHandler(Class, MessageHandler) method. Each MessageHandler defines a a single callback method for a specific incoming message type (data object type).

Sending messages is only possible if an Encoder has been set, and, likewise, a Decoder has to be set to receive messages. Encoders transform a message into a representation that can be used by the underlying implementation of the communication channel to send the message over the channel. Decoders are the corresponding counterparts, that generate message objects from such a representation. For example, a TCP-based connection might need an Encoder that serializes the message into a byte array and a Decoder that deserializes the received bytes into a list of messages.

Connection objects initiate a new connection only after connect() has been called. A Connection cannot be used for waiting for incoming connections. For this, a Server needs to be started, that creates new Connection objects, that represent the local endpoint of an incoming connection. In short, Connections are used both for initiating a connection and communicating over a connection between communication endpoints, while a Server reacts to incoming connection requests by creating new Connection objects.

Method Summary

void	addConnectionListener(ConnectionListener listener) Adds a new ConnectionListener to the internal list notification subscribers.
<M> void	addMessageHandler(Class<M> messageClass, MessageHandler<M> handler) Generic method to append a MessageHandler for a message type to the internal list of message handlers.
boolean	awaitIsConnected(boolean expectedValue, long timeoutInMs) This method will block until {isConnected() returns the expected value or the timeout (in milliseconds) as been reached.
void	connect() Connects (or initiates) the connection asynchronously.
void	disconnect() Disconnects (or closes) the connection asynchronously.
ReconnectStrategy	getAutoReconnectStrategy() Returns the currently set auto reconnection strategy.
ConnectionStatistics	getStatistics() Returns general connection statistics about this connection.
boolean	hasDecoder() Returns true if a valid decoder has been set for this connection.
boolean	hasEncoder() Returns true if a valid encoder has been set for this connection.
boolean	isAbleToReceive() Returns true if the current state of the connection allows to receive messages.
boolean	isAbleToSend() Returns true if the current state of the connection allows to send messages.
boolean	isConnected() Returns true of the connection is working as expected.
boolean	isConnectionless() Checks if the underlying connection type implements a connectionless communication method.
void	removeConnectionListener(ConnectionListener listener) Removes a given listener from list of ConnectionListener.
<M> void	removeMessageHandler(Class<M> messageClass, MessageHandler<M> handler) Generic method to remove a message handler from internal list of message handlers.
void	send(Object msg) This method will send the message.
void	setAutoReconnectStrategy(ReconnectStrategy strategy) Sets the auto reconnection strategy.

Method Detail

awaitIsConnected

boolean awaitIsConnected(boolean expectedValue,
                         long timeoutInMs)

This method will block until {isConnected() returns the expected value or the timeout (in milliseconds) as been reached.

Parameters:

expectedValue - the expected value to wait for (true or false)

timeoutInMs - the maximum time (in milliseconds) to wait for the expected value

Returns:

True, if the connection is at the expected state within the timeout.

send

void send(Object msg)
          throws ConnectionException

This method will send the message. It blocks until the message has been sent.

The message type is Object to ensure that all kinds of messages can be send by the same interface. Type safety is ensured by the used Encoder, that must be able to handle the actual message type (i.e. serialize it correctly), otherwise the message will not be send.

Parameters:

msg - The message to be send.

Throws:

ConnectionException - if sending fails

connect

void connect()

Connects (or initiates) the connection asynchronously. The success of this method can be checked by calling isConnected(). Only a connected connection can be used for sending or receiving messages.

disconnect

void disconnect()

Disconnects (or closes) the connection asynchronously. The success of this method can be checked by calling isConnected(). A disconnected connection cannot be used for sending and will not receive any messages. A disconnected connection can be reconnected by calling connect().

isConnected

boolean isConnected()

Returns true of the connection is working as expected. The methods isAbleToSend() and isAbleToReceive() can be used to further check if sending or receiving of messages is possible.

Returns:

True, if the connection is connected and working as expected.

isAbleToSend

boolean isAbleToSend()

Returns true if the current state of the connection allows to send messages. For this, the connection at least must be connected (see also isConnected()) and an Encoder must have been set in the concrete class implementing the Connection interface. The method hasEncoder() can be used to check if an Encoder has been set.

Returns:

True, if the connection can be used to send messages.

isAbleToReceive

boolean isAbleToReceive()

Returns true if the current state of the connection allows to receive messages. For this, the connection at least must be connected (see also isConnected()) and an encoder must have been set. The method hasDecoder() can be used to check if a Decoder has been set.

Returns:

true, if the connection can be used to receive messages

hasEncoder

boolean hasEncoder()

Returns true if a valid encoder has been set for this connection.

Returns:

true if connection has an encoder, false otherwise.

hasDecoder

boolean hasDecoder()

Returns true if a valid decoder has been set for this connection.

Returns:

true if connection has a decoder, false otherwise.

isConnectionless

boolean isConnectionless()

Checks if the underlying connection type implements a connectionless communication method. If so, the method returns true. A connectionless connection will behave in a slightly different way than a connection-oriented connection, i.e. the connection will not be disconnected if the remote end point stops working properly. Further, the method isConnected() only ensures that the local setup is working properly but does not give any guarantees that the remote end point is working properly. Likewise, isAbleToSend() will refer to the state of the local setup, but it will not guarantee that the message will also be received or that the remote end point is even existing.

Returns:

true, if the connection implements a connectionless communication method, false otherwise

addMessageHandler

<M> void addMessageHandler(Class<M> messageClass,
                           MessageHandler<M> handler)

Generic method to append a MessageHandler for a message type to the internal list of message handlers. Its type parameter M is used to store different message classes and associated handlers.

Type Parameters:

M - the type of the message

Parameters:

messageClass - Defines the type of message for this handler so that the connection is able to choose the right handler for an incoming message

handler - The message handler to handle an incoming message.

removeMessageHandler

<M> void removeMessageHandler(Class<M> messageClass,
                              MessageHandler<M> handler)

Generic method to remove a message handler from internal list of message handlers. If a message handler doesn't exist this method does nothing.

Type Parameters:

M - the type of the message

Parameters:

messageClass - Defines the type of message for the associated handler

handler - message handler that handles incoming messages.

addConnectionListener

void addConnectionListener(ConnectionListener listener)

Adds a new ConnectionListener to the internal list notification subscribers.

An added listener will be notified if a connection event, like e.g. successful or failed establishment of connection, will occur.

Parameters:

listener - The ConnectionListener to add to listener list.

removeConnectionListener

void removeConnectionListener(ConnectionListener listener)

Removes a given listener from list of ConnectionListener. If there is no such listener in internal list nothing would be removed.

Parameters:

listener - The ConnectionListener to remove.

setAutoReconnectStrategy

void setAutoReconnectStrategy(ReconnectStrategy strategy)

Sets the auto reconnection strategy.

Parameters:

strategy - the strategy implementing the ReconnectStrategy

getAutoReconnectStrategy

ReconnectStrategy getAutoReconnectStrategy()

Returns the currently set auto reconnection strategy.

Returns:

The currently set auto reconnection strategy.

getStatistics

ConnectionStatistics getStatistics()

Returns general connection statistics about this connection.

Returns:

general connection statistics about this connection