com.mindbright.ssh2
Class SSH2ConsoleRemote

java.lang.Object
  com.mindbright.ssh2.SSH2ConsoleRemote

All Implemented Interfaces:

SSHConsoleRemote

Direct Known Subclasses:

SSH2SCP1Client

public class SSH2ConsoleRemote
extends java.lang.Object
implements SSHConsoleRemote

This class implements a console to a remote command or shell. The underlying mechanism is a session channel which is created on demand from the provided connection layer. It can be used to execute single commands and/or control input/output to/from a shell. It is for example extended to control an SCP1 client in the class SSH2SCP1Client.

To create a SSH2ConsoleRemote instance a complete connected ssh2 stack is needed from which one provides the SSH2Connection to the constructor.

See Also:

SSH2Connection, SSH2SimpleClient

Field Summary

protected SSH2Connection	connection
protected SSH2SessionChannel	session
protected java.io.OutputStream	stderr
protected java.io.OutputStream	stdout

Constructor Summary

SSH2ConsoleRemote(SSH2Connection connection)
Basic constructor.

SSH2ConsoleRemote(SSH2Connection connection, java.io.OutputStream stdout, java.io.OutputStream stderr)
Constructor to be used to preset the stdout and/or stderr output streams to which the correspondings streams should be redirected to.

Method Summary

void	changeStdOut(NonBlockingOutput out) Changes the output stream where stdout is written to in the underlying session channel.
void	changeStdOut(java.io.OutputStream out) Changes the output stream where stdout is written to in the underlying session channel.
void	close() Closes the session channel.
void	close(boolean waitforcloseconfirm) Closes the session channel.
boolean	command(java.lang.String command) Runs single command on server.
boolean	command(java.lang.String command, boolean pty) Runs single command on server.
boolean	command(java.lang.String command, NonBlockingInput stdin, NonBlockingOutput stdout, NonBlockingOutput stderr) Runs single command on server and redirects stdout to the given NonBlockingOutput.
boolean	command(java.lang.String command, NonBlockingInput stdin, NonBlockingOutput stdout, NonBlockingOutput stderr, boolean pty) Runs single command on server and redirects stdout to the given NonBlockingOutput.
boolean	command(java.lang.String command, NonBlockingInput stdin, NonBlockingOutput stdout, NonBlockingOutput stderr, boolean pty, java.lang.String termType, int rows, int cols) Runs single command on server and redirects stdout to the given NonBlockingOutput.
boolean	command(java.lang.String command, java.io.OutputStream stdout) Runs single command on server and redirects stdout to the given OutputStream.
boolean	command(java.lang.String command, java.io.OutputStream stdout, boolean pty) Runs single command on server and redirects stdout to the given OutputStream.
boolean	command(java.lang.String command, java.io.OutputStream stdout, java.io.OutputStream stderr) Runs single command on server and redirects stdout to the given OutputStream.
boolean	command(java.lang.String command, java.io.OutputStream stdout, java.io.OutputStream stderr, boolean pty) Runs single command on server and redirects stdout to the given OutputStream.
boolean	command(java.lang.String command, java.io.OutputStream stdout, java.io.OutputStream stderr, boolean pty, java.lang.String termType, int rows, int cols) Runs single command on server and redirects stdout to the given OutputStream.
boolean	commandWithTerminal(SSH2TerminalAdapter termAdapter, java.lang.String command) Run a command on the server and connect it to the given terminal.
NonBlockingOutput	getNBStdIn() Gets the stdin stream of the underlying session channel.
NonBlockingInput	getNBStdOut() Gets the stdout stream of the underlying session channel.
java.io.OutputStream	getStdIn() Gets the stdin stream of the underlying session channel.
java.io.InputStream	getStdOut() Gets the stdout stream of the underlying session channel.
boolean	sendBreak(int length) Send a BREAK to the remote session (see draft-ietf-secsh-break for more information)
boolean	shell() Starts an interactive shell on the server, note that no PTY is allocated.
boolean	shell(boolean pty) Starts an interactive shell on the server.
boolean	shell(boolean pty, java.lang.String termType, int rows, int cols) Starts an interactive shell on the server.
boolean	shell(NonBlockingInput stdin, NonBlockingOutput stdout, NonBlockingOutput stderr) Starts an interactive shell on the server.
boolean	shell(NonBlockingInput stdin, NonBlockingOutput stdout, NonBlockingOutput stderr, boolean pty, java.lang.String termType, int rows, int cols) Starts an interactive shell on the server.
boolean	terminal(SSH2TerminalAdapter termAdapter) Start an interactive shell on the server and connect it to the given terminal.
int	waitForExitStatus() Retrieves the exit status reported by the command/shell run.
int	waitForExitStatus(int timeout) Retrieves the exit status reported by the command/shell run.
int	waitForExitStatus(long timeout) Waits for the command to finish within the given time.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

connection

protected SSH2Connection connection

session

protected SSH2SessionChannel session

stdout

protected java.io.OutputStream stdout

stderr

protected java.io.OutputStream stderr

Constructor Detail

SSH2ConsoleRemote

public SSH2ConsoleRemote(SSH2Connection connection)

Basic constructor.

Parameters:

connection - connected connection layer

SSH2ConsoleRemote

public SSH2ConsoleRemote(SSH2Connection connection,
                         java.io.OutputStream stdout,
                         java.io.OutputStream stderr)

Constructor to be used to preset the stdout and/or stderr output streams to which the correspondings streams should be redirected to. That is when the streams doesn't have to be passed to the command() method.

Parameters:

connection - connected connection layer

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

Method Detail

command

public boolean command(java.lang.String command)

Description copied from interface: SSHConsoleRemote

Runs single command on server. Stdout from the command will be sent to the local stdout.

Note, this will create an extra pair of threads to handle the data.

Specified by:

command in interface SSHConsoleRemote

Parameters:

command - command line to run

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       boolean pty)

Runs single command on server. Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

pty - whether to allocate a pty on the server or not

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       java.io.OutputStream stdout)

Runs single command on server and redirects stdout to the given OutputStream.

Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

stdout - the output stream to redirect stdout to

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       java.io.OutputStream stdout,
                       boolean pty)

Runs single command on server and redirects stdout to the given OutputStream. It is also possible to allocate a pty for the command on the server.

Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

stdout - the output stream to redirect stdout to

pty - whether to allocate a pty or not

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       java.io.OutputStream stdout,
                       java.io.OutputStream stderr)

Runs single command on server and redirects stdout to the given OutputStream. This method also redirects stderr to the given OutputStream.

Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       NonBlockingInput stdin,
                       NonBlockingOutput stdout,
                       NonBlockingOutput stderr)

Runs single command on server and redirects stdout to the given NonBlockingOutput. This method also redirects stderr to the given NonBlockingOutput.

Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

stdin - the input stream to read input from (can be null)

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       java.io.OutputStream stdout,
                       java.io.OutputStream stderr,
                       boolean pty)

Runs single command on server and redirects stdout to the given OutputStream. This method also redirects stderr to the given OutputStream. It is also possible to allocate a pty for the command on the server.

Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

pty - whether to allocate a pty or not

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       NonBlockingInput stdin,
                       NonBlockingOutput stdout,
                       NonBlockingOutput stderr,
                       boolean pty)

Runs single command on server and redirects stdout to the given NonBlockingOutput. This method also redirects stderr to the given NonBlockingOutput. It is also possible to allocated a pty for the remote command.

Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

stdin - the input stream to read input from (can be null)

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

pty - whether to allocate a pty or not

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       java.io.OutputStream stdout,
                       java.io.OutputStream stderr,
                       boolean pty,
                       java.lang.String termType,
                       int rows,
                       int cols)

Runs single command on server and redirects stdout to the given OutputStream. This method also redirects stderr to the given OutputStream. This method can also set the terminal type and layout for the remote command. It is also possible to allocated a pty for the remote command.

Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

pty - whether to allocate a pty or not

termType - indicates which terminal type to request

rows - indicates the number of rows on the terminal

cols - indicates the number of columns on the terminal

Returns:

a boolean indicating success or failure

command

public boolean command(java.lang.String command,
                       NonBlockingInput stdin,
                       NonBlockingOutput stdout,
                       NonBlockingOutput stderr,
                       boolean pty,
                       java.lang.String termType,
                       int rows,
                       int cols)

Runs single command on server and redirects stdout to the given NonBlockingOutput. This method also redirects stderr to the given NonBlockingOutput. This method can also set the terminal type and layout for the remote command. It is also possible to allocated a pty for the remote command.

Note that the call will return once the command has been launched on the server and that it does not wait until the command has completed. For waiting look at the waitForExitStatus() method.

Note, this will create an extra pair of threads to handle the data.

Parameters:

command - command line to run

stdin - the input stream to read input from (can be null)

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

pty - whether to allocate a pty or not

termType - indicates which terminal type to request

rows - indicates the number of rows on the terminal

cols - indicates the number of columns on the terminal

Returns:

a boolean indicating success or failure

shell

public boolean shell()

Description copied from interface: SSHConsoleRemote

Starts an interactive shell on the server, note that no PTY is allocated.

Specified by:

shell in interface SSHConsoleRemote

Returns:

a boolean indicating success or failure

shell

public boolean shell(boolean pty)

Starts an interactive shell on the server. The parameter pty indicates whether to allocate a PTY or not.

Parameters:

pty - indicates whether to allocate a PTY or not

Returns:

a boolean indicating success or failure

shell

public boolean shell(boolean pty,
                     java.lang.String termType,
                     int rows,
                     int cols)

Starts an interactive shell on the server. The parameter pty indicates whether to allocate a PTY or not.

Parameters:

pty - indicates whether to allocate a PTY or not

termType - indicates which terminal type to request

rows - indicates the number of rows on the terminal

cols - indicates the number of columns on the terminal

Returns:

a boolean indicating success or failure

shell

public boolean shell(NonBlockingInput stdin,
                     NonBlockingOutput stdout,
                     NonBlockingOutput stderr)

Starts an interactive shell on the server. The parameter pty indicates whether to allocate a PTY or not. This method redirects stdin, stdout and stderr to the provided non blocking streams. It is also possible to setup the terminal type to run in.

Parameters:

stdin - the input stream to read input from (can be null)

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

Returns:

a boolean indicating success or failure

shell

public boolean shell(NonBlockingInput stdin,
                     NonBlockingOutput stdout,
                     NonBlockingOutput stderr,
                     boolean pty,
                     java.lang.String termType,
                     int rows,
                     int cols)

Starts an interactive shell on the server. The parameter pty indicates whether to allocate a PTY or not. This method redirects stdin, stdout and stderr to the provided non blocking streams. It is also possible to setup the terminal type to run in.

Parameters:

stdin - the input stream to read input from (can be null)

stdout - the output stream to redirect stdout to (can be null)

stderr - the output stream to redirect stderr to (can be null)

pty - indicates whether to allocate a PTY or not

termType - indicates which terminal type to request

rows - indicates the number of rows on the terminal

cols - indicates the number of columns on the terminal

Returns:

a boolean indicating success or failure

terminal

public boolean terminal(SSH2TerminalAdapter termAdapter)

Start an interactive shell on the server and connect it to the given terminal.

Parameters:

termAdapter - identifies the terminal window to associate the shell with.

Returns:

a boolean indicating success or failure

commandWithTerminal

public boolean commandWithTerminal(SSH2TerminalAdapter termAdapter,
                                   java.lang.String command)

Run a command on the server and connect it to the given terminal.

Parameters:

termAdapter - identifies the terminal window to associate the shell with.

command - command line to run

Returns:

a boolean indicating success or failure

waitForExitStatus

public int waitForExitStatus()

Retrieves the exit status reported by the command/shell run. Note that this call blocks until the remote command/shell really exits or the session is canceled (e.g. by calling close()) in which case the status returned will be -1.

Returns:

the exit status reported

waitForExitStatus

public int waitForExitStatus(int timeout)

Retrieves the exit status reported by the command/shell run. Note that this call blocks until the remote command/shell really exits or the session is canceled (e.g. by calling close()) in which case the status returned will be -1.

Parameters:

timeout - timeout in milliseconds

Returns:

the exit status reported

waitForExitStatus

public int waitForExitStatus(long timeout)
                      throws TimeoutException

Waits for the command to finish within the given time.

Parameters:

timeout - timeout time in milliseconds

Throws:

TimeoutException

sendBreak

public boolean sendBreak(int length)

Send a BREAK to the remote session (see draft-ietf-secsh-break for more information)

Parameters:

length - the BREAK length (ms)

Returns:

a boolean indicating success or failure

close

public void close()

Description copied from interface: SSHConsoleRemote

Closes the session channel. That is cancels a command/shell in progress if it hasn't already exited.

Specified by:

close in interface SSHConsoleRemote

close

public void close(boolean waitforcloseconfirm)

Description copied from interface: SSHConsoleRemote

Closes the session channel. If waitforcloseconfirm is true it waits for the remote end to acknowledge the close.

Specified by:

close in interface SSHConsoleRemote

changeStdOut

public void changeStdOut(java.io.OutputStream out)

Description copied from interface: SSHConsoleRemote

Changes the output stream where stdout is written to in the underlying session channel.

Note that this method only works if the underlying session uses blocking streams and threads.

Specified by:

changeStdOut in interface SSHConsoleRemote

Parameters:

out - new stdout stream

getStdOut

public java.io.InputStream getStdOut()

Description copied from interface: SSHConsoleRemote

Gets the stdout stream of the underlying session channel. Note, this is an input stream since one wants to read from stdout.

Note that this method returns null if the underlying stream uses non-blocking io

Specified by:

getStdOut in interface SSHConsoleRemote

Returns:

the input stream of stdout stream

getStdIn

public java.io.OutputStream getStdIn()

Description copied from interface: SSHConsoleRemote

Gets the stdin stream of the underlying session channel. Note, this is an output stream since one wants to write to stdin.

Note that this method returns null if the underlying stream uses non-blocking io

Specified by:

getStdIn in interface SSHConsoleRemote

Returns:

the input stream of stdout stream

changeStdOut

public void changeStdOut(NonBlockingOutput out)
                  throws java.lang.IllegalArgumentException

Description copied from interface: SSHConsoleRemote

Changes the output stream where stdout is written to in the underlying session channel.

Note that this method only works if the underlying session uses non-blocking io.

Specified by:

changeStdOut in interface SSHConsoleRemote

Parameters:

out - new stdout stream

Throws:

java.lang.IllegalArgumentException

getNBStdIn

public NonBlockingOutput getNBStdIn()

Description copied from interface: SSHConsoleRemote

Gets the stdin stream of the underlying session channel. Note, this is an output stream since one wants to write to stdin.

Note that this method returns null if the underlying stream uses blocking io

Specified by:

getNBStdIn in interface SSHConsoleRemote

Returns:

the input stream of stdout stream

getNBStdOut

public NonBlockingInput getNBStdOut()

Description copied from interface: SSHConsoleRemote

Gets the stdout stream of the underlying session channel. Note, this is an input stream since one wants to read from stdout.

Note that this method returns null if the underlying stream uses blocking io

Specified by:

getNBStdOut in interface SSHConsoleRemote

Returns:

the input stream of stdout stream