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	attachChannel(MqttChannelRef channel, MessageHandler messageHandler) Attaches the specified channel to this manager's control.
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.
void	detachChannel(MqttChannelRef channel) Detaches the specified channel from this manager's control.
MessageStats	getStats(boolean reset) Request the current snapshot of statistics that are available from this channel manager.
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,
                                       MqttInvocationException,
                                       MqttInvocationError

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

newClientChannel

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

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

newClientChannel

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

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

newBrokerChannel

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

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 remote 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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

send

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

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

close

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

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

close

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

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

cancelBlockingCommands

void cancelBlockingCommands(MqttChannelRef channel)
                            throws MqttCommandCancelledException,
                                   MqttTimeoutException,
                                   MqttInterruptedException,
                                   MqttInvocationException,
                                   MqttInvocationError

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.

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

getUnsentMessages

List<MqttMessage> getUnsentMessages(MqttChannelRef channel)
                                    throws MqttCommandCancelledException,
                                           MqttTimeoutException,
                                           MqttInterruptedException,
                                           MqttInvocationException,
                                           MqttInvocationError

Returns:

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

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

transfer

void transfer(MqttChannelRef oldChannel,
              MqttChannelRef newChannel)
              throws MqttCommandCancelledException,
                     MqttTimeoutException,
                     MqttInterruptedException,
                     MqttInvocationException,
                     MqttInvocationError

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.

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

detachChannel

void detachChannel(MqttChannelRef channel)
                   throws MqttCommandCancelledException,
                          MqttTimeoutException,
                          MqttInterruptedException,
                          MqttInvocationException,
                          MqttInvocationError

Detaches the specified channel from this manager's control. This is used in conjunction with #attachChannel(MqttChannelRef) to move handling of the channel's messages from one manager to another. This is always a synchronous operation. It is safe to call this from the ChannelManagerImpl IO thread.

Parameters:

channel - The channel to detach

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

attachChannel

void attachChannel(MqttChannelRef channel,
                   MessageHandler messageHandler)
                   throws MqttCommandCancelledException,
                          MqttTimeoutException,
                          MqttInterruptedException,
                          MqttInvocationException,
                          MqttInvocationError

Attaches the specified channel to this manager's control. This is used in conjunction with detachChannel(MqttChannelRef) to move handling of the channel's messages from one manager to another. This is always a synchronous operation.

Parameters:

channel - The channel to attach

messageHandler - The message handler to use for all received messages

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

MqttInvocationException - The channel manager uses a command pattern to process this request on the IO thread. Any Exception thrown while the command is being processed will be wrapped in an MqttInvocationException.

MqttInvocationError - The channel manager uses a command pattern to process this request on the IO thread. Any Error thrown while the command is being processed will be wrapped in an MqttInvocationError.

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.

getStats

MessageStats getStats(boolean reset)

Request the current snapshot of statistics that are available from this channel manager.

Parameters:

reset - If true following the acquisition of the statistics all applicable counters that can be reset will be. This is useful if statistics are being gathered and reported at regular intervals and the desire is to see the statistics for the previous interval

Returns:

The statistics for the MQTT client