Issue #540 - Starting to fix MQTTv5 terminology - cleanSession -> cleanStart.

Signed-off-by: James Sutton <james.sutton@uk.ibm.com>

Author: jpwsutton

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/IMqttAsyncClient.java

@@ -175,7 +175,7 @@ IMqttToken connect(MqttConnectionOptions options, Object userContext, MqttAction
 	 * messages being accepted and does not send any messages that have been
 	 * accepted but not yet started delivery across the network to the server. When
 	 * work has completed or after the quiesce timeout, the client will disconnect
-	 * from the server. If the cleanSession flag was set to false and is set to
+	 * from the server. If the cleanStart flag was set to false and is set to
 	 * false the next time a connection is made QoS 1 and 2 messages that were not
 	 * previously delivered will be delivered.
 	 * </p>
@@ -429,7 +429,7 @@ IMqttToken subscribe(String topicFilter, int qos, Object userContext, MqttAction
 	 * method, otherwise any received messages will be discarded.
 	 * </p>
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to true when
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to true when
 	 * when connecting to the server then the subscription remains in place until
 	 * either:
 	 * </p>
@@ -440,15 +440,15 @@ IMqttToken subscribe(String topicFilter, int qos, Object userContext, MqttAction
 	 * </ul>
 	 *
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to false when
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to false when
 	 * connecting to the server then the subscription remains in place until either:
 	 * </p>
 	 * <ul>
 	 * <li>An unsubscribe method is called to unsubscribe the topic</li>
-	 * <li>The next time the client connects with cleanSession set to true</li>
+	 * <li>The next time the client connects with cleanStart set to true</li>
 	 * </ul>
 	 * <p>
-	 * With cleanSession set to false the MQTT server will store messages on behalf
+	 * With cleanStart set to false the MQTT server will store messages on behalf
 	 * of the client when the client is not connected. The next time the client
 	 * connects with the <b>same client ID</b> the server will deliver the stored
 	 * messages to the client.
@@ -834,9 +834,9 @@ IMqttToken unsubscribe(String[] topicFilters, Object userContext, MqttActionList
 	 * callback can be used to track the delivery of outstanding messages.
 	 * </p>
 	 * <p>
-	 * If a client connects with cleanSession true then there will be no delivery
-	 * tokens as the cleanSession option deletes all earlier state. For state to be
-	 * remembered the client must connect with cleanSession set to false
+	 * If a client connects with cleanStart true then there will be no delivery
+	 * tokens as the cleanStart option deletes all earlier state. For state to be
+	 * remembered the client must connect with cleanStart set to false
 	 * </P>
 	 *
 	 * @return zero or more delivery tokens
@@ -946,9 +946,9 @@ IMqttDeliveryToken publish(String topic, byte[] payload, int qos, boolean retain
 	 * <ul>
 	 * <li>The connection is re-established with the same clientID
 	 * <li>The original connection was made with (@link
-	 * MqttConnectOptions#setCleanSession(boolean)} set to false
+	 * MqttConnectOptions#setCleanStart(boolean)} set to false
 	 * <li>The connection is re-established with (@link
-	 * MqttConnectOptions#setCleanSession(boolean)} set to false
+	 * MqttConnectOptions#setCleanStart(boolean)} set to false
 	 * <li>Depending when the failure occurs QoS 0 messages may not be delivered.
 	 * </ul>
 	 *

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/IMqttClient.java

@@ -134,7 +134,7 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * work which has already been initiated to complete - for example, it will
 	 * wait for the QoS 2 flows from earlier publications to complete. When work has
 	 * completed or after the quiesce timeout, the client will disconnect from
-	 * the server. If the cleanSession flag was set to false and is set to false the
+	 * the server. If the cleanStart flag was set to false and is set to false the
 	 * next time a connection is made QoS 1 and 2 messages that
 	 * were not previously delivered will be delivered.</p>
 	 *
@@ -227,7 +227,7 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * will be discarded.
 	 * </p>
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to true
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to true
 	 * when when connecting to the server then the subscription remains in place
 	 * until either:
 	 * </p>
@@ -236,15 +236,15 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * <li>An unsubscribe method is called to un-subscribe the topic</li>
 	 * </ul>
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to false
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to false
 	 * when when connecting to the server then the subscription remains in place
 	 * until either:</p>
 	 * <ul>
 	 * <li>An unsubscribe method is called to unsubscribe the topic</li>
-	 * <li>The client connects with cleanSession set to true</li>
+	 * <li>The client connects with cleanStart set to true</li>
 	 * </ul>
 	 * <p>
-	 * With cleanSession set to false the MQTT server will store messages on
+	 * With cleanStart set to false the MQTT server will store messages on
 	 * behalf of the client when the client is not connected. The next time the
 	 * client connects with the <b>same client ID</b> the server will
 	 * deliver the stored messages to the client.
@@ -363,23 +363,23 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * will be discarded.
 	 * </p>
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to true
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to true
 	 * when when connecting to the server then the subscription remains in place
 	 * until either:</p>
 	 * <ul>
 	 * <li>The client disconnects</li>
 	 * <li>An unsubscribe method is called to un-subscribe the topic</li>
 	 * </ul>
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to false
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to false
 	 * when when connecting to the server then the subscription remains in place
 	 * until either:</p>
 	 * <ul>
 	 * <li>An unsubscribe method is called to unsubscribe the topic</li>
-	 * <li>The client connects with cleanSession set to true</li>
+	 * <li>The client connects with cleanStart set to true</li>
 	 * </ul>
 	 * <p>
-	 * With cleanSession set to false the MQTT server will store messages on
+	 * With cleanStart set to false the MQTT server will store messages on
 	 * behalf of the client when the client is not connected. The next time the
 	 * client connects with the <b>same client ID</b> the server will
 	 * deliver the stored messages to the client.
@@ -471,23 +471,23 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * will be discarded.
 	 * </p>
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to true
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to true
 	 * when when connecting to the server then the subscription remains in place
 	 * until either:</p>
 	 * <ul>
 	 * <li>The client disconnects</li>
 	 * <li>An unsubscribe method is called to un-subscribe the topic</li>
 	 * </ul>
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to false
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to false
 	 * when when connecting to the server then the subscription remains in place
 	 * until either:</p>
 	 * <ul>
 	 * <li>An unsubscribe method is called to unsubscribe the topic</li>
-	 * <li>The client connects with cleanSession set to true</li>
+	 * <li>The client connects with cleanStart set to true</li>
 	 * </ul>
 	 * <p>
-	 * With cleanSession set to false the MQTT server will store messages on
+	 * With cleanStart set to false the MQTT server will store messages on
 	 * behalf of the client when the client is not connected. The next time the
 	 * client connects with the <b>same client ID</b> the server will
 	 * deliver the stored messages to the client.
@@ -564,7 +564,7 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * will be discarded.
 	 * </p>
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to true
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to true
 	 * when when connecting to the server then the subscription remains in place
 	 * until either:</p>
 	 * <ul>
@@ -573,15 +573,15 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * </ul>
 	 * 
 	 * <p>
-	 * If (@link MqttConnectOptions#setCleanSession(boolean)} was set to false
+	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to false
 	 * when when connecting to the server then the subscription remains in place
 	 * until either:</p>
 	 * <ul>
 	 * <li>An unsubscribe method is called to unsubscribe the topic</li>
-	 * <li>The client connects with cleanSession set to true</li>
+	 * <li>The client connects with cleanStart set to true</li>
 	 * </ul>
 	 * <p>
-	 * With cleanSession set to false the MQTT server will store messages on
+	 * With cleanStart set to false the MQTT server will store messages on
 	 * behalf of the client when the client is not connected. The next time the
 	 * client connects with the <b>same client ID</b> the server will
 	 * deliver the stored messages to the client.
@@ -715,9 +715,9 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * a connection is re-established to the server on condition that:</p>
 	 * <ul>
 	 * <li>The connection is re-established with the same clientID</li>
-	 * <li>The original connection was made with (@link MqttConnectOptions#setCleanSession(boolean)}
+	 * <li>The original connection was made with (@link MqttConnectOptions#setCleanStart(boolean)}
 	 * set to false</li>
-	 * <li>The connection is re-established with (@link MqttConnectOptions#setCleanSession(boolean)}
+	 * <li>The connection is re-established with (@link MqttConnectOptions#setCleanStart(boolean)}
 	 * set to false</li>
 	 * </ul>
 	 * <p>In the event that the connection breaks or the client stops it is still possible to determine
@@ -860,9 +860,9 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * Alternately the {@link MqttCallback#deliveryComplete(IMqttDeliveryToken)}
 	 * callback can be used to track the delivery of outstanding messages.
 	 * </p>
-	 * <p>If a client connects with cleanSession true then there will be no
-	 * delivery tokens as the cleanSession option deletes all earlier state.
-	 * For state to be remembered the client must connect with cleanSession
+	 * <p>If a client connects with cleanStart true then there will be no
+	 * delivery tokens as the cleanStart option deletes all earlier state.
+	 * For state to be remembered the client must connect with cleanStart
 	 * set to false</P>
 	 * @return zero or more delivery tokens
 	 */

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/MqttActionListener.java

@@ -20,7 +20,7 @@ public interface MqttActionListener {
 	 * This method is invoked when an action fails.  
 	 * If a client is disconnected while an action is in progress 
 	 * onFailure will be called. For connections
-	 * that use cleanSession set to false, any QoS 1 and 2 messages that 
+	 * that use cleanStart set to false, any QoS 1 and 2 messages that 
 	 * are in the process of being delivered will be delivered to the requested
 	 * quality of service next time the client connects.  
 	 * @param asyncActionToken associated with the action that has failed

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/MqttAsyncClient.java

@@ -97,9 +97,9 @@
  * hence can be lost if the client, Java runtime or device shuts down.
  * </p>
  * <p>
- * If connecting with {@link MqttConnectionOptions#setCleanSession(boolean)} set
+ * If connecting with {@link MqttConnectionOptions#setCleanStart(boolean)} set
  * to true it is safe to use memory persistence as all state is cleared when a
- * client disconnects. If connecting with cleanSession set to false in order to
+ * client disconnects. If connecting with cleanStart set to false in order to
  * provide reliable message delivery then a persistent message store such as the
  * default one should be used.
  * </p>
@@ -422,8 +422,8 @@ public MqttAsyncClient(String serverURI, String clientId) throws MqttException {
 	 * {@link MqttClientPersistence} interface. An implementer of this interface
 	 * that safely stores messages must be specified in order for delivery of
 	 * messages to be reliable. In addition
-	 * {@link MqttConnectionOptions#setCleanSession(boolean)} must be set to false.
-	 * In the event that only QoS 0 messages are sent or received or cleanSession is
+	 * {@link MqttConnectionOptions#setCleanStart(boolean)} must be set to false.
+	 * In the event that only QoS 0 messages are sent or received or cleanStart is
 	 * set to true then a safe store is not needed.
 	 * </p>
 	 * <p>
@@ -525,8 +525,8 @@ public MqttAsyncClient(String serverURI, String clientId, MqttClientPersistence
 	 * {@link MqttClientPersistence} interface. An implementer of this interface
 	 * that safely stores messages must be specified in order for delivery of
 	 * messages to be reliable. In addition
-	 * {@link MqttConnectionOptions#setCleanSession(boolean)} must be set to false.
-	 * In the event that only QoS 0 messages are sent or received or cleanSession is
+	 * {@link MqttConnectionOptions#setCleanStart(boolean)} must be set to false.
+	 * In the event that only QoS 0 messages are sent or received or cleanStart is
 	 * set to true then a safe store is not needed.
 	 * </p>
 	 * <p>
@@ -880,10 +880,10 @@ public IMqttToken connect(MqttConnectionOptions options, Object userContext, Mqt
 		this.userContext = userContext;
 		final boolean automaticReconnect = options.isAutomaticReconnect();
 
-		// @TRACE 103=cleanSession={0} connectionTimeout={1} TimekeepAlive={2}
+		// @TRACE 103=cleanStart={0} connectionTimeout={1} TimekeepAlive={2}
 		// userName={3} password={4} will={5} userContext={6} callback={7}
 		log.fine(CLASS_NAME, methodName, "103",
-				new Object[] { Boolean.valueOf(options.isCleanSession()), new Integer(options.getConnectionTimeout()),
+				new Object[] { Boolean.valueOf(options.isCleanStart()), new Integer(options.getConnectionTimeout()),
 						new Integer(options.getKeepAliveInterval()), options.getUserName(),
 						((null == options.getPassword()) ? "[null]" : "[notnull]"),
 						((null == options.getWillMessage()) ? "[null]" : "[notnull]"), userContext, callback });
@@ -906,11 +906,11 @@ public IMqttToken connect(MqttConnectionOptions options, Object userContext, Mqt
 			connectActionListener.setMqttCallbackExtended((MqttCallback) this.mqttCallback);
 		}
 
-		if (this.connOpts.isCleanSession()) {
+		if (this.connOpts.isCleanStart()) {
 			this.mqttSession.clearSession();
 		}
 
-		if (this.connOpts.isCleanSession()) {
+		if (this.connOpts.isCleanStart()) {
 			this.mqttSession.clearSession();
 		}
 

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/MqttConnectionOptions.java

@@ -99,7 +99,7 @@ public void setWillMessageProperties(MqttProperties willMessageProperties) {
 
 	// Connection packet properties
 	private int mqttVersion = 5; // MQTT Version 5
-	private boolean cleanSession = true; // Clean Session
+	private boolean cleanStart = true; // Clean Session
 	private String willDestination = null; // Will Topic
 	private MqttMessage willMessage = null; // Will Message
 	private String userName; // Username
@@ -215,8 +215,8 @@ public void setWill(String topic, MqttMessage message) {
 	 * 
 	 * @return the clean session flag
 	 */
-	public boolean isCleanSession() {
-		return this.cleanSession;
+	public boolean isCleanStart() {
+		return this.cleanStart;
 	}
 
 	/**
@@ -240,11 +240,11 @@ public boolean isCleanSession() {
 	 * </ul>
 	 * </ul>
 	 * 
-	 * @param cleanSession
+	 * @param cleanStart
 	 *            Set to True to enable cleanSession
 	 */
-	public void setCleanSession(boolean cleanSession) {
-		this.cleanSession = cleanSession;
+	public void setCleanStart(boolean cleanStart) {
+		this.cleanStart = cleanStart;
 	}
 
 	/**
@@ -368,15 +368,15 @@ public String[] getServerURIs() {
 	 * connects to.
 	 * </p>
 	 * <p>
-	 * The cleansession flag must be set to false if durable subscriptions and/or
+	 * The cleanStart flag must be set to false if durable subscriptions and/or
 	 * reliable message delivery is required.
 	 * </p>
 	 * </li>
 	 * <li>Hunt List
 	 * <p>
 	 * 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
+	 * message delivery and durable subscriptions are not valid. The cleanStart
 	 * flag must be set to true if the hunt list mode is used
 	 * </p>
 	 * </li>
@@ -914,7 +914,7 @@ public Properties getDebug() {
 		final String strNull = "null";
 		Properties p = new Properties();
 		p.put("MqttVersion", getMqttVersion());
-		p.put("CleanSession", Boolean.valueOf(isCleanSession()));
+		p.put("CleanStart", Boolean.valueOf(isCleanStart()));
 		p.put("ConTimeout", getConnectionTimeout());
 		p.put("KeepAliveInterval", getKeepAliveInterval());
 		p.put("UserName", (getUserName() == null) ? strNull : getUserName());

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/MqttConnectionOptionsBuilder.java

@@ -42,8 +42,8 @@ public MqttConnectionOptionsBuilder connectionTimeout(int connectionTimeout) {
 		return this;
 	}
 
-	public MqttConnectionOptionsBuilder cleanSession(boolean cleanSession) {
-		mqttConnectionOptions.setCleanSession(cleanSession);
+	public MqttConnectionOptionsBuilder cleanStart(boolean cleanStart) {
+		mqttConnectionOptions.setCleanStart(cleanStart);
 		return this;
 	}