net.sf.xenqtt.message
Interface ChannelManager

All Known Implementing Classes:

ChannelManagerImpl

public interface ChannelManager

Specifies a type that manages zero or more channels that communicate via the MQTT protocol.

All of the methods in this specification are thread-safe. Implementations may be blocking or non-blocking

Method Summary

void	cancelBlockingCommands(MqttChannelRef channel) Cancels all blocking commands for the specified channel.
void	close(MqttChannelRef channel) Closes the specified channel.
void	close(MqttChannelRef channel, Throwable cause) Closes the specified channel and sends cause to the MessageHandler.channelClosed(MqttChannel, Throwable) callback.
List<MqttMessage>	getUnsentMessages(MqttChannelRef channel)
void	init() Starts this channel manager.
boolean	isRunning()
MqttChannelRef	newBrokerChannel(SocketChannel socketChannel, MessageHandler messageHandler) Create a new broker side MqttChannelRef for use in exchanging data using the MQTT protocol.
MqttChannelRef	newClientChannel(String host, int port, MessageHandler messageHandler) Create a new client side MqttChannelRef for use in exchanging data using the MQTT protocol.
MqttChannelRef	newClientChannel(String brokerUri, MessageHandler messageHandler) Create a new client side MqttChannelRef for use in exchanging data using the MQTT protocol.
MqttChannelRef	newClientChannel(URI brokerUri, MessageHandler messageHandler) Create a new client side MqttChannelRef for use in exchanging data using the MQTT protocol.
<T extends MqttMessage> T	send(MqttChannelRef channel, MqttMessage message) Send a message over a specified channel.
void	shutdown() Stops this channel manager.
void	transfer(MqttChannelRef oldChannel, MqttChannelRef newChannel) Transfers unsent messages from oldChannel to newChannel and changes oldChannel such that any messages sent to it will actually go to newChannel.

Method Detail

newClientChannel

MqttChannelRef newClientChannel(String brokerUri,
                                MessageHandler messageHandler)
                                throws MqttCommandCancelledException,
                                       MqttTimeoutException,
                                       MqttInterruptedException

Create a new client side MqttChannelRef for use in exchanging data using the MQTT protocol. This is the client end of the connection. The broker will have the remote end of the connection. This method only blocks long enough for the channel to be created, not for the TCP connection to happen.

Parameters:

brokerUri - URI of the broker to connect to. For example, tcp://q.m2m.io:1883.

messageHandler - The message handler to use for all received messages

Returns:

The newly-created channel. The channel may only be safely accessed from the MessageHandler callback methods.

Throws:

MqttCommandCancelledException - The channel manager uses a command pattern to process this request on the IO thread. If the command is cancelled for some reason, like the channel closes, this exception is thrown.

MqttTimeoutException - Thrown when using a synchronous implementation and the timeout specified for a blocked method expires

MqttInterruptedException - Thrown when the calling thread is interrupted

newClientChannel

MqttChannelRef newClientChannel(URI brokerUri,
                                MessageHandler messageHandler)
                                throws MqttCommandCancelledException,
                                       MqttTimeoutException,
                                       MqttInterruptedException

Create a new client side MqttChannelRef for use in exchanging data using the MQTT protocol. This is the client end of the connection. The broker will have the remote end of the connection. This method only blocks long enough for the channel to be created, not for the TCP connection to happen. This will throw a RuntimeException wrapping any exception thrown while initializing the connection like UnresolvedAddressException

Parameters:

brokerUri - URI of the broker to connect to. For example, tcp://q.m2m.io:1883.

messageHandler - The message handler to use for all received messages

Returns:

The newly-created channel. The channel may only be safely accessed from the MessageHandler callback methods.

Throws:

MqttCommandCancelledException - The channel manager uses a command pattern to process this request on the IO thread. If the command is cancelled for some reason, like the channel closes, this exception is thrown.

MqttTimeoutException - Thrown when using a synchronous implementation and the timeout specified for a blocked method expires

MqttInterruptedException - Thrown when the calling thread is interrupted

newClientChannel

MqttChannelRef newClientChannel(String host,
                                int port,
                                MessageHandler messageHandler)
                                throws MqttCommandCancelledException,
                                       MqttTimeoutException,
                                       MqttInterruptedException

Create a new client side MqttChannelRef for use in exchanging data using the MQTT protocol. This is the client end of the connection. The broker will have the remote end of the connection. This method only blocks long enough for the channel to be created, not for the TCP connection to happen. This will throw a RuntimeException wrapping any exception thrown while initializing the connection like UnresolvedAddressException

Parameters:

host - The host name to connect to

port - The port to connect to

messageHandler - The message handler to use for all received messages

Returns:

The newly-created channel. The channel may only be safely accessed from the MessageHandler callback methods.

Throws:

MqttCommandCancelledException - The channel manager uses a command pattern to process this request on the IO thread. If the command is cancelled for some reason, like the channel closes, this exception is thrown.

MqttTimeoutException - Thrown when using a synchronous implementation and the timeout specified for a blocked method expires

MqttInterruptedException - Thrown when the calling thread is interrupted

newBrokerChannel

MqttChannelRef newBrokerChannel(SocketChannel socketChannel,
                                MessageHandler messageHandler)
                                throws MqttCommandCancelledException,
                                       MqttTimeoutException,
                                       MqttInterruptedException

Create a new broker side MqttChannelRef for use in exchanging data using the MQTT protocol. This is the broker end of the connection. The client will have the remove end of the connection. If an exception is thrown the socketChannel will be closed. This method only blocks long enough for the channel to be created.

Parameters:

socketChannel - The channel to communicate over

messageHandler - The message handler to use for all received messages

Returns:

The newly-created channel.The channel may only be safely accessed from the MessageHandler callback methods.

Throws:

MqttCommandCancelledException - The channel manager uses a command pattern to process this request on the IO thread. If the command is cancelled for some reason, like the channel closes, this exception is thrown.

MqttTimeoutException - Thrown when using a synchronous implementation and the timeout specified for a blocked method expires

MqttInterruptedException - Thrown when the calling thread is interrupted

send

<T extends MqttMessage> T send(MqttChannelRef channel,
                               MqttMessage message)
                           throws MqttCommandCancelledException,
                                  MqttTimeoutException,
                                  MqttInterruptedException

Send a message over a specified channel. This method only blocks until the message is queued to send to the channel.

Parameters:

channel - The channel to send the message over. This channel should have been previously created via the #newChannel(String, int, MessageHandler) or #newChannel(SocketChannel, MessageHandler) methods

message - The message to send. This can be any type of MQTT message

Returns:

In a synchronous implementation this returns the ack message if the message being sent is a ConnectMessage or has a QoS > 0.

Throws:

MqttCommandCancelledException - The channel manager uses a command pattern to process this request on the IO thread. If the command is cancelled for some reason, like the channel closes, this exception is thrown.

MqttTimeoutException - Thrown when using a synchronous implementation and the timeout specified for a blocked method expires

MqttInterruptedException - Thrown when the calling thread is interrupted

close

void close(MqttChannelRef channel)
           throws MqttCommandCancelledException,
                  MqttTimeoutException,
                  MqttInterruptedException

Closes the specified channel. This method blocks until the channel is closed.

Throws:

MqttCommandCancelledException - The channel manager uses a command pattern to process this request on the IO thread. If the command is cancelled for some reason, like the channel closes, this exception is thrown.

MqttTimeoutException - Thrown when using a synchronous implementation and the timeout specified for a blocked method expires

MqttInterruptedException - Thrown when the calling thread is interrupted

close

void close(MqttChannelRef channel,
           Throwable cause)
           throws MqttCommandCancelledException,
                  MqttTimeoutException,
                  MqttInterruptedException

Closes the specified channel and sends cause to the MessageHandler.channelClosed(MqttChannel, Throwable) callback. This method blocks until the channel is closed.

Throws:

MqttCommandCancelledException - The channel manager uses a command pattern to process this request on the IO thread. If the command is cancelled for some reason, like the channel closes, this exception is thrown.

MqttTimeoutException - Thrown when using a synchronous implementation and the timeout specified for a blocked method expires

MqttInterruptedException - Thrown when the calling thread is interrupted

cancelBlockingCommands

void cancelBlockingCommands(MqttChannelRef channel)

Cancels all blocking commands for the specified channel. This is not done when the channel is closed because we may want to reconnect instead of releasing the commands.

getUnsentMessages

List<MqttMessage> getUnsentMessages(MqttChannelRef channel)

Returns:

All messages that have not been sent. This includes messages queued to be sent, any partially sent message, and all in flight messages.

transfer

void transfer(MqttChannelRef oldChannel,
              MqttChannelRef newChannel)

Transfers unsent messages from oldChannel to newChannel and changes oldChannel such that any messages sent to it will actually go to newChannel. This is used by reconnection logic to safely use a new connection in place of one that closed.

init

void init()

Starts this channel manager. Must be called before any other methods

shutdown

void shutdown()

Stops this channel manager. Any other methods called after this have unpredictable results. Closes all open channels. Blocks until shutdown is complete.

isRunning

boolean isRunning()

Returns:

True if this manager is running and not yet stopped. This really means the manager's IO thread is running.