[mina-sshd] branch master updated: [SSHD-910] Fixed Javadoc example for SshClient usage to open SSH session(s)

[lg...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lgoldstein pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mina-sshd.git


The following commit(s) were added to refs/heads/master by this push:
     new e068e1c  [SSHD-910] Fixed Javadoc example for SshClient usage to open SSH session(s)
e068e1c is described below

commit e068e1cdbfccc5a36ef27a687af95552af4b863a
Author: Lyor Goldstein <lg...@apache.org>
AuthorDate: Wed Apr 10 20:51:20 2019 +0300

    [SSHD-910] Fixed Javadoc example for SshClient usage to open SSH session(s)
---
 .../src/main/java/org/apache/sshd/client/SshClient.java  | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/sshd-core/src/main/java/org/apache/sshd/client/SshClient.java b/sshd-core/src/main/java/org/apache/sshd/client/SshClient.java
index b711693..4515b32 100644
--- a/sshd-core/src/main/java/org/apache/sshd/client/SshClient.java
+++ b/sshd-core/src/main/java/org/apache/sshd/client/SshClient.java
@@ -94,7 +94,7 @@ import org.apache.sshd.common.util.net.SshdSocketAddress;
  * <P>
  * The default configured client can be created using
  * the {@link #setUpDefaultClient()}. The next step is to
- * start the client using the {@link #start()} method.
+ * configure and then start the client using the {@link #start()} method.
  * </P>
  *
  * <P>
@@ -113,9 +113,12 @@ import org.apache.sshd.common.util.net.SshdSocketAddress;
  *
  * <pre><code>
  * try (SshClient client = SshClient.setUpDefaultClient()) {
+ *      ...further configuration of the client...
  *      client.start();
  *
- *      try (ClientSession session = client.connect(login, host, port).await().getSession()) {
+ *      try (ClientSession session = client.connect(login, host, port)
+ *                  .verify(...timeout...)
+ *                  .getSession()) {
  *          session.addPasswordIdentity(password);
  *          session.auth().verify(...timeout...);
  *
@@ -134,6 +137,15 @@ import org.apache.sshd.common.util.net.SshdSocketAddress;
  * }
  * </code></pre>
  *
+ * <B>Note</B>: the idea is to have <U>one</U> {@code SshClient} instance
+ * for the entire application and re-use it repeatedly  in order to create
+ * as many sessions as necessary - possibly with different hosts, ports, users,
+ * passwords, etc. - including <U>concurrently</U>. In other words, except for
+ * exceptional cases, it is recommended to initialize one instance of {@code SshClient}
+ * for the application and then use throughout - including for multi-threading.
+ * As long as the {@code SshClient} is not re-configured it should be multi-thread safe
+ * regardless of the target session being created.
+
  * @author <a href="mailto:dev@mina.apache.org">Apache MINA SSHD Project</a>
  */
 public class SshClient extends AbstractFactoryManager implements ClientFactoryManager, ClientSessionCreator, Closeable {