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.
    Version:
    $Id: Session.java,v 1.2 2008/03/03 07:01:36 cplattne Exp $
    • Constructor Summary

      Constructors 
      Constructor Description
      Session​(ChannelManager cm, java.security.SecureRandom rnd)  
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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 ping()
      This method can be used to perform end-to-end session (i.e., SSH channel) testing.
      void pipeStderr​(java.io.OutputStream os)
      The same as pipeStdout(OutputStream) except for stderr, not for stdout.
      void pipeStdout​(java.io.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​(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 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​(java.lang.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​(java.lang.String name)
      Sends a signal to the remote process.
      void startShell()
      Start a shell on the remote machine.
      void startSubSystem​(java.lang.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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • flag_pty_requested

        boolean flag_pty_requested
      • flag_x11_requested

        boolean flag_x11_requested
      • flag_execution_started

        boolean flag_execution_started
      • flag_closed

        boolean flag_closed
      • x11FakeCookie

        java.lang.String x11FakeCookie
      • rnd

        final java.security.SecureRandom rnd
    • Constructor Detail

      • Session

        Session​(ChannelManager cm,
                java.security.SecureRandom rnd)
         throws java.io.IOException
        Throws:
        java.io.IOException
    • 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 - the io exception
      • 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).
        Parameters:
        term - the term
        Throws:
        java.io.IOException - the io exception
      • 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:

        • 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:
        java.io.IOException - the io exception
      • requestWindowChange

        public void requestWindowChange​(int term_width_characters,
                                        int term_height_characters,
                                        int term_width_pixels,
                                        int term_height_pixels)
                                 throws java.io.IOException
        Tells the server that the size of the terminal has changed. See requestPTY(String, int, int, int, int, byte[]) for more details about how parameters are interpreted.
        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:
        java.io.IOException - the io exception
      • signal

        public void signal​(java.lang.String name)
                    throws java.io.IOException
        Sends a signal to the remote process.
        Parameters:
        name - the name
        Throws:
        java.io.IOException - the io exception
      • signal

        public void signal​(int code)
                    throws java.io.IOException
        Sends a signal to the remote process.

        For better portability, specify signal by name, not by its number.

        Parameters:
        code - the code
        Throws:
        java.io.IOException - the io exception
      • requestX11Forwarding

        public void requestX11Forwarding​(java.lang.String hostname,
                                         int port,
                                         byte[] cookie,
                                         boolean singleConnection)
                                  throws java.io.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.

        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:
        java.io.IOException - the io exception
      • 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 - the io exception
      • startShell

        public void startShell()
                        throws java.io.IOException
        Start a shell on the remote machine.
        Throws:
        java.io.IOException - the io exception
      • startSubSystem

        public void startSubSystem​(java.lang.String name)
                            throws java.io.IOException
        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:
        java.io.IOException - the io exception
      • ping

        public void ping()
                  throws java.io.IOException
        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:
        java.io.IOException - in case of any problem or when the session is closed
      • getStdout

        public java.io.InputStream getStdout()
      • getStderr

        public java.io.InputStream getStderr()
      • getStdin

        public java.io.OutputStream getStdin()
      • pipeStdout

        public void pipeStdout​(java.io.OutputStream os)
                        throws java.io.IOException
        Write stdout received from the other side to the specified 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.

        Parameters:
        os - the os
        Throws:
        java.io.IOException - the io exception
      • pipeStderr

        public void pipeStderr​(java.io.OutputStream os)
                        throws java.io.IOException
        The same as pipeStdout(OutputStream) except for stderr, not for stdout.
        Parameters:
        os - the os
        Throws:
        java.io.IOException - the io exception
      • waitUntilDataAvailable

        public int waitUntilDataAvailable​(long timeout)
                                   throws java.io.IOException,
                                          java.lang.InterruptedException
        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:
        java.io.IOException - the io exception
        java.lang.InterruptedException - the interrupted exception
      • waitForCondition

        public int waitForCondition​(int condition_set,
                                    long timeout)
                             throws java.lang.InterruptedException
        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
        Throws:
        java.lang.InterruptedException - the interrupted exception
      • 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 (see also the WaitForCondition method).
        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 (or if the server forgot to send this information).
      • 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.
      • setWindowSize

        public void setWindowSize​(int newSize)
        Sets the receive window size.

        The receive window is a maximum number of bytes that the remote side can send to this channel without waiting for us to consume them (AKA "in-flight bytes").

        When your connection is over a large-latency/high-bandiwdth network, specifying a bigger value allows the network to be efficiently utilized. OTOH, if you don't drain this channel quickly enough all those bytes in flight can end up getting buffered.

        This value can be adjusted at runtime.

        Parameters:
        newSize - the new size