public class Session extends Object
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.Modifier and Type | Method and Description |
---|---|
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 |
pipeStderr(OutputStream os)
The same as
pipeStdout(OutputStream) except for stderr, not for stdout. |
void |
pipeStdout(OutputStream os)
Write stdout received from the other side to the specified
OutputStream . |
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 |
requestWindowChange(int term_width_characters,
int term_height_characters,
int term_width_pixels,
int term_height_pixels)
Tells the server that the size of the terminal has changed.
|
void |
requestX11Forwarding(String hostname,
int port,
byte[] cookie,
boolean singleConnection)
Request X11 forwarding for the current session.
|
void |
setWindowSize(int newSize)
Sets the receive window size.
|
void |
signal(int code)
Sends a signal to the remote process.
|
void |
signal(String name)
Sends a signal to the remote process.
|
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)
Deprecated.
This method has been replaced with a much more powerful wait-for-condition
interface and therefore acts only as a wrapper.
|
public void requestDumbPTY() throws IOException
requestPTY("dumb", 0, 0, 0, 0, null)
.IOException
public void requestPTY(String term) throws IOException
requestPTY(term, 0, 0, 0, 0, null)
.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) throws IOException
This method may only be called before a program or shell is started in this session.
Different aspects can be specified:
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
)IOException
public void requestWindowChange(int term_width_characters, int term_height_characters, int term_width_pixels, int term_height_pixels) throws IOException
requestPTY(String, int, int, int, int, byte[])
for more details about how parameters are interpreted.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)IOException
public void signal(String name) throws IOException
IOException
public void signal(int code) throws IOException
IOException
public void requestX11Forwarding(String hostname, int port, byte[] cookie, boolean singleConnection) throws IOException
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 closedIOException
public void execCommand(String cmd) throws IOException
cmd
- The command to execute on the remote host.IOException
public void startShell() throws IOException
IOException
public void startSubSystem(String name) throws IOException
name
- the name of the subsystem.IOException
public void ping() throws IOException
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.
IOException
- in case of any problem or when the session is closedpublic InputStream getStdout()
public InputStream getStderr()
public OutputStream getStdin()
public void pipeStdout(OutputStream os) throws IOException
OutputStream
.
By default, when data arrives from the other side, trilead buffers them and lets
you read it at your convenience from getStdout()
. This is normally convenient,
but if all you are doing is to send the data to another OutputStream
by
copying a stream, then you'll be end up wasting a thread just for this.
In such a situation, you can call this method and let the I/O handling thread of trilead
directly pass the received data to the output stream. This also eliminates the internal
buffer used for spooling.
When you do this, beware of a blocking write! If a write blocks, it'll affect
all the other channels and sessions that are sharing the same SSH connection,
as there's only one I/O thread. For example, this can happen if you are writing to
Socket
.
If any data has already been received and spooled before calling this method, the data will be sent to the given stream immediately.
To signal the end of the stream, when the other side notifies us of EOF or when
the channel closes, the output stream gets closed. If this is not desirable,
you must wrap the output stream and ignore the OutputStream.close()
call.
IOException
public void pipeStderr(OutputStream os) throws IOException
pipeStdout(OutputStream)
except for stderr, not for stdout.IOException
public int waitUntilDataAvailable(long timeout) throws IOException, InterruptedException
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.IOException
InterruptedException
public int waitForCondition(int condition_set, long timeout) throws InterruptedException
This method returns as soon as one of the following happens:
ChannelCondition
) holds true
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 timeoutInterruptedException
public Integer getExitStatus()
method).
Integer
holding the exit code, or
null
if no exit code is (yet) available.public String getExitSignal()
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 void close()
close()
method, you may be wasting (local) resources.public void setWindowSize(int newSize)
Copyright © 2015. All rights reserved.