com.trilead.ssh2
Class Session
public class Session
extends java.lang.Object
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.
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 | 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 | 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 has been replaced with a much more powerful wait-for-condition
interface and therefore acts only as a wrapper.
|
close
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.
execCommand
public void execCommand(String cmd)
throws IOException
Execute a command on the remote machine.
cmd
- The command to execute on the remote host.
getExitSignal
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.
- 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).
getExitStatus
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).
- An
Integer
holding the exit code, or
null
if no exit code is (yet) available.
getStderr
public InputStream getStderr()
getStdin
public OutputStream getStdin()
getStdout
public InputStream getStdout()
requestDumbPTY
public void requestDumbPTY()
throws IOException
Basically just a wrapper for lazy people - identical to calling
requestPTY("dumb", 0, 0, 0, 0, null)
.
requestPTY
public void requestPTY(String term)
throws IOException
Basically just another wrapper for lazy people - identical to calling
requestPTY(term, 0, 0, 0, 0, null)
.
requestPTY
public void requestPTY(String term,
int term_width_characters,
int term_height_characters,
int term_width_pixels,
int term_height_pixels,
byte[] terminal_modes)
throws IOException
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.
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
)
requestX11Forwarding
public void requestX11Forwarding(String hostname,
int port,
byte[] cookie,
boolean singleConnection)
throws IOException
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.
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 serversingleConnection
- 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
startShell
public void startShell()
throws IOException
Start a shell on the remote machine.
startSubSystem
public void startSubSystem(String name)
throws IOException
Start a subsystem on the remote machine.
Unless you know what you are doing, you will never need this.
name
- the name of the subsystem.
waitForCondition
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).
condition_set
- a bitmask based on ChannelCondition
valuestimeout
- non-negative timeout in ms, 0
means no timeout
- all bitmask specifying all current conditions that are true
waitUntilDataAvailable
public int waitUntilDataAvailable(long timeout)
throws IOException
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).
timeout
- The (non-negative) timeout in ms
. 0
means no
timeout, the call may block forever.
0
if no more data will arrive.1
if more data is available.-1
if a timeout occurred.