Add more detailed javadoc for the drop related api to warn about the …

…pitfalls

src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestChannel.java

@@ -82,6 +82,12 @@ public interface SnowflakeStreamingIngestChannel {
   /**
    * Close the channel, this function will make sure all the data in this channel is committed
    *
+   * <p>Note that this call with drop=true will delete <a
+   * href=https://docs.snowflake.com/en/user-guide/data-load-snowpipe-streaming-overview#offset-tokens>Offset
+   * Token</a> information from Snowflake servers unless the channel has already been opened in
+   * another client. So only use it if you are completely done ingesting data for this channel. If
+   * you open a channel with the same name in the future, it will behave like a new channel.
+   *
    * @param drop if true, the channel will be dropped after all data is successfully committed.
    * @return a completable future which will be completed when the channel is closed
    */

src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestClient.java

@@ -28,9 +28,15 @@ public interface SnowflakeStreamingIngestClient extends AutoCloseable {
   /**
    * Drop the specified channel on the server using a {@link DropChannelRequest}
    *
-   * <p>Note that this call will blindly drop the latest version of the channel and any pending data
-   * will be lost. Also see {@link SnowflakeStreamingIngestChannel#close(boolean)} to drop channels
-   * on close. That approach will drop the local version of the channel and if the channel has been
+   * <p>Note that this call will <em>blindly</em> drop the latest version of the channel and any
+   * pending data will be lost. It will also delete <a
+   * href=https://docs.snowflake.com/en/user-guide/data-load-snowpipe-streaming-overview#offset-tokens>Offset
+   * Token</a> information from Snowflake servers. So only use it if you are completely done
+   * ingesting data for this channel. If you open a channel with the same name in the future, it
+   * will behave like a new channel.
+   *
+   * <p>Also see {@link SnowflakeStreamingIngestChannel#close(boolean)} to drop channels on close.
+   * That approach will drop the local version of the channel and if the channel has been
    * concurrently reopened by another client, that version of the channel won't be affected.
    *
    * @param request the drop channel request