| java.lang.Object
 ch.ethz.ssh2.Session
| Session | | public class Session (Code) | | 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.
author:
Christian Plattner, plattner@inf.ethz.ch
version:
$Id: Session.java,v 1.9 2006/02/14 19:43:16 cplattne Exp $ |
| Method Summary | |
| public void | close()
Close this session. | | public void | execCommand(String cmd)
Execute a command on the remote machine. | | public String | getExitSignal()
Get the name of the signal by which the process on the remote side was
stopped - if available and applicable. | | public Integer | getExitStatus()
Get the exit code/status from the remote command - if available. | | public InputStream | getStderr()
| | public OutputStream | getStdin()
| | public InputStream | getStdout()
| | public void | requestDumbPTY()
Basically just a wrapper for lazy people - identical to calling
requestPTY("dumb", 0, 0, 0, 0, null). | | public void | requestPTY(String term)
Basically just another wrapper for lazy people - identical to calling
requestPTY(term, 0, 0, 0, 0, null). | | 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. | | public void | requestX11Forwarding(String hostname, int port, byte[] cookie, boolean singleConnection)
Request X11 forwarding for the current session. | | public void | startShell()
Start a shell on the remote machine. | | public void | startSubSystem(String name)
Start a subsystem on the remote machine. | | 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 ). | | public int | waitUntilDataAvailable(long timeout)
This method blocks until there is more data available on either the
stdout or stderr InputStream of this Session. |
| flag_closed | | boolean flag_closed(Code) | | |
| flag_execution_started | | boolean flag_execution_started(Code) | | |
| flag_pty_requested | | boolean flag_pty_requested(Code) | | |
| flag_x11_requested | | boolean flag_x11_requested(Code) | | |
| close | | public void close()(Code) | | 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(Code) | | Execute a command on the remote machine.
Parameters:
cmd - The command to execute on the remote host.
throws:
IOException - |
| getExitSignal | | public String getExitSignal()(Code) | | 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, ornull if the process exited normally or is stillrunning (or if the server forgot to send this information). |
| getExitStatus | | public Integer getExitStatus()(Code) | | 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, ornull if no exit code is (yet) available. |
| requestDumbPTY | | public void requestDumbPTY() throws IOException(Code) | | Basically just a wrapper for lazy people - identical to calling
requestPTY("dumb", 0, 0, 0, 0, null).
throws:
IOException - |
| requestPTY | | public void requestPTY(String term) throws IOException(Code) | | Basically just another wrapper for lazy people - identical to calling
requestPTY(term, 0, 0, 0, 0, null).
throws:
IOException - |
| 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(Code) | | 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, e.g., in
draft-ietf-secsh-connect-XY.txt.
Parameters:
term - The TERM environment variable value (e.g., vt100)
Parameters:
term_width_characters - terminal width, characters (e.g., 80)
Parameters:
term_height_characters - terminal height, rows (e.g., 24)
Parameters:
term_width_pixels - terminal width, pixels (e.g., 640)
Parameters:
term_height_pixels - terminal height, pixels (e.g., 480)
Parameters:
terminal_modes - encoded terminal modes (may be null)
throws:
IOException - |
| requestX11Forwarding | | public void requestX11Forwarding(String hostname, int port, byte[] cookie, boolean singleConnection) throws IOException(Code) | | 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)
Parameters:
port - the port of the real (target) X11 server (e.g., 6010)
Parameters:
cookie - if non-null, then present this cookie to the real X11 server
Parameters:
singleConnection - if true, then the server is instructed to only forward one singleconnection, no more connections shall be forwarded after first, or after the sessionchannel has been closed
throws:
IOException - |
| startSubSystem | | public void startSubSystem(String name) throws IOException(Code) | | 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 - |
| waitForCondition | | public int waitForCondition(int condition_set, long timeout)(Code) | | 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
Parameters:
timeout - 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(Code) | | 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 notimeout, the call may block forever.0 if no more data will arrive.1 if more data is available.-1 if a timeout occurred.
throws:
IOException - |
|
|