Ganymed SSH2 for Java

ch.ethz.ssh2
Class Session

java.lang.Object
  extended bych.ethz.ssh2.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.

Version:
$Id: Session.java,v 1.3 2005/08/11 12:47:31 cplattne Exp $
Author:
Christian Plattner, plattner@inf.ethz.ch

Method Summary
 void close()
          Close this session.
 void execCommand(java.lang.String cmd)
          Execute a command on the remote machine.
 java.lang.String getExitSignal()
          Get the name of the signal by which the process on the remote side was stopped - if available and applicable.
 java.lang.Integer getExitStatus()
          Get the exit code/status from the remote command - if available.
 java.io.InputStream getStderr()
           
 java.io.OutputStream getStdin()
           
 java.io.InputStream getStdout()
           
 void requestDumbPTY()
          Basically just a wrapper for lazy people - identical to calling requestPTY("dumb", 0, 0, 0, 0, null).
 void requestPTY(java.lang.String term)
          Basically just another wrapper for lazy people - identical to calling requestPTY(term, 0, 0, 0, 0, null).
 void requestPTY(java.lang.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 startShell()
          Start a shell on the remote machine.
 int waitUntilDataAvailable(long timeout)
          This method blocks until there is more data available on either the stdout or stderr InputStream of this Session.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

requestDumbPTY

public void requestDumbPTY()
                    throws java.io.IOException
Basically just a wrapper for lazy people - identical to calling requestPTY("dumb", 0, 0, 0, 0, null).

Throws:
java.io.IOException

requestPTY

public void requestPTY(java.lang.String term)
                throws java.io.IOException
Basically just another wrapper for lazy people - identical to calling requestPTY(term, 0, 0, 0, 0, null).

Throws:
java.io.IOException

requestPTY

public void requestPTY(java.lang.String term,
                       int term_width_characters,
                       int term_height_characters,
                       int term_width_pixels,
                       int term_height_pixels,
                       byte[] terminal_modes)
                throws java.io.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:

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)
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:
java.io.IOException

execCommand

public void execCommand(java.lang.String cmd)
                 throws java.io.IOException
Execute a command on the remote machine.

Parameters:
cmd - The command to execute on the remote host.
Throws:
java.io.IOException

startShell

public void startShell()
                throws java.io.IOException
Start a shell on the remote machine.

Throws:
java.io.IOException

getStdout

public java.io.InputStream getStdout()
                              throws java.io.IOException
Throws:
java.io.IOException

getStderr

public java.io.InputStream getStderr()
                              throws java.io.IOException
Throws:
java.io.IOException

getStdin

public java.io.OutputStream getStdin()
                              throws java.io.IOException
Throws:
java.io.IOException

waitUntilDataAvailable

public int waitUntilDataAvailable(long timeout)
                           throws java.io.IOException
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 timeout in ms. 0 means no timeout, the call may block forever.
Returns:
  • 0 if no more data will arrive (EOF on both streams).
  • 1 if more data is available.
  • -1 if a timeout occurred.
Throws:
java.io.IOException

getExitStatus

public java.lang.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.

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

getExitSignal

public java.lang.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.

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 calling a method 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 resources.


Ganymed SSH2 for Java