[SSHD-542] Checkstyle validation Fixed (a lot) of Javadoc issues
Project: http://git-wip-us.apache.org/repos/asf/mina-sshd/repo Commit: http://git-wip-us.apache.org/repos/asf/mina-sshd/commit/61e637c4 Tree: http://git-wip-us.apache.org/repos/asf/mina-sshd/tree/61e637c4 Diff: http://git-wip-us.apache.org/repos/asf/mina-sshd/diff/61e637c4 Branch: refs/heads/master Commit: 61e637c48348cc8ab6330a749ef1fe9be6d0fb36 Parents: 1a51446 Author: Lyor Goldstein <[email protected]> Authored: Tue Jul 28 15:07:30 2015 +0300 Committer: Lyor Goldstein <[email protected]> Committed: Tue Jul 28 15:07:30 2015 +0300 ---------------------------------------------------------------------- pom.xml | 5 + .../org/apache/sshd/agent/SshAgentFactory.java | 13 +- .../org/apache/sshd/agent/unix/AprLibrary.java | 8 +- .../java/org/apache/sshd/client/SshClient.java | 52 ++++--- .../client/channel/AbstractClientChannel.java | 8 +- .../channel/PtyCapableChannelSession.java | 56 +++---- .../sshd/client/config/keys/ClientIdentity.java | 2 + .../apache/sshd/client/future/AuthFuture.java | 15 +- .../sshd/client/future/ConnectFuture.java | 27 +++- .../apache/sshd/client/future/OpenFuture.java | 21 ++- .../sshd/client/session/ClientSession.java | 88 +++++++++-- .../subsystem/sftp/DefaultSftpClient.java | 13 ++ .../sshd/client/subsystem/sftp/SftpClient.java | 1 + .../sftp/extensions/CopyFileExtension.java | 2 +- .../impl/AbstractSftpClientExtension.java | 8 +- .../openssh/OpenSSHFsyncExtension.java | 2 +- .../org/apache/sshd/common/BaseBuilder.java | 5 +- .../org/apache/sshd/common/FactoryManager.java | 16 +- .../org/apache/sshd/common/NamedResource.java | 2 + .../org/apache/sshd/common/ServiceFactory.java | 1 + .../apache/sshd/common/SshdSocketAddress.java | 4 +- .../org/apache/sshd/common/channel/Channel.java | 42 +++++- .../common/channel/ChannelAsyncInputStream.java | 2 +- .../channel/ChannelAsyncOutputStream.java | 2 +- .../apache/sshd/common/channel/SttySupport.java | 149 +++++++++++-------- .../sshd/common/config/SshConfigFileReader.java | 7 +- .../sshd/common/config/keys/KeyUtils.java | 18 +-- .../sshd/common/config/keys/PublicKeyEntry.java | 14 +- .../sshd/common/file/util/ImmutableList.java | 2 +- .../forward/DefaultTcpipForwarderFactory.java | 1 - .../sshd/common/forward/TcpipForwarder.java | 40 +++-- .../apache/sshd/common/future/CloseFuture.java | 2 +- .../sshd/common/future/DefaultCloseFuture.java | 3 + .../sshd/common/future/DefaultSshFuture.java | 38 +++-- .../apache/sshd/common/future/SshFuture.java | 16 +- .../apache/sshd/common/io/IoConnectFuture.java | 14 +- .../apache/sshd/common/io/IoInputStream.java | 3 + .../apache/sshd/common/io/IoOutputStream.java | 5 +- .../org/apache/sshd/common/io/IoSession.java | 12 +- .../apache/sshd/common/io/IoWriteFuture.java | 4 +- .../sshd/common/kex/KexProposalOption.java | 2 +- .../org/apache/sshd/common/kex/KeyExchange.java | 8 +- .../org/apache/sshd/common/random/Random.java | 3 + .../session/AbstractConnectionService.java | 4 +- .../sshd/common/session/AbstractSession.java | 34 +++-- .../sshd/common/session/ConnectionService.java | 5 +- .../org/apache/sshd/common/session/Session.java | 25 +++- .../sshd/common/session/SessionListener.java | 10 +- .../common/signature/BuiltinSignatures.java | 2 +- .../subsystem/sftp/extensions/ParserUtils.java | 2 +- .../openssh/FsyncExtensionParser.java | 2 +- .../openssh/HardLinkExtensionParser.java | 2 +- .../openssh/PosixRenameExtensionParser.java | 2 +- .../openssh/StatVfsExtensionParser.java | 2 +- .../org/apache/sshd/common/util/Base64.java | 16 +- .../apache/sshd/common/util/CloseableUtils.java | 10 +- .../sshd/common/util/DirectoryScanner.java | 25 ++-- .../sshd/common/util/EventListenerUtils.java | 50 +++++-- .../apache/sshd/common/util/GenericUtils.java | 8 +- .../apache/sshd/common/util/SelectorUtils.java | 32 ++-- .../apache/sshd/common/util/buffer/Buffer.java | 13 +- .../sshd/common/util/buffer/BufferUtils.java | 31 ++-- .../apache/sshd/common/util/io/DERParser.java | 12 +- .../org/apache/sshd/common/util/io/IoUtils.java | 14 +- .../sshd/common/util/logging/LoggingUtils.java | 34 +++-- .../sshd/common/util/threads/ThreadUtils.java | 18 +-- .../org/apache/sshd/server/AsyncCommand.java | 6 +- .../java/org/apache/sshd/server/Command.java | 20 ++- .../org/apache/sshd/server/CommandFactory.java | 4 +- .../org/apache/sshd/server/SignalListener.java | 2 +- .../java/org/apache/sshd/server/SshServer.java | 17 ++- .../org/apache/sshd/server/auth/UserAuth.java | 3 +- .../sshd/server/auth/UserAuthPassword.java | 2 +- .../sshd/server/auth/gss/UserAuthGSS.java | 4 +- .../server/channel/AbstractServerChannel.java | 10 +- .../server/channel/ChannelDataReceiver.java | 51 ++++--- .../sshd/server/channel/ChannelSession.java | 2 + .../sshd/server/config/keys/ServerIdentity.java | 3 +- .../sshd/server/forward/ForwardingFilter.java | 24 ++- .../apache/sshd/server/shell/InvertedShell.java | 16 +- .../server/subsystem/sftp/SftpSubsystem.java | 1 + .../server/subsystem/sftp/UnixDateFormat.java | 4 + .../java/org/apache/sshd/WindowAdjustTest.java | 6 +- .../java/org/apache/sshd/server/ServerTest.java | 4 +- .../server/command/ScpCommandFactoryTest.java | 2 +- .../sftp/SftpSubsystemFactoryTest.java | 2 +- 86 files changed, 820 insertions(+), 452 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index 98acb00..4b9b8ae 100644 --- a/pom.xml +++ b/pom.xml @@ -400,6 +400,11 @@ <artifactId>maven-source-plugin</artifactId> <version>2.4</version> </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>2.10.3</version> + </plugin> </plugins> </pluginManagement> http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/agent/SshAgentFactory.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/agent/SshAgentFactory.java b/sshd-core/src/main/java/org/apache/sshd/agent/SshAgentFactory.java index 771d5e2..2684559 100644 --- a/sshd-core/src/main/java/org/apache/sshd/agent/SshAgentFactory.java +++ b/sshd-core/src/main/java/org/apache/sshd/agent/SshAgentFactory.java @@ -35,7 +35,7 @@ public interface SshAgentFactory { * The channel will receive agent requests and need to forward them to the agent, * either local or through another proxy. * - * @return The channel factory used to create channels on the client side + * @return The (named) channel factory used to create channels on the client side */ NamedFactory<Channel> getChannelForwardingFactory(); @@ -43,8 +43,9 @@ public interface SshAgentFactory { * Create an SshAgent that can be used on the client side by the authentication * process to send possible keys. * - * @param manager - * @return + * @param manager The {@link FactoryManager} instance + * @return The {@link SshAgent} instance + * @throws IOException If failed to create the client */ SshAgent createClient(FactoryManager manager) throws IOException; @@ -53,9 +54,9 @@ public interface SshAgentFactory { * It will usually create a channel that will forward the requests * to the original client. * - * @param service - * @return + * @param service The {@link ConnectionService} to use + * @return The {@link SshAgentServer} instance + * @throws IOException If failed to create the server */ SshAgentServer createServer(ConnectionService service) throws IOException; - } http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/agent/unix/AprLibrary.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/agent/unix/AprLibrary.java b/sshd-core/src/main/java/org/apache/sshd/agent/unix/AprLibrary.java index 8e78735..282fe4f 100644 --- a/sshd-core/src/main/java/org/apache/sshd/agent/unix/AprLibrary.java +++ b/sshd-core/src/main/java/org/apache/sshd/agent/unix/AprLibrary.java @@ -27,11 +27,15 @@ import org.apache.tomcat.jni.Pool; /** + * <p> * Internal singleton used for initializing correctly the APR native library * and the associated root memory pool. - * <p/> + * </p> + * + * <p> * It'll finalize nicely the native resources (libraries and memory pools). - * <p/> + * </p> + * * Each memory pool used in the APR transport module needs to be children of the * root pool {@link AprLibrary#getRootPool()}. * http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/SshClient.java ---------------------------------------------------------------------- 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 94ad2d7..0e651d8 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 @@ -76,37 +76,51 @@ import org.apache.sshd.common.util.io.NoCloseInputStream; import org.apache.sshd.common.util.io.NoCloseOutputStream; /** + * <P> * Entry point for the client side of the SSH protocol. - * <p/> + * </P> + * + * <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. - * <p/> + * </P> + * + * <P> * Sessions can then be created using on of the * {@link #connect(String, String, int)} or {@link #connect(String, java.net.SocketAddress)} * methods. - * <p/> - * The client can be stopped at anytime using the {@link #stop()} method. - * <p/> - * Following is an example of using the SshClient: + * </P> + * + * <P> + * The client can be stopped any time using the {@link #stop()} method. + * </P> + * + * <P> + * Following is an example of using the {@code SshClient}: + * </P> + * * <pre> - * SshClient client = SshClient.setUpDefaultClient(); - * client.start(); - * try { - * ClientSession session = client.connect(login, host, port).await().getSession(); - * session.addPasswordIdentity(password); - * session.auth().verify(); + * try(SshClient client = SshClient.setUpDefaultClient()) { + * client.start(); + * + * try(ClientSession session = client.connect(login, host, port).await().getSession()) { + * session.addPasswordIdentity(password); + * session.auth().verify(); * - * ClientChannel channel = session.createChannel("shell"); - * channel.setIn(new NoCloseInputStream(System.in)); - * channel.setOut(new NoCloseOutputStream(System.out)); - * channel.setErr(new NoCloseOutputStream(System.err)); - * channel.open(); - * channel.waitFor(ClientChannel.CLOSED, 0); - * session.close(false); + * try(ClientChannel channel = session.createChannel("shell")) { + * channel.setIn(new NoCloseInputStream(System.in)); + * channel.setOut(new NoCloseOutputStream(System.out)); + * channel.setErr(new NoCloseOutputStream(System.err)); + * channel.open(); + * channel.waitFor(ClientChannel.CLOSED, 0); + * } finally { + * session.close(false); + * } * } finally { * client.stop(); * } + * } * </pre> * * @author <a href="mailto:[email protected]";>Apache MINA SSHD Project</a> http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/channel/AbstractClientChannel.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/channel/AbstractClientChannel.java b/sshd-core/src/main/java/org/apache/sshd/client/channel/AbstractClientChannel.java index e9dd0da..69a4505 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/channel/AbstractClientChannel.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/channel/AbstractClientChannel.java @@ -242,14 +242,14 @@ public abstract class AbstractClientChannel extends AbstractChannel implements C } @Override - public OpenFuture open(int recipient, int rwsize, int rmpsize, Buffer buffer) { - throw new IllegalStateException(); + public OpenFuture open(int recipient, int rwSize, int packetSize, Buffer buffer) { + throw new UnsupportedOperationException("open(" + recipient + "," + rwSize + "," + packetSize + ") N/A"); } @Override - public void handleOpenSuccess(int recipient, int rwsize, int rmpsize, Buffer buffer) { + public void handleOpenSuccess(int recipient, int rwSize, int packetSize, Buffer buffer) { this.recipient = recipient; - this.remoteWindow.init(rwsize, rmpsize, session.getFactoryManager().getProperties()); + this.remoteWindow.init(rwSize, packetSize, session.getFactoryManager().getProperties()); try { doOpen(); this.opened.set(true); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/channel/PtyCapableChannelSession.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/channel/PtyCapableChannelSession.java b/sshd-core/src/main/java/org/apache/sshd/client/channel/PtyCapableChannelSession.java index 5620c27..43dc700 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/channel/PtyCapableChannelSession.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/channel/PtyCapableChannelSession.java @@ -39,34 +39,36 @@ import org.apache.sshd.common.util.buffer.ByteArrayBuffer; * open. If they are invoked afterwards then they have no effect (silently * ignored).</P> * <P>A typical code snippet would be:</P> - * <CODE><PRE> - * client = SshClient.setUpDefaultClient(); - * client.start(); - * <p/> - * try(ClientSession s = client.connect(getCurrentTestName(), "localhost", port).verify(7L, TimeUnit.SECONDS).getSession()) { - * s.addPasswordIdentity(getCurrentTestName()); - * s.auth().verify(5L, TimeUnit.SECONDS); - * <p/> - * try(ChannelExec shell = s.createExecChannel("my super duper command")) { - * shell.setEnv("var1", "val1"); - * shell.setEnv("var2", "val2"); - * ...etc... - * shell.setPtyType(...); - * shell.setPtyLines(...); - * ...etc... - * <p/> - * shell.open().verify(5L, TimeUnit.SECONDS); - * shell.waitFor(ClientChannel.CLOSED, TimeUnit.SECONDS.toMillis(17L)); // can use zero for infinite wait - * <p/> - * Integer status = shell.getExitStatus(); - * if (status.intValue() != 0) { - * ...error... - * } - * } - * } finally { - * client.stop(); + * <PRE> + * try(client = SshClient.setUpDefaultClient()) { + * client.start(); + * + * try(ClientSession s = client.connect(getCurrentTestName(), "localhost", port).verify(7L, TimeUnit.SECONDS).getSession()) { + * s.addPasswordIdentity(getCurrentTestName()); + * s.auth().verify(5L, TimeUnit.SECONDS); + * + * try(ChannelExec shell = s.createExecChannel("my super duper command")) { + * shell.setEnv("var1", "val1"); + * shell.setEnv("var2", "val2"); + * ...etc... + * + * shell.setPtyType(...); + * shell.setPtyLines(...); + * ...etc... + * + * shell.open().verify(5L, TimeUnit.SECONDS); + * shell.waitFor(ClientChannel.CLOSED, TimeUnit.SECONDS.toMillis(17L)); // can use zero for infinite wait + * + * Integer status = shell.getExitStatus(); + * if (status.intValue() != 0) { + * ...error... + * } + * } + * } finally { + * client.stop(); + * } * } - * </PRE></CODE> + * </PRE> * * @author <a href="mailto:[email protected]";>Apache MINA SSHD Project</a> */ http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/config/keys/ClientIdentity.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/config/keys/ClientIdentity.java b/sshd-core/src/main/java/org/apache/sshd/client/config/keys/ClientIdentity.java index 8204890..8412e49 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/config/keys/ClientIdentity.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/config/keys/ClientIdentity.java @@ -103,6 +103,7 @@ public final class ClientIdentity { } /** + * @param <C> The generic client class * @param client The {@link SshClient} to updated * @param strict If {@code true} then files that do not have the required * access rights are excluded from consideration @@ -128,6 +129,7 @@ public final class ClientIdentity { } /** + * @param <C> The generic client class * @param client The {@link SshClient} to updated * @param dir The folder to scan for the built-in identities * @param strict If {@code true} then files that do not have the required http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/future/AuthFuture.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/future/AuthFuture.java b/sshd-core/src/main/java/org/apache/sshd/client/future/AuthFuture.java index 2972567..33b64e0 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/future/AuthFuture.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/future/AuthFuture.java @@ -39,6 +39,8 @@ public interface AuthFuture extends SshFuture<AuthFuture> { /** * Wait and verify that the authentication succeeded within the specified timeout. * + * @param timeout The number of time units + * @param unit The {@link TimeUnit} for the timeout * @throws IOException if the authentication failed for any reason */ void verify(long timeout, TimeUnit unit) throws IOException; @@ -46,6 +48,7 @@ public interface AuthFuture extends SshFuture<AuthFuture> { /** * Wait and verify that the authentication succeeded within the specified timeout. * + * @param timeoutMillis Timeout in milliseconds * @throws IOException if the authentication failed for any reason */ void verify(long timeoutMillis) throws IOException; @@ -53,23 +56,23 @@ public interface AuthFuture extends SshFuture<AuthFuture> { /** * Returns the cause of the connection failure. * - * @return <tt>null</tt> if the connect operation is not finished yet, + * @return <code>null</code> if the connect operation is not finished yet, * or if the connection attempt is successful. */ Throwable getException(); /** - * Returns <tt>true</tt> if the authentication operation is finished successfully. + * @return <code>true</code> if the authentication operation is finished successfully. */ boolean isSuccess(); /** - * Returns <tt>false</tt> if the authentication operation failed. + * @return <code>false</code> if the authentication operation failed. */ boolean isFailure(); /** - * Returns {@code true} if the connect operation has been canceled by + * @return {@code true} if the connect operation has been canceled by * {@link #cancel()} method. */ boolean isCanceled(); @@ -78,6 +81,8 @@ public interface AuthFuture extends SshFuture<AuthFuture> { * Notifies that the session has been authenticated. * This method is invoked by SSHD internally. Please do not * call this method directly. + * + * @param authed Authentication success state */ void setAuthed(boolean authed); @@ -85,6 +90,8 @@ public interface AuthFuture extends SshFuture<AuthFuture> { * Sets the exception caught due to connection failure and notifies all * threads waiting for this future. This method is invoked by SSHD * internally. Please do not call this method directly. + * + * @param exception The caught {@link Throwable} */ void setException(Throwable exception); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/future/ConnectFuture.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/future/ConnectFuture.java b/sshd-core/src/main/java/org/apache/sshd/client/future/ConnectFuture.java index 43fe89b..5000065 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/future/ConnectFuture.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/future/ConnectFuture.java @@ -31,28 +31,43 @@ import org.apache.sshd.common.future.SshFuture; */ public interface ConnectFuture extends SshFuture<ConnectFuture> { + /** + * @return The referenced {@link ClientSession} + */ ClientSession getSession(); - // wait and verify that connection succeeded within specified timeout + /** + * Wait and verify that connection succeeded within specified timeout + * + * @param count The number of time units to wait + * @param unit The {@link TimeUnit} for waiting + * @return The {@link ConnectFuture} + * @throws IOException If failed to verify the request on time + */ ConnectFuture verify(long count, TimeUnit unit) throws IOException; + /** + * @param timeout The wait timeout in milliseconds + * @return The {@link ConnectFuture} + * @throws IOException If failed to verify the request on time + */ ConnectFuture verify(long timeout) throws IOException; /** * Returns the cause of the connection failure. * - * @return <tt>null</tt> if the connect operation is not finished yet, + * @return <code>null</code> if the connect operation is not finished yet, * or if the connection attempt is successful. */ Throwable getException(); /** - * Returns <tt>true</tt> if the connect operation is finished successfully. + * @return <code>true</code> if the connect operation is finished successfully. */ boolean isConnected(); /** - * Returns {@code true} if the connect operation has been canceled by + * @return {@code true} if the connect operation has been canceled by * {@link #cancel()} method. */ boolean isCanceled(); @@ -61,6 +76,8 @@ public interface ConnectFuture extends SshFuture<ConnectFuture> { * Sets the newly connected session and notifies all threads waiting for * this future. This method is invoked by SSHD internally. Please do not * call this method directly. + * + * @param session The {@link ClientSession} */ void setSession(ClientSession session); @@ -68,6 +85,8 @@ public interface ConnectFuture extends SshFuture<ConnectFuture> { * Sets the exception caught due to connection failure and notifies all * threads waiting for this future. This method is invoked by SSHD * internally. Please do not call this method directly. + * + * @param exception The caught {@link Throwable} */ void setException(Throwable exception); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/future/OpenFuture.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/future/OpenFuture.java b/sshd-core/src/main/java/org/apache/sshd/client/future/OpenFuture.java index 116f9e5..7e6e03b 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/future/OpenFuture.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/future/OpenFuture.java @@ -36,25 +36,38 @@ public interface OpenFuture extends SshFuture<OpenFuture> { */ void verify() throws IOException; + /** + * Wait and verify that the channel has been successfully opened. + * + * @param timeout The number of time units to wait + * @param unit The wait {@link TimeUnit} + * @throws IOException If failed to verify successfully on time + */ void verify(long timeout, TimeUnit unit) throws IOException; + /** + * Wait and verify that the channel has been successfully opened. + * + * @param timeoutMillis Wait timeout in milliseconds + * @throws IOException If failed to verify successfully on time + */ void verify(long timeoutMillis) throws IOException; /** * Returns the cause of the connection failure. * - * @return <tt>null</tt> if the connect operation is not finished yet, + * @return <code>null</code> if the connect operation is not finished yet, * or if the connection attempt is successful. */ Throwable getException(); /** - * Returns <tt>true</tt> if the connect operation is finished successfully. + * @return <code>true</code> if the connect operation is finished successfully. */ boolean isOpened(); /** - * Returns {@code true} if the connect operation has been canceled by + * @return {@code true} if the connect operation has been canceled by * {@link #cancel()} method. */ boolean isCanceled(); @@ -70,6 +83,8 @@ public interface OpenFuture extends SshFuture<OpenFuture> { * Sets the exception caught due to connection failure and notifies all * threads waiting for this future. This method is invoked by SSHD * internally. Please do not call this method directly. + * + * @param exception The caught {@link Throwable} */ void setException(Throwable exception); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/session/ClientSession.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/session/ClientSession.java b/sshd-core/src/main/java/org/apache/sshd/client/session/ClientSession.java index 74cb75e..d10af5b 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/session/ClientSession.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/session/ClientSession.java @@ -40,22 +40,28 @@ import org.apache.sshd.common.scp.ScpTransferEventListener; import org.apache.sshd.common.session.Session; /** - * An authenticated session to a given SSH server - * <p/> + * <P>An authenticated session to a given SSH server</P> + * + * <P> * A client session is established using the {@link org.apache.sshd.client.SshClient}. * Once the session has been created, the user has to authenticate * using either {@link #addPasswordIdentity(String)} or * {@link #addPublicKeyIdentity(java.security.KeyPair)} followed by * a call to {$link #auth()}. - * <p/> + * </P> + * + * <P> * From this session, channels can be created using the * {@link #createChannel(String)} method. Multiple channels can * be created on a given session concurrently. - * <p/> + * </P> + * + * <P> * When using the client in an interactive mode, the * {@link #waitFor(int, long)} method can be used to listen to specific * events such as the session being established, authenticated or closed. - * <p/> + * </P> + * * When a given session is no longer used, it must be closed using the * {@link #close(boolean)} method. * @@ -105,7 +111,7 @@ public interface ClientSession extends Session { * {@link #addPasswordIdentity(String)} or {@link #addPublicKeyIdentity(java.security.KeyPair)}. * * @return the authentication future - * @throws IOException + * @throws IOException if failed to generate the future * @see #addPasswordIdentity(String) * @see #addPublicKeyIdentity(java.security.KeyPair) */ @@ -114,31 +120,56 @@ public interface ClientSession extends Session { /** * Create a channel of the given type. * Same as calling <code>createChannel(type, null)</code>. + * + * @param type The channel type + * @return The created {@link ClientChannel} + * @throws IOException If failed to create the requested channel */ ClientChannel createChannel(String type) throws IOException; /** - * Create a channel of the given type and subtype. + * Create a channel of the given type and sub-type. + * + * @param type The channel type + * @param subType The channel sub-type + * @return The created {@link ClientChannel} + * @throws IOException If failed to create the requested channel */ ClientChannel createChannel(String type, String subType) throws IOException; /** * Create a channel to start a shell. + * + * @return The created {@link ChannelShell} + * @throws IOException If failed to create the requested channel */ ChannelShell createShellChannel() throws IOException; /** * Create a channel to execute a command. + * + * @param command The command to execute + * @return The created {@link ChannelExec} + * @throws IOException If failed to create the requested channel */ ChannelExec createExecChannel(String command) throws IOException; /** * Create a subsystem channel. + * + * @param subsystem The subsystem name + * @return The created {@link ChannelSubsystem} + * @throws IOException If failed to create the requested channel */ ChannelSubsystem createSubsystemChannel(String subsystem) throws IOException; /** * Create a direct tcp-ip channel which can be used to stream data to a remote port from the server. + * + * @param local The local address + * @param remote The remote address + * @return The created {@link ChannelDirectTcpip} + * @throws IOException If failed to create the requested channel */ ChannelDirectTcpip createDirectTcpipChannel(SshdSocketAddress local, SshdSocketAddress remote) throws IOException; @@ -204,18 +235,27 @@ public interface ClientSession extends Session { /** * Start forwarding the given local address on the client to the given address on the server. + * + * @param local The local address + * @param remote The remote address + * @return The bound {@link SshdSocketAddress} + * @throws IOException If failed to create the requested binding */ SshdSocketAddress startLocalPortForwarding(SshdSocketAddress local, SshdSocketAddress remote) throws IOException; /** * Stop forwarding the given local address. + * + * @param local The local address + * @throws IOException If failed to cancel the requested binding */ void stopLocalPortForwarding(SshdSocketAddress local) throws IOException; /** + * <P> * Start forwarding tcpip from the given address on the server to the * given address on the client. - * <p/> + * </P> * The remote host name is the address to bind to on the server: * <ul> * <li>"" means that connections are to be accepted on all protocol families @@ -227,38 +267,54 @@ public interface ClientSession extends Session { * <li>"127.0.0.1" and "::1" indicate listening on the loopback interfaces for * IPv4 and IPv6 respectively</li> * </ul> + * + * @param local The local address + * @param remote The remote address + * @return The bound {@link SshdSocketAddress} + * @throws IOException If failed to create the requested binding */ SshdSocketAddress startRemotePortForwarding(SshdSocketAddress remote, SshdSocketAddress local) throws IOException; /** * Stop forwarding of the given remote address. + * + * @param remote The remote address + * @throws IOException If failed to cancel the requested binding */ void stopRemotePortForwarding(SshdSocketAddress remote) throws IOException; /** * Start dynamic local port forwarding using a SOCKS proxy. * - * @param local - * @return - * @throws IOException + * @param local The local address + * @return The bound {@link SshdSocketAddress} + * @throws IOException If failed to create the requested binding */ SshdSocketAddress startDynamicPortForwarding(SshdSocketAddress local) throws IOException; /** * Stop a previously started dynamic port forwarding. * - * @param local - * @throws IOException + * @param local The local address + * @throws IOException If failed to cancel the requested binding */ void stopDynamicPortForwarding(SshdSocketAddress local) throws IOException; /** * Wait for a specific state. + * + * @param mask The request mask + * @param timeout Wait time in milliseconds - non-positive means forever + * @return The actual state that was detected either due to the mask + * yielding non-zero state or due to timeout (in which case the {@link #TIMEOUT} + * bit is set) */ int waitFor(int mask, long timeout); /** * Access to the metadata. + * + * @return The metadata {@link Map} */ Map<Object, Object> getMetadataMap(); @@ -269,12 +325,14 @@ public interface ClientSession extends Session { ClientFactoryManager getFactoryManager(); /** - * Switch to a none cipher for performance. - * <p/> + * <P>Switch to a none cipher for performance.</P> + * + * <P> * This should be done after the authentication phase has been performed. * After such a switch, interactive channels are not allowed anymore. * Both client and server must have been configured to support the none cipher. * If that's not the case, the returned future will be set with an exception. + * </P> * * @return an {@link SshFuture} that can be used to wait for the exchange * to be finished http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/DefaultSftpClient.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/DefaultSftpClient.java b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/DefaultSftpClient.java index feb156a..feeea1b 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/DefaultSftpClient.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/DefaultSftpClient.java @@ -130,6 +130,11 @@ public class DefaultSftpClient extends AbstractSftpClient { /** * Receive binary data + * @param buf The buffer for the incoming data + * @param start Offset in buffer to place the data + * @param len Available space in buffer for the data + * @return Actual size of received data + * @throws IOException If failed to receive incoming data */ protected int data(byte[] buf, int start, int len) throws IOException { Buffer incoming = new ByteArrayBuffer(buf, start, len); @@ -157,6 +162,11 @@ public class DefaultSftpClient extends AbstractSftpClient { /** * Read SFTP packets from buffer + * + * @param incoming The received {@link Buffer} + * @return {@code true} if data from incoming buffer was processed + * @throws IOException if failed to process the buffer + * @see #process(Buffer) */ protected boolean receive(Buffer incoming) throws IOException { int rpos = incoming.rpos(); @@ -182,6 +192,9 @@ public class DefaultSftpClient extends AbstractSftpClient { /** * Process an SFTP packet + * + * @param incoming The received {@link Buffer} + * @throws IOException if failed to process the buffer */ protected void process(Buffer incoming) throws IOException { Buffer buffer = new ByteArrayBuffer(incoming.available()); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/SftpClient.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/SftpClient.java b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/SftpClient.java index 0c7032c..7276dd8 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/SftpClient.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/SftpClient.java @@ -436,6 +436,7 @@ public interface SftpClient extends SubsystemClient { OutputStream write(String path, int bufferSize, Collection<OpenMode> mode) throws IOException; /** + * @param <E> The generic extension type * @param extensionType The extension type * @return The extension instance - <B>Note:</B> it is up to the caller * to invoke {@link SftpClientExtension#isSupported()} - {@code null} if http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/CopyFileExtension.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/CopyFileExtension.java b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/CopyFileExtension.java index 33b7225..fa5d364 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/CopyFileExtension.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/CopyFileExtension.java @@ -23,7 +23,7 @@ import java.io.IOException; /** * @author <a href="mailto:[email protected]";>Apache MINA SSHD Project</a> - * @see <A HREF="https://tools.ietf.org/html/draft-ietf-secsh-filexfer-extensions-00#section-6";>copy-file</A> extension + * @see <A HREF="https://tools.ietf.org/html/draft-ietf-secsh-filexfer-extensions-00#section-6";>copy-file extension</A> */ public interface CopyFileExtension extends SftpClientExtension { /** http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/impl/AbstractSftpClientExtension.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/impl/AbstractSftpClientExtension.java b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/impl/AbstractSftpClientExtension.java index e9f2e0e..e0cf07d 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/impl/AbstractSftpClientExtension.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/impl/AbstractSftpClientExtension.java @@ -106,7 +106,7 @@ public abstract class AbstractSftpClientExtension extends AbstractLoggingBean im /** * @param buffer The {@link Buffer} - * @param target A target path {@link String} or {@link Handle} or {@code byte[]) + * @param target A target path {@link String} or {@link Handle} or {@code byte[]} * to be encoded in the buffer * @return The updated buffer * @throws UnsupportedOperationException If target is not one of the above @@ -127,7 +127,7 @@ public abstract class AbstractSftpClientExtension extends AbstractLoggingBean im } /** - * @param target A target path {@link String} or {@link Handle} or {@code byte[]) + * @param target A target path {@link String} or {@link Handle} or {@code byte[]} * to be encoded in the buffer * @return A {@link Buffer} with the extension name set * @see #getCommandBuffer(Object, int) @@ -137,7 +137,7 @@ public abstract class AbstractSftpClientExtension extends AbstractLoggingBean im } /** - * @param target A target path {@link String} or {@link Handle} or {@code byte[]) + * @param target A target path {@link String} or {@link Handle} or {@code byte[]} * to be encoded in the buffer * @param extraSize Extra size - beyond the path/handle to be allocated * @return A {@link Buffer} with the extension name set @@ -198,7 +198,7 @@ public abstract class AbstractSftpClientExtension extends AbstractLoggingBean im throw new SshException("Unexpected SFTP packet received: type=" + type + ", id=" + id + ", length=" + length); } } - + protected void throwStatusException(int id, int substatus, String msg, String lang) throws IOException { throw new SftpException(substatus, msg); } http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/openssh/OpenSSHFsyncExtension.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/openssh/OpenSSHFsyncExtension.java b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/openssh/OpenSSHFsyncExtension.java index 0c11e5b..7c67ec9 100644 --- a/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/openssh/OpenSSHFsyncExtension.java +++ b/sshd-core/src/main/java/org/apache/sshd/client/subsystem/sftp/extensions/openssh/OpenSSHFsyncExtension.java @@ -28,7 +28,7 @@ import org.apache.sshd.client.subsystem.sftp.extensions.SftpClientExtension; * Implements the "[email protected]" extension * * @author <a href="mailto:[email protected]";>Apache MINA SSHD Project</a> - * @see <A HREF="https://github.com/openssh/openssh-portable/blob/master/PROTOCOL";>OpenSSH</A> section 10 + * @see <A HREF="https://github.com/openssh/openssh-portable/blob/master/PROTOCOL";>OpenSSH - section 10</A> */ public interface OpenSSHFsyncExtension extends SftpClientExtension { void fsync(Handle fileHandle) throws IOException; http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/BaseBuilder.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/BaseBuilder.java b/sshd-core/src/main/java/org/apache/sshd/common/BaseBuilder.java index f4629d8..69de1ab 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/BaseBuilder.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/BaseBuilder.java @@ -66,8 +66,7 @@ public class BaseBuilder<T extends AbstractFactoryManager, S extends BaseBuilder /** * The default {@link BuiltinCiphers} setup in order of preference - * as specified by <A HREF="https://www.freebsd.org/cgi/man.cgi?query=ssh_config&sektion=5";> - * ssh_config(5)</A> + * as specified by <A HREF="https://www.freebsd.org/cgi/man.cgi?query=ssh_config&sektion=5";>ssh_config(5)</A> */ public static final List<BuiltinCiphers> DEFAULT_CIPHERS_PREFERENCE = Collections.unmodifiableList(Arrays.asList( @@ -120,7 +119,7 @@ public class BaseBuilder<T extends AbstractFactoryManager, S extends BaseBuilder /** * Preferred {@link BuiltinSignatures} according to - * <A HREF="https://www.freebsd.org/cgi/man.cgi?query=ssh_config&sektion=5>sshd_config(5)</A> + * <A HREF="https://www.freebsd.org/cgi/man.cgi?query=ssh_config&sektion=5";>sshd_config(5)</A> * {@code HostKeyAlgorithms} recommendation */ public static final List<BuiltinSignatures> DEFAULT_SIGNATURE_PREFERENCE = http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/FactoryManager.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/FactoryManager.java b/sshd-core/src/main/java/org/apache/sshd/common/FactoryManager.java index b9ed1e6..87fc846 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/FactoryManager.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/FactoryManager.java @@ -164,25 +164,25 @@ public interface FactoryManager { * client and is not supposed to be changed at runtime (changes are not * bound to have any effect on a running client or server), though it may * affect the creation of sessions later as these values are usually not - * cached.</P></BR> - * <B>Note:</B> the <U>type</U> of the mapped property should match the + * cached.</P> + * + * <P><B>Note:</B> the <U>type</U> of the mapped property should match the * expected configuration value type - {@code Long, Integer, Boolean, - * String, etc...). If it doesn't, the {@code toString()} result of the + * String}, etc.... If it doesn't, the {@code toString()} result of the * mapped value is used to convert it to the required type. E.g., if * the mapped value is the <U>string</U> "1234" and the expected * value is a {@code long} then it will be parsed into one. Also, if * the mapped value is an {@code Integer} but a {@code long} is expected, - * then it will be converted into one. + * then it will be converted into one.</P> * * @return a valid <code>Map</code> containing configuration values, never {@code null} */ Map<String, Object> getProperties(); /** - * An upper case string identifying the version of the - * software used on client or server side. - * This version includes the name of the software and usually - * looks like: <code>SSHD-1.0</code> + * An upper case string identifying the version of the software used on + * client or server side. This version includes the name of the software + * and usually looks like this: <code>SSHD-1.0</code> * * @return the version of the software */ http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/NamedResource.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/NamedResource.java b/sshd-core/src/main/java/org/apache/sshd/common/NamedResource.java index c1bf654..a7d192f 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/NamedResource.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/NamedResource.java @@ -103,6 +103,7 @@ public interface NamedResource { /** * Remove the resource identified by the name from the list. * + * @param <R> The generic resource type * @param name Name of the resource - ignored if {@code null}/empty * @param c The {@link Comparator} to decide whether the {@link NamedResource#getName()} * matches the <tt>name</tt> parameter @@ -119,6 +120,7 @@ public interface NamedResource { } /** + * @param <R> The generic resource type * @param name Name of the resource - ignored if {@code null}/empty * @param c The {@link Comparator} to decide whether the {@link NamedResource#getName()} * matches the <tt>name</tt> parameter http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/ServiceFactory.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/ServiceFactory.java b/sshd-core/src/main/java/org/apache/sshd/common/ServiceFactory.java index 6df16cc..b350f55 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/ServiceFactory.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/ServiceFactory.java @@ -41,6 +41,7 @@ public interface ServiceFactory extends NamedResource { * * @param factories list of available factories * @param name the factory name to use + * @param session the referenced {@link Session} * @return a newly created object or {@code null} if the factory is not in the list * @throws IOException if session creation failed * @see ServiceFactory#create(Session) http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/SshdSocketAddress.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/SshdSocketAddress.java b/sshd-core/src/main/java/org/apache/sshd/common/SshdSocketAddress.java index e4aab99..07b4a04 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/SshdSocketAddress.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/SshdSocketAddress.java @@ -27,7 +27,7 @@ import org.apache.sshd.common.util.ValidateUtils; /** * <P>A simple socket address holding the host name and port number. The reason - * it does not extend {@link InetSocketAddress} is twofold:</P></BR> + * it does not extend {@link InetSocketAddress} is twofold:</P> * <OL> * <LI><P> * The {@link InetSocketAddress} performs a DNS resolution on the @@ -35,7 +35,7 @@ import org.apache.sshd.common.util.ValidateUtils; * create a connection using this address (thus the {@link #toInetSocketAddress()} * call which executes this query * </P></LI> - * <p/> + * * <LI><P> * If empty host name is provided we replace it with the <I>any</I> * address of 0.0.0.0 http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/channel/Channel.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/channel/Channel.java b/sshd-core/src/main/java/org/apache/sshd/common/channel/Channel.java index 667a64f..27721f4 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/channel/Channel.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/channel/Channel.java @@ -34,8 +34,14 @@ import org.apache.sshd.common.util.buffer.Buffer; */ public interface Channel extends Closeable { + /** + * @return Local channel identifier + */ int getId(); + /** + * @return Remote channel identifier + */ int getRecipient(); Window getLocalWindow(); @@ -65,18 +71,42 @@ public interface Channel extends Closeable { /** * For a server channel, this method will actually open the channel + * + * @param recipient Recipient identifier + * @param rwSize Read/Write window size + * @param packetSize Preferred maximum packet size + * @param buffer Incoming {@link Buffer} that triggered the call. + * <B>Note:</B> the buffer's read position is exactly + * <U>after</U> the information that read to this call + * was decoded + * @return An {@link OpenFuture} for the channel open request */ - OpenFuture open(int recipient, int rwsize, int rmpsize, Buffer buffer); + OpenFuture open(int recipient, int rwSize, int packetSize, Buffer buffer); /** - * For a client channel, this method will be called internally by the session when the confirmation - * has been received. + * For a client channel, this method will be called internally by the + * session when the confirmation has been received. + * + * @param recipient Recipient identifier + * @param rwSize Read/Write window size + * @param packetSize Preferred maximum packet size + * @param buffer Incoming {@link Buffer} that triggered the call. + * <B>Note:</B> the buffer's read position is exactly + * <U>after</U> the information that read to this call + * was decoded + * @throws IOException If failed to handle the success */ - void handleOpenSuccess(int recipient, int rwsize, int rmpsize, Buffer buffer) throws IOException; + void handleOpenSuccess(int recipient, int rwSize, int packetSize, Buffer buffer) throws IOException; /** - * For a client channel, this method will be called internally by the session when - * the server has rejected this channel opening. + * For a client channel, this method will be called internally by the + * session when the server has rejected this channel opening. + * + * @param buffer Incoming {@link Buffer} that triggered the call. + * <B>Note:</B> the buffer's read position is exactly + * <U>after</U> the information that read to this call + * was decoded + * @throws IOException If failed to handle the success */ void handleOpenFailure(Buffer buffer) throws IOException; http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncInputStream.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncInputStream.java b/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncInputStream.java index b950afc..06f9a65 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncInputStream.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncInputStream.java @@ -58,7 +58,7 @@ public class ChannelAsyncInputStream extends CloseableUtils.AbstractCloseable im } else { synchronized (buffer) { if (pending != null) { - throw new ReadPendingException(); + throw new ReadPendingException("Previous pending read not handled"); } pending = future; } http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncOutputStream.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncOutputStream.java b/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncOutputStream.java index 85edc24..6a705f8 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncOutputStream.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/channel/ChannelAsyncOutputStream.java @@ -52,7 +52,7 @@ public class ChannelAsyncOutputStream extends CloseableUtils.AbstractCloseable i future.setValue(new IOException("Closed")); } else { if (!pendingWrite.compareAndSet(null, future)) { - throw new WritePendingException(); + throw new WritePendingException("No write pending future"); } doWriteIfPossible(false); } http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/channel/SttySupport.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/channel/SttySupport.java b/sshd-core/src/main/java/org/apache/sshd/common/channel/SttySupport.java index 7bdf320..7cf2650 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/channel/SttySupport.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/channel/SttySupport.java @@ -21,9 +21,12 @@ package org.apache.sshd.common.channel; import java.io.ByteArrayOutputStream; import java.io.IOException; import java.io.InputStream; +import java.io.OutputStream; import java.util.Map; import java.util.StringTokenizer; import java.util.TreeMap; +import java.util.concurrent.atomic.AtomicLong; +import java.util.concurrent.atomic.AtomicReference; /** * Support for stty command on unix @@ -31,10 +34,16 @@ import java.util.TreeMap; * @author <a href="mailto:[email protected]";>Apache MINA SSHD Project</a> */ public final class SttySupport { + public static final int DEFAULT_TERMINAL_WIDTH = 80; + public static final int DEFAULT_TERMINAL_HEIGHT = 24; - private static String sttyCommand = System.getProperty("sshd.sttyCommand", "stty"); - private static String ttyProps; - private static long ttyPropsLastFetched; + public static final String SSHD_STTY_COMMAND_PROP = "sshd.sttyCommand"; + public static final String DEFAULT_SSHD_STTY_COMMAND = "stty"; + + private static final AtomicReference<String> STTY_COMMAND_HOLDER = + new AtomicReference<String>(System.getProperty(SSHD_STTY_COMMAND_PROP, DEFAULT_SSHD_STTY_COMMAND)); + private static final AtomicReference<String> TTY_PROPS_HOLDER = new AtomicReference<String>(null); + private static final AtomicLong TTY_PROPS_LAST_FETCHED_HOLDER = new AtomicLong(0L); private SttySupport() { throw new UnsupportedOperationException("No instance allowed"); @@ -125,51 +134,53 @@ public final class SttySupport { } /** - * Returns the value of "stty size" width param. - * <p/> + * <P>Returns the value of "stty size" width param.</P> + * + * <P> * <strong>Note</strong>: this method caches the value from the * first time it is called in order to increase speed, which means * that changing to size of the terminal will not be reflected * in the console. + * </P> + * + * @return The terminal width */ public static int getTerminalWidth() { - int val = -1; - try { - val = getTerminalProperty("columns"); - } catch (Exception e) { - // ignored - } + int val = getTerminalProperty("columns"); + if (val == -1) { + val = DEFAULT_TERMINAL_WIDTH; + } - if (val == -1) { - val = 80; + return val; + } catch (Exception e) { + return DEFAULT_TERMINAL_WIDTH; // debug breakpoint } - - return val; } /** - * Returns the value of "stty size" height param. - * <p/> + * <P>Returns the value of "stty size" height param.</P> + * + * <P> * <strong>Note</strong>: this method caches the value from the * first time it is called in order to increase speed, which means * that changing to size of the terminal will not be reflected * in the console. + * </P> + * + * @return The terminal height */ public static int getTerminalHeight() { - int val = -1; - try { - val = getTerminalProperty("rows"); - } catch (Exception e) { - // ignored - } + int val = getTerminalProperty("rows"); + if (val == -1) { + val = DEFAULT_TERMINAL_HEIGHT; + } - if (val == -1) { - val = 24; + return val; + } catch (Exception e) { + return DEFAULT_TERMINAL_HEIGHT; // debug breakpoint } - - return val; } private static int getTerminalProperty(String prop) @@ -197,17 +208,25 @@ public final class SttySupport { public static String getTtyProps() throws IOException, InterruptedException { // tty properties are cached so we don't have to worry too much about getting term widht/height - if (ttyProps == null || System.currentTimeMillis() - ttyPropsLastFetched > 1000) { - ttyProps = stty("-a"); - ttyPropsLastFetched = System.currentTimeMillis(); + long now = System.currentTimeMillis(); + long lastFetched = TTY_PROPS_LAST_FETCHED_HOLDER.get(); + if ((TTY_PROPS_HOLDER.get() == null) || ((now - lastFetched) > 1000L)) { + TTY_PROPS_HOLDER.set(stty("-a")); + TTY_PROPS_LAST_FETCHED_HOLDER.set(System.currentTimeMillis()); } - return ttyProps; - } + return TTY_PROPS_HOLDER.get(); + } /** * Execute the stty command with the specified arguments * against the current active terminal. + * + * @param args The command arguments + * @return The execution result + * @throws IOException If failed to execute the command + * @throws InterruptedException If interrupted while awaiting command execution + * @see #exec(String) */ public static String stty(final String args) throws IOException, InterruptedException { @@ -217,6 +236,12 @@ public final class SttySupport { /** * Execute the specified command and return the output * (both stdout and stderr). + * + * @param cmd The command to execute + * @return The execution result + * @throws IOException If failed to execute the command + * @throws InterruptedException If interrupted while awaiting command execution + * @see #exec(String[]) */ public static String exec(final String cmd) throws IOException, InterruptedException { @@ -230,48 +255,52 @@ public final class SttySupport { /** * Execute the specified command and return the output * (both stdout and stderr). + * + * @param cmd The command components + * @return The execution result + * @throws IOException If failed to execute the command + * @throws InterruptedException If interrupted while awaiting command execution */ - private static String exec(final String[] cmd) + private static String exec(final String ... cmd) throws IOException, InterruptedException { - ByteArrayOutputStream bout = new ByteArrayOutputStream(); - - Process p = Runtime.getRuntime().exec(cmd); - int c; - InputStream in; - - in = p.getInputStream(); - - while ((c = in.read()) != -1) { - bout.write(c); + try (ByteArrayOutputStream bout = new ByteArrayOutputStream()) { + Process p = Runtime.getRuntime().exec(cmd); + copyStream(p.getInputStream(), bout); + copyStream(p.getErrorStream(), bout); + p.waitFor(); + + String result = new String(bout.toByteArray()); + return result; } + } - in = p.getErrorStream(); + private static int copyStream(InputStream in, OutputStream bout) throws IOException { + int count = 0; + while (true) { + int c = in.read(); + if (c == (-1)) { + return count; + } - while ((c = in.read()) != -1) { bout.write(c); + count++; } - - p.waitFor(); - - String result = new String(bout.toByteArray()); - - return result; } /** - * The command to use to set the terminal options. Defaults - * to "stty", or the value of the system property "jline.sttyCommand". + * @return The command to use to set the terminal options. + * @see #setSttyCommand(String) */ - public static void setSttyCommand(String cmd) { - sttyCommand = cmd; + public static String getSttyCommand() { + return STTY_COMMAND_HOLDER.get(); } /** - * The command to use to set the terminal options. Defaults - * to "stty", or the value of the system property "jline.sttyCommand". + * @param cmd The command to use to set the terminal options. Defaults + * to {@link #DEFAULT_SSHD_STTY_COMMAND}, or the value of the + * {@link #SSHD_STTY_COMMAND_PROP} system property if not set via this method */ - public static String getSttyCommand() { - return sttyCommand; + public static void setSttyCommand(String cmd) { + STTY_COMMAND_HOLDER.set(cmd); } - } http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/config/SshConfigFileReader.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/config/SshConfigFileReader.java b/sshd-core/src/main/java/org/apache/sshd/common/config/SshConfigFileReader.java index ae3637d..73cde24 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/config/SshConfigFileReader.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/config/SshConfigFileReader.java @@ -398,7 +398,7 @@ public final class SshConfigFileReader { * @param props The {@link Properties} - ignored if {@code null}/empty * @return A {@link BuiltinSignatures.ParseResult} of all the {@link NamedFactory} * whose name appears in the string and represent a built-in signature. Any - * unknown name is <U>ignored</I>. The order of the returned result is the + * unknown name is <U>ignored</U>. The order of the returned result is the * same as the original order - bar the unknown signatures. <B>Note:</B> it * is up to caller to ensure that the list does not contain duplicates * @see #HOST_KEY_ALGORITHMS_CONFIG_PROP @@ -445,7 +445,7 @@ public final class SshConfigFileReader { /** * <P>Configures an {@link AbstractFactoryManager} with the values read from - * some configuration. Currently it configures:</P></BR> + * some configuration. Currently it configures:</P> * <UL> * <LI>The {@link Cipher}s - via the {@link #CIPHERS_CONFIG_PROP}</LI> * <LI>The {@link Mac}s - via the {@link #MACS_CONFIG_PROP}</LI> @@ -453,6 +453,7 @@ public final class SshConfigFileReader { * <LI>The {@link Compression} - via the {@link #COMPRESSION_PROP}</LI> * </UL> * + * @param <M> The generic factory manager * @param manager The {@link AbstractFactoryManager} to configure * @param props The {@link Properties} to use for configuration - <B>Note:</B> * if any known configuration value has a default and does not appear in the @@ -528,6 +529,7 @@ public final class SshConfigFileReader { } /** + * @param <M> The generic factory manager * @param manager The {@link AbstractFactoryManager} to set up (may not be {@code null}) * @param props The (non-{@code null}) {@link Properties} containing the configuration * @param lenient If {@code true} then any unknown/unsupported configuration @@ -565,6 +567,7 @@ public final class SshConfigFileReader { /** * Configure the factory manager using one of the known {@link CompressionConfigValue}s. * + * @param <M> The generic factory manager * @param manager The {@link AbstractFactoryManager} to configure * @param props The configuration {@link Properties} * @param lenient If {@code true} and an unknown value is provided then http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/config/keys/KeyUtils.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/config/keys/KeyUtils.java b/sshd-core/src/main/java/org/apache/sshd/common/config/keys/KeyUtils.java index 97013cf..f1934d2 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/config/keys/KeyUtils.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/config/keys/KeyUtils.java @@ -108,21 +108,21 @@ public final class KeyUtils { } /** - * <P>Checks if a path has strict permissions</P></BR> + * <P>Checks if a path has strict permissions</P> * <UL> - * <LI> + * <LI><P> * The path may not have {@link PosixFilePermission#OTHERS_EXECUTE} * permission - * </LI> - * <p/> - * <LI> + * </P></LI> + * + * <LI><P> * (For {@code Unix}) The path may not have group or others permissions - * </LI> - * <p/> - * <LI> + * </P></LI> + * + * <LI><P> * (For {@code Unix}) If the path is a file, then its folder may not have * group or others permissions - * </LI> + * </P></LI> * </UL> * * @param path The {@link Path} to be checked - ignored if {@code null} http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/config/keys/PublicKeyEntry.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/config/keys/PublicKeyEntry.java b/sshd-core/src/main/java/org/apache/sshd/common/config/keys/PublicKeyEntry.java index 60c91c6..d099e33 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/config/keys/PublicKeyEntry.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/config/keys/PublicKeyEntry.java @@ -37,10 +37,11 @@ import org.apache.sshd.common.util.buffer.BufferUtils; /** * <P>Represents a {@link PublicKey} whose data is formatted according to - * the <A HREF="http://en.wikibooks.org/wiki/OpenSSH";>OpenSSH</A> format:</P></BR> - * <CODE><PRE> - * <key-type> <base64-encoded-public-key-data> - * </CODE></PRE> + * the <A HREF="http://en.wikibooks.org/wiki/OpenSSH";>OpenSSH</A> format:</P> + * + * <PRE> + * <key-type> <base64-encoded-public-key-data> + * </PRE> * * @author <a href="mailto:[email protected]";>Apache MINA SSHD Project</a> */ @@ -177,6 +178,7 @@ public class PublicKeyEntry implements Serializable { } /** + * @param <E> The generic entry type * @param entry The {@link PublicKeyEntry} whose contents are to be * updated - ignored if {@code null} * @param data Assumed to contain at least {@code key-type base64-data} (anything @@ -214,7 +216,8 @@ public class PublicKeyEntry implements Serializable { /** * @param key The {@link PublicKey} * @return The {@code OpenSSH} encoded data - * @throws IllegalArgumentException + * @throws IllegalArgumentException If failed to encode + * @see #appendPublicKeyEntry(Appendable, PublicKey) */ public static String toString(PublicKey key) throws IllegalArgumentException { try { @@ -227,6 +230,7 @@ public class PublicKeyEntry implements Serializable { /** * Encodes a public key data the same way as the {@link #parsePublicKeyEntry(String)} expects it * + * @param <A> The generic appendable class * @param sb The {@link Appendable} instance to encode the data into * @param key The {@link PublicKey} * @return The updated appendable instance http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/file/util/ImmutableList.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/file/util/ImmutableList.java b/sshd-core/src/main/java/org/apache/sshd/common/file/util/ImmutableList.java index 123bbf2..f8124da 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/file/util/ImmutableList.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/file/util/ImmutableList.java @@ -23,7 +23,7 @@ import java.util.AbstractList; /** * Simple immutable array list * - * @param <T> + * @param <T> The element type */ public class ImmutableList<T> extends AbstractList<T> { http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/forward/DefaultTcpipForwarderFactory.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/forward/DefaultTcpipForwarderFactory.java b/sshd-core/src/main/java/org/apache/sshd/common/forward/DefaultTcpipForwarderFactory.java index d9837ec..8147f33 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/forward/DefaultTcpipForwarderFactory.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/forward/DefaultTcpipForwarderFactory.java @@ -24,7 +24,6 @@ import org.apache.sshd.common.session.ConnectionService; * The default {@link TcpipForwarderFactory} implementation. * * @author <a href="mailto:[email protected]";>Apache MINA SSHD Project</a> - * @see {@link DefaultTcpipForwarder} */ public class DefaultTcpipForwarderFactory implements TcpipForwarderFactory { public static final DefaultTcpipForwarderFactory INSTANCE = new DefaultTcpipForwarderFactory(); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/forward/TcpipForwarder.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/forward/TcpipForwarder.java b/sshd-core/src/main/java/org/apache/sshd/common/forward/TcpipForwarder.java index a278ab0..c278977 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/forward/TcpipForwarder.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/forward/TcpipForwarder.java @@ -31,6 +31,7 @@ public interface TcpipForwarder extends Closeable { * * @param remote The remote address * @param local The local address + * @return The bound {@link SshdSocketAddress} * @throws IOException If failed to handle request */ SshdSocketAddress startLocalPortForwarding(SshdSocketAddress local, SshdSocketAddress remote) throws IOException; @@ -44,23 +45,42 @@ public interface TcpipForwarder extends Closeable { void stopLocalPortForwarding(SshdSocketAddress local) throws IOException; /** - * Start forwarding tcpip from the given remote address to the + * <P> + * Start forwarding tcp/ip from the given remote address to the * given local address. - * <p/> + * </P> + * + * <P> * The remote host name is the address to bind to on the server: + * </P> * <ul> - * <li>"" means that connections are to be accepted on all protocol families - * supported by the SSH implementation</li> - * <li>"0.0.0.0" means to listen on all IPv4 addresses</li> - * <li>"::" means to listen on all IPv6 addresses</li> - * <li>"localhost" means to listen on all protocol families supported by the SSH - * implementation on loopback addresses only, [RFC3330] and RFC3513]</li> - * <li>"127.0.0.1" and "::1" indicate listening on the loopback interfaces for - * IPv4 and IPv6 respectively</li> + * <li> + * "" means that connections are to be accepted on all protocol families + * supported by the SSH implementation + * </li> + * + * <li> + * "0.0.0.0" means to listen on all IPv4 addresses + * </li> + * + * <li> + * "::" means to listen on all IPv6 addresses + * </li> + * + * <li> + * "localhost" means to listen on all protocol families supported by the SSH + * implementation on loopback addresses only, [RFC3330] and RFC3513] + * </li> + * + * <li> + * "127.0.0.1" and "::1" indicate listening on the loopback interfaces for + * IPv4 and IPv6 respectively + * </li> * </ul> * * @param remote The remote address * @param local The local address + * @return The bound {@link SshdSocketAddress} * @throws IOException If failed to handle request */ SshdSocketAddress startRemotePortForwarding(SshdSocketAddress remote, SshdSocketAddress local) throws IOException; http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/future/CloseFuture.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/future/CloseFuture.java b/sshd-core/src/main/java/org/apache/sshd/common/future/CloseFuture.java index 64fc756..5efecc2 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/future/CloseFuture.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/future/CloseFuture.java @@ -26,7 +26,7 @@ package org.apache.sshd.common.future; public interface CloseFuture extends SshFuture<CloseFuture> { /** - * Returns <tt>true</tt> if the close request is finished and the target is closed. + * @return <tt>true</tt> if the close request is finished and the target is closed. */ boolean isClosed(); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultCloseFuture.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultCloseFuture.java b/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultCloseFuture.java index 3f0da11..368ff8d 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultCloseFuture.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultCloseFuture.java @@ -27,6 +27,9 @@ public class DefaultCloseFuture extends DefaultSshFuture<CloseFuture> implements /** * Create a new instance + * + * @param lock A synchronization object for locking access - if {@code null} + * then synchronization occurs on {@code this} instance */ public DefaultCloseFuture(Object lock) { super(lock); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultSshFuture.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultSshFuture.java b/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultSshFuture.java index 973f226..e6bd532 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultSshFuture.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/future/DefaultSshFuture.java @@ -53,6 +53,9 @@ public class DefaultSshFuture<T extends SshFuture> extends AbstractLoggingBean i /** * Creates a new instance. + * + * @param lock A synchronization object for locking access - if {@code null} + * then synchronization occurs on {@code this} instance */ public DefaultSshFuture(Object lock) { this.lock = lock != null ? lock : this; @@ -104,32 +107,33 @@ public class DefaultSshFuture<T extends SshFuture> extends AbstractLoggingBean i /** * <P>Waits (interruptible) for the specified timeout (msec.) and then checks - * the result:</P><BR/> + * the result:</P> * <UL> - * <LI> + * <LI><P> * If result is {@code null} then timeout is assumed to have expired - throw * an appropriate {@link IOException} - * </LI> - * <p/> - * <LI> + * </P></LI> + * + * <LI><P> * If the result is of the expected type, then cast and return it - * </LI> - * <p/> - * <LI> + * </P></LI> + * + * <LI><P> * If the result is an {@link IOException} then re-throw it - * </LI> - * <p/> - * <LI> + * </P></LI> + * + * <LI><P> * If the result is a {@link Throwable} then throw an {@link IOException} * whose cause is the original exception - * </LI> - * <p/> - * <LI> + * </P></LI> + * + * <LI><P> * Otherwise (should never happen), throw a {@link StreamCorruptedException} * with the name of the result type - * </LI> + * </P></LI> * </UL> * + * @param <R> The generic result type * @param expectedType The expected result type * @param timeout The timeout (millis) to wait for a result * @return The (never {@code null}) result @@ -205,6 +209,8 @@ public class DefaultSshFuture<T extends SshFuture> extends AbstractLoggingBean i /** * Sets the result of the asynchronous operation, and mark it as finished. + * + * @param newValue The operation result */ public void setValue(Object newValue) { synchronized (lock) { @@ -221,7 +227,7 @@ public class DefaultSshFuture<T extends SshFuture> extends AbstractLoggingBean i } /** - * Returns the result of the asynchronous operation. + * @return The result of the asynchronous operation. */ protected Object getValue() { synchronized (lock) { http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/future/SshFuture.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/future/SshFuture.java b/sshd-core/src/main/java/org/apache/sshd/common/future/SshFuture.java index 8963aae..bc9b9ce 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/future/SshFuture.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/future/SshFuture.java @@ -44,6 +44,8 @@ public interface SshFuture<T extends SshFuture> { /** * Wait for the asynchronous operation to complete with the specified timeout. * + * @param timeout The number of time units to wait + * @param unit The {@link TimeUnit} for waiting * @return {@code true} if the operation is completed. * @throws IOException if failed - specifically {@link java.io.InterruptedIOException} * if waiting was interrupted @@ -53,6 +55,7 @@ public interface SshFuture<T extends SshFuture> { /** * Wait for the asynchronous operation to complete with the specified timeout. * + * @param timeoutMillis Wait time in milliseconds * @return {@code true} if the operation is completed. * @throws IOException if failed - specifically {@link java.io.InterruptedIOException} * if waiting was interrupted @@ -64,7 +67,7 @@ public interface SshFuture<T extends SshFuture> { * The attached listeners will be notified when the operation is * completed. * - * @return the current IoFuture + * @return the current future */ T awaitUninterruptibly(); @@ -72,6 +75,8 @@ public interface SshFuture<T extends SshFuture> { * Wait for the asynchronous operation to complete with the specified timeout * uninterruptibly. * + * @param timeout The number of time units to wait + * @param unit The {@link TimeUnit} for waiting * @return {@code true} if the operation is completed. */ boolean awaitUninterruptibly(long timeout, TimeUnit unit); @@ -80,12 +85,13 @@ public interface SshFuture<T extends SshFuture> { * Wait for the asynchronous operation to complete with the specified timeout * uninterruptibly. * + * @param timeoutMillis Wait time in milliseconds * @return {@code true} if the operation is finished. */ boolean awaitUninterruptibly(long timeoutMillis); /** - * Returns if the asynchronous operation is completed. + * @return {@code true} if the asynchronous operation is completed. */ boolean isDone(); @@ -93,12 +99,18 @@ public interface SshFuture<T extends SshFuture> { * Adds an event <tt>listener</tt> which is notified when * this future is completed. If the listener is added * after the completion, the listener is directly notified. + * + * @param listener The {@link SshFutureListener} instance to add + * @return The future instance */ T addListener(SshFutureListener<T> listener); /** * Removes an existing event <tt>listener</tt> so it won't be notified when * the future is completed. + * + * @param listener The {@link SshFutureListener} instance to remove + * @return The future instance */ T removeListener(SshFutureListener<T> listener); } http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/io/IoConnectFuture.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/io/IoConnectFuture.java b/sshd-core/src/main/java/org/apache/sshd/common/io/IoConnectFuture.java index 50b2053..aefdd33 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/io/IoConnectFuture.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/io/IoConnectFuture.java @@ -22,6 +22,11 @@ import org.apache.sshd.common.future.SshFuture; public interface IoConnectFuture extends SshFuture<IoConnectFuture> { + /** + * @return The current {@link IoSession} - may be {@code null} + * if connect operation not finished yet or attempt has failed + * @see #getException() + */ IoSession getSession(); /** @@ -29,16 +34,17 @@ public interface IoConnectFuture extends SshFuture<IoConnectFuture> { * * @return <tt>null</tt> if the connect operation is not finished yet, * or if the connection attempt is successful. + * @see #getSession() */ Throwable getException(); /** - * Returns <tt>true</tt> if the connect operation is finished successfully. + * @return <tt>true</tt> if the connect operation is finished successfully. */ boolean isConnected(); /** - * Returns {@code true} if the connect operation has been canceled by + * @return {@code true} if the connect operation has been canceled by * {@link #cancel()} method. */ boolean isCanceled(); @@ -47,6 +53,8 @@ public interface IoConnectFuture extends SshFuture<IoConnectFuture> { * Sets the newly connected session and notifies all threads waiting for * this future. This method is invoked by SSHD internally. Please do not * call this method directly. + * + * @param session The connected {@link IoSession} */ void setSession(IoSession session); @@ -54,6 +62,8 @@ public interface IoConnectFuture extends SshFuture<IoConnectFuture> { * Sets the exception caught due to connection failure and notifies all * threads waiting for this future. This method is invoked by SSHD * internally. Please do not call this method directly. + * + * @param exception The caught {@link Throwable} */ void setException(Throwable exception); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/io/IoInputStream.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/io/IoInputStream.java b/sshd-core/src/main/java/org/apache/sshd/common/io/IoInputStream.java index d61419c..0fdd011 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/io/IoInputStream.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/io/IoInputStream.java @@ -25,6 +25,9 @@ public interface IoInputStream extends Closeable { /** * NOTE: the buffer must not be touched until the returned read future is completed. + * + * @param buffer the {@link Buffer} to use + * @return The {@link IoReadFuture} for the operation */ IoReadFuture read(Buffer buffer); http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/61e637c4/sshd-core/src/main/java/org/apache/sshd/common/io/IoOutputStream.java ---------------------------------------------------------------------- diff --git a/sshd-core/src/main/java/org/apache/sshd/common/io/IoOutputStream.java b/sshd-core/src/main/java/org/apache/sshd/common/io/IoOutputStream.java index 104d5fb..0bf1c33 100644 --- a/sshd-core/src/main/java/org/apache/sshd/common/io/IoOutputStream.java +++ b/sshd-core/src/main/java/org/apache/sshd/common/io/IoOutputStream.java @@ -24,7 +24,10 @@ import org.apache.sshd.common.util.buffer.Buffer; public interface IoOutputStream extends Closeable { /** - * NOTE: the buffer must not be touched until the returned write future is completed. + * <B>NOTE:</B> the buffer must not be touched until the returned write future is completed. + * + * @param buffer the {@link Buffer} to use + * @return The {@link IoWriteFuture} for the operation */ IoWriteFuture write(Buffer buffer);
