org.eclipse.paho.client.mqttv3

Class MqttConnectOptions

java.lang.Object

org.eclipse.paho.client.mqttv3.MqttConnectOptions

public class MqttConnectOptions
extends Object

Holds options that control how the client connects to a server.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	CLEAN_SESSION_DEFAULT The default clean session setting if one is not specified
static int	CONNECTION_TIMEOUT_DEFAULT The default connection timeout in seconds if one is not specified
static int	KEEP_ALIVE_INTERVAL_DEFAULT The default keep alive interval in seconds if one is not specified
static int	MQTT_VERSION_3_1
static int	MQTT_VERSION_3_1_1
static int	MQTT_VERSION_DEFAULT The default MqttVersion is 3.1.1 first, dropping back to 3.1 if that fails
protected static int	URI_TYPE_LOCAL
protected static int	URI_TYPE_SSL
protected static int	URI_TYPE_TCP

Constructor Summary

Constructors

Constructor and Description
MqttConnectOptions() Constructs a new MqttConnectOptions object using the default values.

Method Summary

Methods

Modifier and Type	Method and Description
int	getConnectionTimeout() Returns the connection timeout value.
org.eclipse.paho.client.mqttv3.util.Properties	getDebug()
int	getKeepAliveInterval() Returns the "keep alive" interval.
int	getMqttVersion() Returns the MQTT version.
char[]	getPassword() Returns the password to use for the connection.
String[]	getServerURIs()
org.eclipse.paho.client.mqttv3.util.Properties	getSSLProperties() Returns the SSL properties for the connection.
String	getUserName() Returns the user name to use for the connection.
String	getWillDestination() Returns the topic to be used for last will and testament (LWT).
MqttMessage	getWillMessage() Returns the message to be sent as last will and testament (LWT).
boolean	isCleanSession() Returns whether the server should remember state for the client across reconnects.
void	setCleanSession(boolean cleanSession) Sets whether the server should remember state for the client across reconnects.
void	setConnectionTimeout(int connectionTimeout) Sets the connection timeout value.
void	setKeepAliveInterval(int keepAliveInterval) Sets the "keep alive" interval.
void	setMqttVersion(int MqttVersion) Sets the MQTT version.
void	setPassword(char[] password) Sets the password to use for the connection.
void	setServerURIs(String[] array)
void	setSSLProperties(org.eclipse.paho.client.mqttv3.util.Properties props) Sets the SSL properties for the connection.
void	setUserName(String userName) Sets the user name to use for the connection.
void	setWill(MqttTopic topic, byte[] payload, int qos, boolean retained) Sets the "Last Will and Testament" (LWT) for the connection.
void	setWill(String topic, byte[] payload, int qos, boolean retained) Sets the "Last Will and Testament" (LWT) for the connection.
protected void	setWill(String topic, MqttMessage msg, int qos, boolean retained) Sets up the will information, based on the supplied parameters.
String	toString() Returns a string representation of the object.
protected static int	validateURI(String srvURI) Validate a URI

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

KEEP_ALIVE_INTERVAL_DEFAULT

public static final int KEEP_ALIVE_INTERVAL_DEFAULT

The default keep alive interval in seconds if one is not specified

See Also:

Constant Field Values

CONNECTION_TIMEOUT_DEFAULT

public static final int CONNECTION_TIMEOUT_DEFAULT

The default connection timeout in seconds if one is not specified

See Also:

Constant Field Values

CLEAN_SESSION_DEFAULT

public static final boolean CLEAN_SESSION_DEFAULT

The default clean session setting if one is not specified

See Also:

Constant Field Values

MQTT_VERSION_DEFAULT

public static final int MQTT_VERSION_DEFAULT

The default MqttVersion is 3.1.1 first, dropping back to 3.1 if that fails

See Also:

Constant Field Values

MQTT_VERSION_3_1

public static final int MQTT_VERSION_3_1

See Also:

Constant Field Values

MQTT_VERSION_3_1_1

public static final int MQTT_VERSION_3_1_1

See Also:

Constant Field Values

URI_TYPE_TCP

protected static final int URI_TYPE_TCP

See Also:

Constant Field Values

URI_TYPE_SSL

protected static final int URI_TYPE_SSL

See Also:

Constant Field Values

URI_TYPE_LOCAL

protected static final int URI_TYPE_LOCAL

See Also:

Constant Field Values

Constructor Detail

MqttConnectOptions

public MqttConnectOptions()

Constructs a new MqttConnectOptions object using the default values. The defaults are:

• The keepalive interval is 60 seconds
• Clean Session is true
• The message delivery retry interval is 15 seconds
• The connection timeout period is 30 seconds
• No Will message is set
• A standard SocketFactory is used

More information about these values can be found in the setter methods.

Method Detail

getPassword

public char[] getPassword()

Returns the password to use for the connection.

Returns:

the password to use for the connection.

setPassword

public void setPassword(char[] password)

Sets the password to use for the connection.

getUserName

public String getUserName()

Returns the user name to use for the connection.

Returns:

the user name to use for the connection.

setUserName

public void setUserName(String userName)

Sets the user name to use for the connection.

Throws:

IllegalArgumentException - if the user name is blank or only contains whitespace characters.

setWill

public void setWill(MqttTopic topic,
           byte[] payload,
           int qos,
           boolean retained)

Sets the "Last Will and Testament" (LWT) for the connection. In the event that this client unexpectedly loses its connection to the server, the server will publish a message to itself using the supplied details.

Parameters:

topic - the topic to publish to.

payload - the byte payload for the message.

qos - the quality of service to publish the message at (0, 1 or 2).

retained - whether or not the message should be retained.

setWill

public void setWill(String topic,
           byte[] payload,
           int qos,
           boolean retained)

Sets the "Last Will and Testament" (LWT) for the connection. In the event that this client unexpectedly loses its connection to the server, the server will publish a message to itself using the supplied details.

Parameters:

topic - the topic to publish to.

payload - the byte payload for the message.

qos - the quality of service to publish the message at (0, 1 or 2).

retained - whether or not the message should be retained.

setWill

protected void setWill(String topic,
           MqttMessage msg,
           int qos,
           boolean retained)

Sets up the will information, based on the supplied parameters.

getKeepAliveInterval

public int getKeepAliveInterval()

Returns the "keep alive" interval.

Returns:

the keep alive interval.

See Also:

setKeepAliveInterval(int)

getMqttVersion

public int getMqttVersion()

Returns the MQTT version.

Returns:

the MQTT version.

See Also:

setMqttVersion(int)

setKeepAliveInterval

public void setKeepAliveInterval(int keepAliveInterval)
                          throws IllegalArgumentException

Sets the "keep alive" interval. This value, measured in seconds, defines the maximum time interval between messages sent or received. It enables the client to detect if the server is no longer available, without having to wait for the TCP/IP timeout. The client will ensure that at least one message travels across the network within each keep alive period. In the absence of a data-related message during the time period, the client sends a very small "ping" message, which the server will acknowledge. A value of 0 disables keepalive processing in the client.

The default value is 60 seconds

Parameters:

keepAliveInterval - the interval, measured in seconds, must be >= 0.

Throws:

IllegalArgumentException

getConnectionTimeout

public int getConnectionTimeout()

Returns the connection timeout value.

Returns:

the connection timeout value.

See Also:

setConnectionTimeout(int)

setConnectionTimeout

public void setConnectionTimeout(int connectionTimeout)

Sets the connection timeout value. This value, measured in seconds, defines the maximum time interval the client will wait for the network connection to the MQTT server to be established. The default timeout is 30 seconds. A value of 0 disables timeout processing meaning the client will wait until the network connection is made successfully or fails.

Parameters:

connectionTimeout - the timeout value, measured in seconds. It must be >0;

getWillDestination

public String getWillDestination()

Returns the topic to be used for last will and testament (LWT).

Returns:

the MqttTopic to use, or null if LWT is not set.

See Also:

setWill(MqttTopic, byte[], int, boolean)

getWillMessage

public MqttMessage getWillMessage()

Returns the message to be sent as last will and testament (LWT). The returned object is "read only". Calling any "setter" methods on the returned object will result in an IllegalStateException being thrown.

Returns:

the message to use, or null if LWT is not set.

getSSLProperties

public org.eclipse.paho.client.mqttv3.util.Properties getSSLProperties()

Returns the SSL properties for the connection.

Returns:

the properties for the SSL connection

setSSLProperties

public void setSSLProperties(org.eclipse.paho.client.mqttv3.util.Properties props)

Sets the SSL properties for the connection. Note that these properties are only valid if an implementation of the Java Secure Socket Extensions (JSSE) is available. These properties are not used if a SocketFactory has been set using #setSocketFactory(SocketFactory). The following properties can be used:

com.ibm.ssl.protocol

One of: SSL, SSLv3, TLS, TLSv1, SSL_TLS.

com.ibm.ssl.contextProvider

Underlying JSSE provider. For example "IBMJSSE2" or "SunJSSE"

com.ibm.ssl.keyStore

The name of the file that contains the KeyStore object that you want the KeyManager to use. For example /mydir/etc/key.p12

com.ibm.ssl.keyStorePassword

The password for the KeyStore object that you want the KeyManager to use. The password can either be in plain-text, or may be obfuscated using the static method: com.ibm.micro.security.Password.obfuscate(char[] password). This obfuscates the password using a simple and insecure XOR and Base64 encoding mechanism. Note that this is only a simple scrambler to obfuscate clear-text passwords.

com.ibm.ssl.keyStoreType

Type of key store, for example "PKCS12", "JKS", or "JCEKS".

com.ibm.ssl.keyStoreProvider

Key store provider, for example "IBMJCE" or "IBMJCEFIPS".

com.ibm.ssl.trustStore

The name of the file that contains the KeyStore object that you want the TrustManager to use.

com.ibm.ssl.trustStorePassword

The password for the TrustStore object that you want the TrustManager to use. The password can either be in plain-text, or may be obfuscated using the static method: com.ibm.micro.security.Password.obfuscate(char[] password). This obfuscates the password using a simple and insecure XOR and Base64 encoding mechanism. Note that this is only a simple scrambler to obfuscate clear-text passwords.

com.ibm.ssl.trustStoreType

The type of KeyStore object that you want the default TrustManager to use. Same possible values as "keyStoreType".

com.ibm.ssl.trustStoreProvider

Trust store provider, for example "IBMJCE" or "IBMJCEFIPS".

com.ibm.ssl.enabledCipherSuites

A list of which ciphers are enabled. Values are dependent on the provider, for example: SSL_RSA_WITH_AES_128_CBC_SHA;SSL_RSA_WITH_3DES_EDE_CBC_SHA.

com.ibm.ssl.keyManager

Sets the algorithm that will be used to instantiate a KeyManagerFactory object instead of using the default algorithm available in the platform. Example values: "IbmX509" or "IBMJ9X509".

com.ibm.ssl.trustManager

Sets the algorithm that will be used to instantiate a TrustManagerFactory object instead of using the default algorithm available in the platform. Example values: "PKIX" or "IBMJ9X509".

isCleanSession

public boolean isCleanSession()

Returns whether the server should remember state for the client across reconnects.

Returns:

the clean session flag

setCleanSession

public void setCleanSession(boolean cleanSession)

Sets whether the server should remember state for the client across reconnects. This includes subscriptions and the state of any in-flight messages.

getServerURIs

public String[] getServerURIs()

Returns:

the serverURIs

setServerURIs

public void setServerURIs(String[] array)

Parameters:

array - of serverURIs

validateURI

protected static int validateURI(String srvURI)

Validate a URI

Parameters:

srvURI -

Returns:

the URI type

setMqttVersion

public void setMqttVersion(int MqttVersion)
                    throws IllegalArgumentException

Sets the MQTT version. The default action is to connect with version 3.1.1, and to fall back to 3.1 if that fails. Version 3.1.1 or 3.1 can be selected specifically, with no fall back, by using the MQTT_VERSION_3_1_1 or MQTT_VERSION_3_1 options respectively.

Parameters:

MqttVersion - the version of the MQTT protocol.

Throws:

IllegalArgumentException

getDebug

public org.eclipse.paho.client.mqttv3.util.Properties getDebug()

toString

public String toString()

Description copied from class: Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Object

Returns:

a string representation of the object.