com.sshtools.ssh

Interface SshSession

All Superinterfaces:

SshChannel, SshIO

All Known Implementing Classes:

Ssh2Session

public interface SshSession
extends SshChannel

Base interface for SSH sessions supporting all the features common to both SSH1 and SSH2. Sessions are created through the openSessionChannel() method of the SshClient. Once a session has been obtained the session will not be active until you either call executeCommand(String command) or startShell(). Once activated you can use the IO streams to read and write to the remote process. The following code shows the basic process:

 SshConnector con = SshConnector.getInstance();
 SshClient ssh = con.connect(
        new SocketTransport("beagle2.sshtools.net", 22),
        "martianx");
 
 PasswordAuthentication pwd = new PasswordAuthentication();
 pwd.setPassword("likeidgivethataway!");
 
 if(ssh.authenticate(pwd)==SshAuthentication.COMPLETE) {
        SshSession sesison = ssh.openSessionChannel();
 
      if(session.requestPseudoTerminal("vt100",
                        80,
                        24,
                         0,
                         0)) {
           session.startShell();
 
           session.getOutputStream().write("ls\n".getBytes());
      }
 } else {
        System.out.println("Authentication failed");
 }
 
 
 SshSession objects can't maintain state so performing a "cd c:\\temp" command would have no effect instead the Shell class should be used.
 
 

Author:

Lee David Painter

See Also:

com.sshtools.ssh1.Ssh1Session, Ssh2Session

Field Summary

Fields

Modifier and Type	Field and Description
static int	EXITCODE_NOT_RECEIVED Returned from exitCode() when the remote process is still active.

Method Summary

Methods

Modifier and Type	Method and Description
void	changeTerminalDimensions(int cols, int rows, int width, int height) Change the dimensions of the terminal window.
void	close() Close the session.
boolean	executeCommand(String cmd) Execute a command.
boolean	executeCommand(String cmd, String charset) Execute a command.
int	exitCode() Return the exit code of the process once complete.
SshClient	getClient() Get the client that created this session.
InputStream	getInputStream() Get an InputStream to read the process stdout.
OutputStream	getOutputStream() Get an OutputStream to write to the process stdin.
InputStream	getStderrInputStream() Get an InputStream to read the process stderr.
boolean	isClosed() Evaluate whether the channel is closed.
boolean	requestPseudoTerminal(String term, int cols, int rows, int width, int height) The remote process may require a pseudo terminal.
boolean	requestPseudoTerminal(String term, int cols, int rows, int width, int height, byte[] modes) The remote process may require a pseudo terminal.
boolean	requestPseudoTerminal(String term, int cols, int rows, int width, int height, PseudoTerminalModes terminalModes) The remote process may require a pseudo terminal.
boolean	startShell() Start the users default shell.

Methods inherited from interface com.sshtools.ssh.SshChannel

addChannelEventListener, getChannelId, getMessageRouter, setAutoConsumeInput

Field Detail

EXITCODE_NOT_RECEIVED

static final int EXITCODE_NOT_RECEIVED

Returned from exitCode() when the remote process is still active. NOTE: This may still be returned once the channel has been closed and should not be used as an indication of the remote process state.

See Also:

Constant Field Values

Method Detail

startShell

boolean startShell()
                   throws SshException

Start the users default shell.

Returns:

true if the shell was started, otherwise false

Throws:

SshException

getClient

SshClient getClient()

Get the client that created this session.

Returns:

SshClient

executeCommand

boolean executeCommand(String cmd)
                       throws SshException

Execute a command. An important note to remember is that this does not execute a shell command. You cannot for instance issue the command executeCommand("dir")" on the Windows Operating system as this is a shell command, instead use "cmd.exe /C dir". This method executes a binary executable and so should be used to execute any program other than the users shell. Calls to this method should only be used to execute commands that are indedependent, such as "mkdir /home/david/newfolder".

Parameters:

cmd -

Returns:

true if the command was accepted, otherwise false. This may not return false if the command is incorrect, it should only be used as an indication that the command was accepted and that the server will attempt to execute it.

Throws:

SshException

executeCommand

boolean executeCommand(String cmd,
                     String charset)
                       throws SshException

Execute a command. An important note to remember is that this does not execute a shell command. You cannot for instance issue the command executeCommand("dir")" on the Windows Operating system as this is a shell command, instead use "cmd.exe /C dir". This method executes a binary executable and so should be used to execute any program other than the users shell. Calls to this method should only be used to execute commands that are indedependent, such as "mkdir /home/david/newfolder".

Parameters:

cmd -

Returns:

true if the command was accepted, otherwise false. This may not return false if the command is incorrect, it should only be used as an indication that the command was accepted and that the server will attempt to execute it.

Throws:

SshException

requestPseudoTerminal

boolean requestPseudoTerminal(String term,
                            int cols,
                            int rows,
                            int width,
                            int height,
                            byte[] modes)
                              throws SshException

The remote process may require a pseudo terminal. Call this method before executing a command or starting a shell.

Parameters:

term - the terminal type e.g "vt100"

cols - the number of columns

rows - the number of rows

width - the width of the terminal (informational only, can be zero)

height - the height of the terminal (informational only, can be zero)

modes - an array of encoded terminal modes as described in the SSH protocol specifications.

Returns:

true if the pty was allocated, otherwise false

Throws:

SshException

requestPseudoTerminal

boolean requestPseudoTerminal(String term,
                            int cols,
                            int rows,
                            int width,
                            int height,
                            PseudoTerminalModes terminalModes)
                              throws SshException

The remote process may require a pseudo terminal. Call this method before executing a command or starting a shell.

Parameters:

term - the terminal type e.g "vt100"

cols - the number of columns

rows - the number of rows

width - the width of the terminal (informational only, can be zero)

height - the height of the terminal (informational only, can be zero)

terminalModes - the known terminal modes

Returns:

true if the pty was allocated, otherwise false

Throws:

SshException

requestPseudoTerminal

boolean requestPseudoTerminal(String term,
                            int cols,
                            int rows,
                            int width,
                            int height)
                              throws SshException

The remote process may require a pseudo terminal. Call this method before executing a command or starting a shell.

Parameters:

term - the terminal type e.g "vt100"

cols - the number of columns

rows - the number of rows

width - the width of the terminal (informational only, can be zero)

height - the height of the terminal (informational only, can be zero)

Returns:

true if the pty was allocated, otherwise false

Throws:

SshException

getInputStream

InputStream getInputStream()
                           throws SshIOException

Get an InputStream to read the process stdout.

Specified by:

getInputStream in interface SshIO

Returns:

the sessions InputStream

Throws:

SshException

SshIOException

getOutputStream

OutputStream getOutputStream()
                             throws SshIOException

Get an OutputStream to write to the process stdin.

Specified by:

getOutputStream in interface SshIO

Returns:

the sessions OutputStream

Throws:

SshException

SshIOException

getStderrInputStream

InputStream getStderrInputStream()
                                 throws SshIOException

Get an InputStream to read the process stderr.

Returns:

the sessions stderr InputStream

Throws:

SshException

SshIOException

close

void close()

Close the session.

Specified by:

close in interface SshIO

exitCode

int exitCode()

Return the exit code of the process once complete. Call this after the session has been closed to obtain the exit code of the process. It MAY or MAY NOT be sent by the server. If the exit code was not received this method will return EXITCODE_NOT_RECEIVED.

Returns:

the exit code value or SshSession.EXITCODE_NOT_RECEIVED

changeTerminalDimensions

void changeTerminalDimensions(int cols,
                            int rows,
                            int width,
                            int height)
                              throws SshException

Change the dimensions of the terminal window. This method should be called when the session is active and the user or application changes the size of the terminal window.

Parameters:

cols -

rows -

width -

height -

Throws:

SshException

isClosed

boolean isClosed()

Evaluate whether the channel is closed.

Specified by:

isClosed in interface SshChannel

Returns:

true if the session is closed, otherwise false