public class

Session

extends Object
java.lang.Object
   ↳ com.trilead.ssh2.Session

Class Overview

A Session is a remote execution of a program. "Program" means in this context either a shell, an application or a system command. The program may or may not have a tty. Only one single program can be started on a session. However, multiple sessions can be active simultaneously.

Summary

Fields
ChannelManager cm
Channel cn
boolean flag_closed
boolean flag_execution_started
boolean flag_pty_requested
boolean flag_x11_requested
final SecureRandom rnd
String x11FakeCookie
Public Methods
void close()
Close this session.
void execCommand(String cmd)
Execute a command on the remote machine.
String getExitSignal()
Get the name of the signal by which the process on the remote side was stopped - if available and applicable.
Integer getExitStatus()
Get the exit code/status from the remote command - if available.
InputStream getStderr()
OutputStream getStdin()
InputStream getStdout()
void ping()
This method can be used to perform end-to-end session (i.e., SSH channel) testing.
void requestDumbPTY()
Basically just a wrapper for lazy people - identical to calling requestPTY("dumb", 0, 0, 0, 0, null).
void requestPTY(String term)
Basically just another wrapper for lazy people - identical to calling requestPTY(term, 0, 0, 0, 0, null).
void requestPTY(String term, int term_width_characters, int term_height_characters, int term_width_pixels, int term_height_pixels, byte[] terminal_modes)
Allocate a pseudo-terminal for this session.
void requestWindowSizeChange(int term_width_characters, int term_height_characters, int term_width_pixels, int term_height_pixels)
Request window change.
void requestX11Forwarding(String hostname, int port, byte[] cookie, boolean singleConnection)
Request X11 forwarding for the current session.
void startShell()
Start a shell on the remote machine.
void startSubSystem(String name)
Start a subsystem on the remote machine.
int waitForCondition(int condition_set, long timeout)
This method blocks until certain conditions hold true on the underlying SSH-2 channel.
int waitUntilDataAvailable(long timeout)
This method is deprecated. This method has been replaced with a much more powerful wait-for-condition interface and therefore acts only as a wrapper.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

ChannelManager cm

Channel cn

boolean flag_closed

boolean flag_execution_started

boolean flag_pty_requested

boolean flag_x11_requested

final SecureRandom rnd

String x11FakeCookie

Public Methods

public void close ()

Close this session. NEVER forget to call this method to free up resources - even if you got an exception from one of the other methods (or when getting an Exception on the Input- or OutputStreams). Sometimes these other methods may throw an exception, saying that the underlying channel is closed (this can happen, e.g., if the other server sent a close message.) However, as long as you have not called the close() method, you may be wasting (local) resources.

public void execCommand (String cmd)

Execute a command on the remote machine.

Parameters
cmd The command to execute on the remote host.
Throws
IOException

public String getExitSignal ()

Get the name of the signal by which the process on the remote side was stopped - if available and applicable. Be careful - not all server implementations return this value.

Returns
  • An String holding the name of the signal, or null if the process exited normally or is still running (or if the server forgot to send this information).

public Integer getExitStatus ()

Get the exit code/status from the remote command - if available. Be careful - not all server implementations return this value. It is generally a good idea to call this method only when all data from the remote side has been consumed (see also the method).

Returns
  • An Integer holding the exit code, or null if no exit code is (yet) available.

public InputStream getStderr ()

public OutputStream getStdin ()

public InputStream getStdout ()

public void ping ()

This method can be used to perform end-to-end session (i.e., SSH channel) testing. It sends a 'ping' message to the server and waits for the 'pong' from the server.

Implementation details: this method sends a SSH_MSG_CHANNEL_REQUEST request ('trilead-ping') to the server and waits for the SSH_MSG_CHANNEL_FAILURE reply packet.

Throws
IOException in case of any problem or when the session is closed

public void requestDumbPTY ()

Basically just a wrapper for lazy people - identical to calling requestPTY("dumb", 0, 0, 0, 0, null).

Throws
IOException

public void requestPTY (String term)

Basically just another wrapper for lazy people - identical to calling requestPTY(term, 0, 0, 0, 0, null).

Parameters
term
Throws
IOException

public void requestPTY (String term, int term_width_characters, int term_height_characters, int term_width_pixels, int term_height_pixels, byte[] terminal_modes)

Allocate a pseudo-terminal for this session.

This method may only be called before a program or shell is started in this session.

Different aspects can be specified:

  • The TERM environment variable value (e.g., vt100)
  • The terminal's dimensions.
  • The encoded terminal modes.
Zero dimension parameters are ignored. The character/row dimensions override the pixel dimensions (when nonzero). Pixel dimensions refer to the drawable area of the window. The dimension parameters are only informational. The encoding of terminal modes (parameter terminal_modes) is described in RFC4254.

Parameters
term The TERM environment variable value (e.g., vt100)
term_width_characters Terminal width, characters (e.g., 80)
term_height_characters Terminal height, rows (e.g., 24)
term_width_pixels Terminal width, pixels (e.g., 640)
term_height_pixels Terminal height, pixels (e.g., 480)
terminal_modes Encoded terminal modes (may be null)
Throws
IOException

public void requestWindowSizeChange (int term_width_characters, int term_height_characters, int term_width_pixels, int term_height_pixels)

Request window change.

This method may only be called after a program or shell is started in this session.

Zero dimension parameters are ignored. The character/row dimensions override the pixel dimensions (when nonzero). Pixel dimensions refer to the drawable area of the window. The dimension parameters are only informational.

Parameters
term_width_characters Terminal width, characters (e.g., 80)
term_height_characters Terminal height, rows (e.g., 24)
term_width_pixels Terminal width, pixels (e.g., 640)
term_height_pixels Terminal height, pixels (e.g., 480)
Throws
IOException

public void requestX11Forwarding (String hostname, int port, byte[] cookie, boolean singleConnection)

Request X11 forwarding for the current session.

You have to supply the name and port of your X-server.

This method may only be called before a program or shell is started in this session.

Parameters
hostname The hostname of the real (target) X11 server (e.g., 127.0.0.1)
port The port of the real (target) X11 server (e.g., 6010)
cookie If non-null, then present this cookie to the real X11 server
singleConnection If true, then the server is instructed to only forward one single connection, no more connections shall be forwarded after first, or after the session channel has been closed
Throws
IOException

public void startShell ()

Start a shell on the remote machine.

Throws
IOException

public void startSubSystem (String name)

Start a subsystem on the remote machine. Unless you know what you are doing, you will never need this.

Parameters
name The name of the subsystem.
Throws
IOException

public int waitForCondition (int condition_set, long timeout)

This method blocks until certain conditions hold true on the underlying SSH-2 channel.

This method returns as soon as one of the following happens:

  • at least of the specified conditions (see ChannelCondition) holds true
  • timeout > 0 and a timeout occured (TIMEOUT will be set in result conditions)
  • the underlying channel was closed (CLOSED will be set in result conditions)

In any case, the result value contains ALL current conditions, which may be more than the specified condition set (i.e., never use the "==" operator to test for conditions in the bitmask, see also comments in ChannelCondition).

Note: do NOT call this method if you want to wait for STDOUT_DATA or STDERR_DATA and there are concurrent threads (e.g., StreamGobblers) that operate on either of the two InputStreams of this Session (otherwise this method may block, even though more data is available in the StreamGobblers).

Parameters
condition_set A bitmask based on ChannelCondition values
timeout Non-negative timeout in ms, 0 means no timeout
Returns
  • all bitmask specifying all current conditions that are true

public int waitUntilDataAvailable (long timeout)

This method is deprecated.
This method has been replaced with a much more powerful wait-for-condition interface and therefore acts only as a wrapper.

This method blocks until there is more data available on either the stdout or stderr InputStream of this Session. Very useful if you do not want to use two parallel threads for reading from the two InputStreams. One can also specify a timeout. NOTE: do NOT call this method if you use concurrent threads that operate on either of the two InputStreams of this Session (otherwise this method may block, even though more data is available).

Parameters
timeout The (non-negative) timeout in ms. 0 means no timeout, the call may block forever.
Returns
    • 0 if no more data will arrive.
    • 1 if more data is available.
    • -1 if a timeout occurred.
Throws
IOException
IOException