doc(iot-dev): Add notes in javadocs about when subscriptions are pres…

…erved (#1619)

Twin and methods subscriptions are preserved only through retry whereas c2d callback is preserved even when the client is closed.

device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/DeviceClient.java

@@ -146,7 +146,13 @@ public DeviceClient(String uri, String deviceId, SecurityProvider securityProvid
 
     /**
      * Sets the message callback.
-     *
+     * <p>
+     * This should be set before opening the client. If it is set after opening the client, any messages sent by the
+     * service may be missed.
+     * </p>
+     * <p>
+     * This callback is preserved between reconnection attempts and preserved after re-opening a previously closed client.
+     * </p>
      * @param callback the message callback. Can be {@code null}.
      * @param context the context to be passed to the callback. Can be {@code null}.
      *

device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/InternalClient.java

@@ -314,7 +314,14 @@ public void sendEvents(List<Message> messages, int timeoutMilliseconds)
     /**
      * Start receiving desired property updates for this client. After subscribing to desired properties, this client can
      * freely send reported property updates and make getTwin calls.
-     *
+     * <p>
+     * This call can only be made after the client has been successfully opened.
+     * </p>
+     * <p>
+     * This subscription is preserved between reconnect attempts. However, it is not preserved after a client has
+     * been closed because the user called {@link #close()} or because this client lost its connection and its retry
+     * policy was exhausted.
+     * </p>
      * @param desiredPropertiesCallback The callback to execute each time a desired property update message is received
      * from the service. This will contain one or many properties updated at once.
      * @param desiredPropertiesCallbackContext The context that will be included in the callback of desiredPropertiesCallback. May be null.
@@ -331,7 +338,14 @@ public void subscribeToDesiredProperties(DesiredPropertiesCallback desiredProper
     /**
      * Start receiving desired property updates for this client. After subscribing to desired properties, this client can
      * freely send reported property updates and make getTwin calls.
-     *
+     * <p>
+     * This call can only be made after the client has been successfully opened.
+     * </p>
+     * <p>
+     * This subscription is preserved between reconnect attempts. However, it is not preserved after a client has
+     * been closed because the user called {@link #close()} or because this client lost its connection and its retry
+     * policy was exhausted.
+     * </p>
      * @param desiredPropertiesCallback The callback to execute each time a desired property update message is received
      * from the service. This will contain one or many properties updated at once.
      * @param desiredPropertiesCallbackContext The context that will be included in the callback of desiredPropertiesCallback. May be null.
@@ -520,8 +534,15 @@ public Twin getTwin(int timeoutMilliseconds) throws InterruptedException, Illega
     }
 
     /**
-     * Subscribes to direct methods
-     *
+     * Subscribes to direct methods.
+     * <p>
+     * This call can only be made after the client has been successfully opened.
+     * </p>
+     * <p>
+     * This subscription is preserved between reconnect attempts. However, it is not preserved after a client has
+     * been closed because the user called {@link #close()} or because this client lost its connection and its retry
+     * policy was exhausted.
+     * </p>
      * @param methodCallback Callback on which direct methods shall be invoked. Cannot be {@code null}.
      * @param methodCallbackContext Context for device method callback. Can be {@code null}.
      *
@@ -536,8 +557,15 @@ public void subscribeToMethods(MethodCallback methodCallback, Object methodCallb
     }
 
     /**
-     * Subscribes to direct methods
-     *
+     * Subscribes to direct methods.
+     * <p>
+     * This call can only be made after the client has been successfully opened.
+     * </p>
+     * <p>
+     * This subscription is preserved between reconnect attempts. However, it is not preserved after a client has
+     * been closed because the user called {@link #close()} or because this client lost its connection and its retry
+     * policy was exhausted.
+     * </p>
      * @param methodCallback Callback on which direct methods shall be invoked. Cannot be {@code null}.
      * @param methodCallbackContext Context for device method callback. Can be {@code null}.
      * @param timeoutMilliseconds The maximum number of milliseconds this call will wait for the service to return the twin.
@@ -652,7 +680,14 @@ public void sendEventsAsync(List<Message> messages, MessagesSentCallback callbac
     /**
      * Start receiving desired property updates for this client asynchronously. After subscribing to desired properties, this client can
      * freely send reported property updates and make getTwin calls.
-     *
+     * <p>
+     * This call can only be made after the client has been successfully opened.
+     * </p>
+     * <p>
+     * This subscription is preserved between reconnect attempts. However, it is not preserved after a client has
+     * been closed because the user called {@link #close()} or because this client lost its connection and its retry
+     * policy was exhausted.
+     * </p>
      * @param subscriptionAcknowledgedCallback The callback to execute once the service has acknowledged the subscription request.
      * @param desiredPropertiesSubscriptionCallbackContext The context that will be included in the callback of desiredPropertiesSubscriptionCallback. May be null.
      * @param desiredPropertiesCallback The callback to execute each time a desired property update message is received
@@ -846,8 +881,15 @@ public void getTwinAsync(GetTwinCorrelatingMessageCallback twinCallback, Object
     }
 
     /**
-     * Subscribes to direct methods
-     *
+     * Subscribes to direct methods.
+     * <p>
+     * This call can only be made after the client has been successfully opened.
+     * </p>
+     * <p>
+     * This subscription is preserved between reconnect attempts. However, it is not preserved after a client has
+     * been closed because the user called {@link #close()} or because this client lost its connection and its retry
+     * policy was exhausted.
+     * </p>
      * @param methodCallback Callback on which direct methods shall be invoked. Cannot be {@code null}.
      * @param methodCallbackContext Context for device method callback. Can be {@code null}.
      * @param methodStatusCallback Callback for providing IotHub status for direct methods. Cannot be {@code null}.

device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/ModuleClient.java

@@ -495,7 +495,13 @@ public DirectMethodResponse invokeMethod(String deviceId, String moduleId, Direc
 
     /**
      * Sets the message callback.
-     *
+     * <p>
+     * This should be set before opening the client. If it is set after opening the client, any messages sent by the
+     * service may be missed.
+     * </p>
+     * <p>
+     * This callback is preserved between reconnection attempts and preserved after re-opening a previously closed client.
+     * </p>
      * @param callback the message callback. Can be {@code null}.
      * @param context the context to be passed to the callback. Can be {@code null}.
      *