net.sf.xenqtt.message
Interface MqttChannel

All Superinterfaces:

MqttChannelRef

All Known Implementing Classes:

MqttBrokerChannel, MqttClientChannel

public interface MqttChannel
extends MqttChannelRef

Sends and receives MqttMessages over a channel. This may be client or server side. Since read(long) may generate data to send it should always be called before write(long). houseKeeping(long) should be called after both read(long) and write(long) as those methods may change paramaters used to determine what housekeeping is required.

If any exception occurs the channel is closed.

Method Summary

void	cancelBlockingCommands() Cancels all blocking commands.
void	close() Closes the underlying channels, sockets, etc
void	close(Throwable cause) Closes the underlying channels, sockets, etc and sends cause to the MessageHandler.channelClosed(MqttChannel, Throwable) callback.
void	deregister() Deregisters this channel.
boolean	finishConnect() Finishes a connection.
String	getLocalAddress()
String	getRemoteAddress()
List<MqttMessage>	getUnsentMessages()
long	houseKeeping(long now) Performs housekeeping: message resends, ping requests, etc
int	inFlightMessageCount()
boolean	isConnected() Tells whether or not this channel is connected.
boolean	isConnectionPending() Tells whether or not a connection operation is in progress on this channel.
boolean	isOpen() Tells whether or not this channel is open.
void	pauseRead() Pauses reading on the channel.
boolean	read(long now) Reads data.
boolean	register(Selector selector, MessageHandler handler) Registers this channel with the specified selector.
void	resumeRead() Resumes reading on this channel.
boolean	send(MqttMessage message) Sends the specified message asynchronously.
boolean	send(MqttMessage message, BlockingCommand<MqttMessage> blockingCommand) Sends the specified message asynchronously.
int	sendQueueDepth()
boolean	write(long now) Writes as much data as possible.

Method Detail

deregister

void deregister()

Deregisters this channel. Cancels the underlying SelectionKey.

register

boolean register(Selector selector,
                 MessageHandler handler)

Registers this channel with the specified selector. This channel must not already be registered with another selector. The current MessageHandler is replaced with the specified one.

Returns:

A return value of true does NOT necessarily mean this channel is open but false does mean it is closed (or the connect hasn't finished yet).

finishConnect

boolean finishConnect()

Finishes a connection. This should be called when a SelectionKeys SelectionKey.OP_CONNECT op is ready.

Returns:

True if and only if this channel is now connected.

read

boolean read(long now)

Reads data. This will read as many messages as it can and pass them to a MessageHandler.This should be called when a SelectionKeys SelectionKey.OP_READ op is ready.

Parameters:

now - The timestamp to use as the "current" time

Returns:

True if the channel is left open. False if it is closed by this method or already closed when this method is called or the connect hasn't finished yet.

pauseRead

void pauseRead()

Pauses reading on the channel. To resume call resumeRead().

resumeRead

void resumeRead()

Resumes reading on this channel.

send

boolean send(MqttMessage message)

Sends the specified message asynchronously. When a DisconnectMessage or a ConnAckMessage where ConnAckMessage.getReturnCode() is not ConnectReturnCode.ACCEPTED is sent the channel is closed automatically. This is the same as calling #send(MqttMessage, BlockingCommand, long) with a null BlockingCommand and 0 timestamp.

Parameters:

message - The message to send

Returns:

A return value of true does NOT necessarily mean this channel is open but false does mean it is closed (or the connect hasn't finished yet).

send

boolean send(MqttMessage message,
             BlockingCommand<MqttMessage> blockingCommand)

Sends the specified message asynchronously. When a DisconnectMessage or a ConnAckMessage where ConnAckMessage.getReturnCode() is not ConnectReturnCode.ACCEPTED is sent the channel is closed automatically.

Parameters:

message - The message to send

blockingCommand - If not null then this latch is complete when processing the message is complete. The definition of complete is:

• If the message is a ConnectMessage processing is complete when the ConnAckMessage is received.
• else if the message is ackable processing is complete when the ack is received.
• else processing is complete when the message is written to the socket.
• If any exception occurs or the channel is closed all in flight messages are complete

Returns:

A return value of true does NOT necessarily mean this channel is open but false does mean it is closed (or the connect hasn't finished yet).

write

boolean write(long now)

Writes as much data as possible. This should be called when a SelectionKeys SelectionKey.OP_WRITE op is ready.

Parameters:

now - The timestamp to use as the "current" time

Returns:

True if the channel is left open. False if it is closed by this method or already closed when this method is called or the connect hasn't finished yet.

close

void close()

Closes the underlying channels, sockets, etc

close

void close(Throwable cause)

Closes the underlying channels, sockets, etc and sends cause to the MessageHandler.channelClosed(MqttChannel, Throwable) callback.

isOpen

boolean isOpen()

Tells whether or not this channel is open. This channel is open if the underlying channels, sockets, etc are open

Returns:

true if, and only if, this channel is open

isConnected

boolean isConnected()

Tells whether or not this channel is connected. This channel is connected if isOpen() is true, Connect/ConnectAck has finished, and no disconnect has been received/sent.

Returns:

True if and only if this channel is connected.

isConnectionPending

boolean isConnectionPending()

Tells whether or not a connection operation is in progress on this channel.

Returns:

true if, and only if, a connection operation has been initiated on this channel but not yet completed by invoking the finishConnect() method

houseKeeping

long houseKeeping(long now)

Performs housekeeping: message resends, ping requests, etc

Parameters:

now - The timestamp to use as the "current" time

Returns:

Maximum millis until this method should be called again. This result is only valid when this method is called. Future calls to read(long) or write(long) may change this value. Returns < 0 if this method closes the channel.

sendQueueDepth

int sendQueueDepth()

Returns:

The number of messages in the send queue. This includes any message currently in the process of being sent

inFlightMessageCount

int inFlightMessageCount()

Returns:

The number of messages currently in flight (QoS level > 0)

cancelBlockingCommands

void cancelBlockingCommands()

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

getUnsentMessages

List<MqttMessage> getUnsentMessages()

Returns:

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

getRemoteAddress

String getRemoteAddress()

Returns:

The channel's remote address

getLocalAddress

String getLocalAddress()

Returns:

The channel's local address