You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by lg...@apache.org on 2015/07/28 14:08:08 UTC
[4/4] mina-sshd git commit: [SSHD-542] Checkstyle validation
[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 <lg...@vmware.com>
Authored: Tue Jul 28 15:07:30 2015 +0300
Committer: Lyor Goldstein <lg...@vmware.com>
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:dev@mina.apache.org">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:dev@mina.apache.org">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:dev@mina.apache.org">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 "fsync@openssh.com" extension
*
* @author <a href="mailto:dev@mina.apache.org">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:dev@mina.apache.org">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:dev@mina.apache.org">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:dev@mina.apache.org">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);