net.sf.xenqtt.message
Class ConnectMessage

java.lang.Object
  net.sf.xenqtt.message.MqttMessage
      net.sf.xenqtt.message.ConnectMessage

public final class ConnectMessage
extends MqttMessage

The MQTT connect message. When a TCP/IP socket connection is established from a client to a server, a protocol level session must be created using a CONNECT flow.

Constructor Summary

ConnectMessage(ByteBuffer buffer, int remainingLength, long receivedTimestamp)
Create a new instance of this class.

ConnectMessage(String clientId, boolean cleanSession, int keepAliveSeconds)
Create an instance with no credentials and no will message.

ConnectMessage(String clientId, boolean cleanSession, int keepAliveSeconds, String userName, String password)
Create an instance with credentials and no will message.

ConnectMessage(String clientId, boolean cleanSession, int keepAliveSeconds, String willTopic, String willMessage, QoS willQos, boolean willRetain)
Create an instance with no credentials and a will message.

ConnectMessage(String clientId, boolean cleanSession, int keepAliveSeconds, String userName, String password, String willTopic, String willMessage, QoS willQos, boolean willRetain)
Create an instance with credentials and a will message.

Method Summary

String	getClientId() The Client Identifier (Client ID) is between 1 and 23 characters long, and uniquely identifies the client to the server.
int	getKeepAliveSeconds() The Keep Alive timer, measured in seconds, defines the maximum time interval between messages received from a client.
String	getPassword() If the Password flag is set, this is the next UTF-encoded string.
String	getProtocolName() String that represents the protocol name MQIsdp, capitalized as shown.
int	getProtocolVersion() The revision level of the protocol used by the client.
String	getUserName() The user name identifies the name of the user who is connecting, which can be used for authentication.
String	getWillMessage() The Will Message defines the content of the message that is published to the Will Topic if the client is unexpectedly disconnected.
QoS	getWillQoS()
int	getWillQoSLevel()
String	getWillTopic() The Will Message is published to the Will Topic.
boolean	isCleanSession() If not set, then the server must store the subscriptions of the client after it disconnects.
boolean	isPasswordFlag()
boolean	isUserNameFlag()
boolean	isWillMessageFlag()
boolean	isWillRetain() The retain value of the Will message.

Methods inherited from class net.sf.xenqtt.message.MqttMessage

byteBufferToHex, bytesToHex, equals, getMessageType, getQoS, getQoSLevel, getReceivedTimestamp, getRemainingLength, isAck, isAckable, isDuplicate, isRetain, setDuplicateFlag, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ConnectMessage

public ConnectMessage(ByteBuffer buffer,
                      int remainingLength,
                      long receivedTimestamp)

Create a new instance of this class.

Parameters:

buffer - The buffer that contains the contents of the message

remainingLength - The remaining length of the message

receivedTimestamp - The time at which the message was received

ConnectMessage

public ConnectMessage(String clientId,
                      boolean cleanSession,
                      int keepAliveSeconds)

Create an instance with no credentials and no will message.

ConnectMessage

public ConnectMessage(String clientId,
                      boolean cleanSession,
                      int keepAliveSeconds,
                      String userName,
                      String password)

Create an instance with credentials and no will message.

ConnectMessage

public ConnectMessage(String clientId,
                      boolean cleanSession,
                      int keepAliveSeconds,
                      String willTopic,
                      String willMessage,
                      QoS willQos,
                      boolean willRetain)

Create an instance with no credentials and a will message.

ConnectMessage

public ConnectMessage(String clientId,
                      boolean cleanSession,
                      int keepAliveSeconds,
                      String userName,
                      String password,
                      String willTopic,
                      String willMessage,
                      QoS willQos,
                      boolean willRetain)

Create an instance with credentials and a will message.

Method Detail

getProtocolName

public String getProtocolName()

String that represents the protocol name MQIsdp, capitalized as shown.

getProtocolVersion

public int getProtocolVersion()

The revision level of the protocol used by the client. The current version of the protocol is 3

isCleanSession

public boolean isCleanSession()

If not set, then the server must store the subscriptions of the client after it disconnects. This includes continuing to store QoS 1 and QoS 2 messages for the subscribed topics so that they can be delivered when the client reconnects. The server must also maintain the state of in-flight messages being delivered at the point the connection is lost. This information must be kept until the client reconnects.

If set, then the server must discard any previously maintained information about the client and treat the connection as "clean". The server must also discard any state when the client disconnects.

Typically, a client will operate in one mode or the other and not change. The choice will depend on the application. A clean session client will not receive stale information and it must resubscribe each time it connects. A non-clean session client will not miss any QoS 1 or QoS 2 messages that were published whilst it was disconnected. QoS 0 messages are never stored, since they are delivered on a best efforts basis.

This flag was formerly known as "Clean start". It has been renamed to clarify the fact it applies to the whole session and not just to the initial connect.

A server may provide an administrative mechanism for clearing stored information about a client which can be used when it is known that a client will never reconnect.

getClientId

public String getClientId()

The Client Identifier (Client ID) is between 1 and 23 characters long, and uniquely identifies the client to the server. It must be unique across all clients connecting to a single server, and is the key in handling messages with QoS levels 1 and 2. If the Client ID contains more than 23 characters, the server responds to the CONNECT message with a CONNACK return code 2: Identifier Rejected.

getWillTopic

public String getWillTopic()

The Will Message is published to the Will Topic. The QoS level is defined by getWillQoS() and the RETAIN status is defined by isWillRetain().

Null if there is no Will Message.

isWillMessageFlag

public boolean isWillMessageFlag()

Returns:

True if the will message flag is set

getWillMessage

public String getWillMessage()

The Will Message defines the content of the message that is published to the Will Topic if the client is unexpectedly disconnected. This may be a zero-length message.

Although the Will Message is UTF-8 encoded in the CONNECT message, when it is published to the Will Topic only the bytes of the message are sent, not the first two length bytes. The message must therefore only consist of 7-bit ASCII characters.

Null if there is no Will Message. Zero length string if there is an empty Will Message.

getWillQoS

public QoS getWillQoS()

Returns:

The QoS of the willMessage. If there is not a Will Message then this is not applicable.

getWillQoSLevel

public int getWillQoSLevel()

Returns:

The integer value of the QoS of the willMessage. If there is not a Will Message then this is not applicable.

isWillRetain

public boolean isWillRetain()

The retain value of the Will message. False if either retain is false or there is no Will Message.

isUserNameFlag

public boolean isUserNameFlag()

Returns:

True if the user name flag is set

getUserName

public String getUserName()

The user name identifies the name of the user who is connecting, which can be used for authentication. It is recommended that user names are kept to 12 characters or fewer, but it is not required.

Note that, for compatibility with the original MQTT V3 specification, the Remaining Length field from the fixed header takes precedence over the User Name flag. Server implementations must allow for the possibility that the User Name flag is set, but the User Name string is missing. This is valid, and connections should be allowed to continue.

Null if there is no user name.

isPasswordFlag

public boolean isPasswordFlag()

Returns:

True if the password flag is set

getPassword

public String getPassword()

If the Password flag is set, this is the next UTF-encoded string. The password corresponding to the user who is connecting, which can be used for authentication. It is recommended that passwords are kept to 12 characters or fewer, but it is not required.

Note that, for compatibility with the original MQTT V3 specification, the Remaining Length field from the fixed header takes precedence over the Password flag. Server implementations must allow for the possibility that the Password flag is set, but the Password string is missing. This is valid, and connections should be allowed to continue.

Null if there is no password. If there is no username there can be no password.

getKeepAliveSeconds

public int getKeepAliveSeconds()

The Keep Alive timer, measured in seconds, defines the maximum time interval between messages received from a client. It enables the server to detect that the network connection to a client has dropped, without having to wait for the long TCP/IP timeout. The client has a responsibility to send a message within each Keep Alive time period. In the absence of a data-related message during the time period, the client sends a PINGREQ message, which the server acknowledges with a PINGRESP message.

If the server does not receive a message from the client within one and a half times the Keep Alive time period (the client is allowed "grace" of half a time period), it disconnects the client as if the client had sent a DISCONNECT message. This action does not impact any of the client's subscriptions. See DISCONNECT for more details.

If a client does not receive a PINGRESP message within a Keep Alive time period after sending a PINGREQ, it should close the TCP/IP socket connection.

The Keep Alive timer is a 16-bit value that represents the number of seconds for the time period. The actual value is application-specific, but a typical value is a few minutes. The maximum value is approximately 18 hours. A value of zero (0) means the client is not disconnected.