org.eclipse.paho.client.mqttv3
Class MqttConnectOptions

java.lang.Object
  extended by org.eclipse.paho.client.mqttv3.MqttConnectOptions

public class MqttConnectOptions
extends Object

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


Field Summary
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
protected static int URI_TYPE_LOCAL
           
protected static int URI_TYPE_SSL
           
protected static int URI_TYPE_TCP
           
 
Constructor Summary
MqttConnectOptions()
          Constructs a new MqttConnectOptions object using the default values.
 
Method Summary
 int getConnectionTimeout()
          Returns the connection timeout value.
 Properties getDebug()
           
 int getKeepAliveInterval()
          Returns the "keep alive" interval.
 char[] getPassword()
          Returns the password to use for the connection.
 String[] getServerURIs()
          Return a list of serverURIs the client may connect to
 SocketFactory getSocketFactory()
          Returns the socket factory that will be used when connecting, or null if one has not been set.
 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 client and server should remember state for the client across reconnects.
 void setCleanSession(boolean cleanSession)
          Sets whether the client and server should remember state across restarts and reconnects.
 void setConnectionTimeout(int connectionTimeout)
          Sets the connection timeout value.
 void setKeepAliveInterval(int keepAliveInterval)
          Sets the "keep alive" interval.
 void setPassword(char[] password)
          Sets the password to use for the connection.
 void setServerURIs(String[] array)
          Set a list of one or more serverURIs the client may connect to.
 void setSocketFactory(SocketFactory socketFactory)
          Sets the SocketFactory to use.
 void setSSLProperties(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()
           
protected static int validateURI(String srvURI)
          Validate a URI
 
Methods inherited from class java.lang.Object
clone, equals, finalize, 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

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: 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)

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;

getSocketFactory

public SocketFactory getSocketFactory()
Returns the socket factory that will be used when connecting, or null if one has not been set.


setSocketFactory

public void setSocketFactory(SocketFactory socketFactory)
Sets the SocketFactory to use. This allows an application to apply its own policies around the creation of network sockets. If using an SSL connection, an SSLSocketFactory can be used to supply application-specific security settings.

Parameters:
socketFactory - the factory to use.

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 Properties getSSLProperties()
Returns the SSL properties for the connection.

Returns:
the properties for the SSL connection

setSSLProperties

public void setSSLProperties(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 client and server should remember state for the client across reconnects.

Returns:
the clean session flag

setCleanSession

public void setCleanSession(boolean cleanSession)
Sets whether the client and server should remember state across restarts and reconnects.

getServerURIs

public String[] getServerURIs()
Return a list of serverURIs the client may connect to

Returns:
the serverURIs or null if not set

setServerURIs

public void setServerURIs(String[] array)
Set a list of one or more serverURIs the client may connect to.

Each serverURI specifies the address of a server that the client may connect to. Two types of connection are supported tcp:// for a TCP connection and ssl:// for a TCP connection secured by SSL/TLS. For example:

If the port is not specified, it will default to 1883 for tcp://" URIs, and 8883 for ssl:// URIs.

If serverURIs is set then it overrides the serverURI parameter passed in on the constructor of the MQTT client.

When an attempt to connect is initiated the client will start with the first serverURI in the list and work through the list until a connection is established with a server. If a connection cannot be made to any of the servers then the connect attempt fails.

Specifying a list of servers that a client may connect to has several uses:

  1. High Availability and reliable message delivery

    Some MQTT servers support a high availability feature where two or more "equal" MQTT servers share state. An MQTT client can connect to any of the "equal" servers and be assured that messages are reliably delivered and durable subscriptions are maintained no matter which server the client connects to.

    The cleansession flag must be set to false if durable subscriptions and/or reliable message delivery is required.

  2. Hunt List

    A set of servers may be specified that are not "equal" (as in the high availability option). As no state is shared across the servers reliable message delivery and durable subscriptions are not valid. The cleansession flag must be set to true if the hunt list mode is used

Parameters:
array - of serverURIs

validateURI

protected static int validateURI(String srvURI)
Validate a URI

Parameters:
srvURI -
Returns:
the URI type

getDebug

public Properties getDebug()

toString

public String toString()
Overrides:
toString in class Object


Copyright © 2013. All Rights Reserved.