com.jscape.inet.ssh

## Class SshSession

- java.lang.Object
- - com.jscape.inet.ssh.SshSession

-     public class SshSession
      extends java.lang.Object

  Convenience class for automating communications with a SSH server.

  Example:

       String shellPrompt = "$";

       // creates new SshShession instance providing hostname, username and password arguments
       SshSession session = new SshSession(hostname,username,password);

       // set expected shell prompt from SSH server
       session.setShellPrompt(shellPrompt);

       // establish connection
       session.connect();

       // send command to SSH shell and wait for shell prompt
       session.send("cd /user/logs");

       // send command to SSH shell and wait for shell prompt
       session.send("rm *.log");

       // send command to SSH shell and DO NOT wait for shell prompt
       session.sendNoWait("exit");

       // close connection with SSH server
       session.disconnect();

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SshSession(SshParameters sshParams)` Creates a new SshSession instance.
    `SshSession(SshParameters sshParams, Ssh ssh)` Creates a new SshSession instance.
    `SshSession(Ssh ssh, java.lang.String promptPattern, boolean promptPatternIsRegex, int regexMatchLength, java.lang.String endOfLine, java.lang.String characterSet, int pollingInterval)`
    `SshSession(java.lang.String hostname, int port, java.lang.String username, java.lang.String password)` Creates a new SshSession instance.
    `SshSession(java.lang.String hostname, java.lang.String username, java.lang.String password)` Creates a new SshSession instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addSshListener(SshListener listener)` Add Ssh event listener.
    `void` | `connect()` Establishes connection with SSH server and performs login.
    `void` | `connect(int timeout)` Establishes connection with SSH server and performs login
    `void` | `disconnect()` Disconnects from SSH server.
    `java.lang.String` | `getCharacterSet()` Gets the character set
    `java.lang.String` | `getCommandTerminator()` Gets terminator used when sending data to SSH server.
    `boolean` | `getDebug()` Checks if debugging is enabled.
    `java.io.PrintStream` | `getDebugStream()` Gets PrintStream used in outputting debug information.
    `boolean` | `getEcho()` Returns echo flag.
    `int` | `getPollingInterval()` Gets the polling interval used when checking for completion of commands sent using send or sendWait methods.
    `int` | `getRegexMatchLength()` Gets the number of characters to read from the end of the response buffer when using regular expressions to detect start or end prompts.
    `java.lang.String` | `getShellPrompt()` Gets shell prompt to wait for before sending commands.
    `Ssh` | `getSsh()` Gets underlying `Ssh` instance.
    `void` | `interrupt()` Interrupts any running command waiting for an expected prompt.
    `void` | `removeSshListener(SshListener listener)` Remove Ssh event listener.
    `java.lang.String` | `send(java.lang.String command)` Sends command to SSH host terminated by command terminator.
    `java.lang.String` | `send(java.lang.String command, long timeout)` Sends command to SSH host terminated by command terminator.
    `java.lang.String` | `send(java.lang.String command, java.lang.String prompt)` Deprecated. replaced by `sendWait(String, String)` method
    `void` | `sendNoWait(java.lang.String command)` Sends command to SSH host terminated by command terminator.
    `void` | `sendRaw(java.lang.String data)` Sends data to SSH host without command terminator.
    `java.lang.String` | `sendWait(java.lang.String command, java.lang.String prompt)` Sends command to SSH host terminated by command terminator.
    `java.lang.String` | `sendWait(java.lang.String command, java.lang.String prompt, boolean regex)` Sends command to SSH host terminated by command terminator.
    `java.lang.String` | `sendWait(java.lang.String command, java.lang.String prompt, boolean regex, long timeout)` Sends command to SSH host terminated by command terminator.
    `java.lang.String` | `sendWait(java.lang.String command, java.lang.String prompt, long timeout)` Sends command to SSH host terminated by command terminator.
    `void` | `setCharacterSet(java.lang.String value)` Sets the session character set
    `void` | `setCommandTerminator(java.lang.String value)` Sets terminator used when sending data to SSH server.
    `void` | `setDebug(boolean value)` Enables or disables debugging information.
    `void` | `setDebugStream(java.io.PrintStream stream)` Sets PrintStream used in outputting debug information.
    `void` | `setEcho(boolean value)` Sets server echo flag for the next connection.
    `void` | `setPollingInterval(int value)` Sets the polling interval used when checking for completion of commands sent using send or sendWait methods.
    `void` | `setRegexMatchLength(int value)` Sets the number of characters to read from the end of the response buffer when using regular expressions to detect start or end prompts.
    `void` | `setShellPrompt(java.lang.String string)` Sets shell prompt to wait for before sending commands.
    `void` | `setShellPrompt(java.lang.String value, boolean isRegex)` Sets shell prompt to wait for before sending commands.
    `void` | `setSsh(Ssh value)` Sets the underlying `Ssh` instance.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SshSession

          public SshSession(Ssh ssh,
                            java.lang.String promptPattern,
                            boolean promptPatternIsRegex,
                            int regexMatchLength,
                            java.lang.String endOfLine,
                            java.lang.String characterSet,
                            int pollingInterval)

    - #### SshSession

          public SshSession(SshParameters sshParams,
                            Ssh ssh)

      Creates a new SshSession instance.
      Parameters:
        `sshParams` - - the SshParameters instance.
        `ssh` - - the Ssh instance.
      Throws:
        `SshException` - - the exception instance that is thrown if an error occurs.

    - #### SshSession

          public SshSession(SshParameters sshParams)

      Creates a new SshSession instance.
      Parameters:
        `sshParams` - an SshParameters instance
      Throws:
        `SshException` - if an SSH related exception occurs

    - #### SshSession

          public SshSession(java.lang.String hostname,
                            int port,
                            java.lang.String username,
                            java.lang.String password)

      Creates a new SshSession instance.
      Parameters:
        `hostname` - the hostname of SSH server
        `port` - the port of SSH server
        `username` - the SSH username
        `password` - the SSH password
      Throws:
        `SshException` - if an SSH related exception occurs

    - #### SshSession

          public SshSession(java.lang.String hostname,
                            java.lang.String username,
                            java.lang.String password)

      Creates a new SshSession instance.
      Parameters:
        `hostname` - the hostname of SSH server
        `username` - the SSH username
        `password` - the SSH password
      Throws:
        `SshException` - if an SSH related exception occurs

  - ### Method Detail

    - #### getSsh

          public Ssh getSsh()

      Gets underlying `Ssh` instance.
      Returns:
        underlying `Ssh` instance

    - #### setSsh

          public void setSsh(Ssh value)

      Sets the underlying `Ssh` instance.
      Parameters:
        `value` -

    - #### getShellPrompt

          public java.lang.String getShellPrompt()

      Gets shell prompt to wait for before sending commands. Default value is "$"
      Returns:
        the shell prompt

    - #### setShellPrompt

          public void setShellPrompt(java.lang.String string)

      Sets shell prompt to wait for before sending commands. Default value is "$"
      Parameters:
        `string` - the shell prompt

    - #### setShellPrompt

          public void setShellPrompt(java.lang.String value,
                                     boolean isRegex)

      Sets shell prompt to wait for before sending commands. Default value is "$"
      Parameters:
        `value` - the shell prompt
        `isRegex` - true if shell prompt to match is a regular expression, false otherwise
      See Also:
        `setRegexMatchLength(int)`

    - #### getCommandTerminator

          public java.lang.String getCommandTerminator()

      Gets terminator used when sending data to SSH server. Default value is LF (Line Feed).
      Returns:
        the command terminator

    - #### setCommandTerminator

          public void setCommandTerminator(java.lang.String value)

      Sets terminator used when sending data to SSH server. Default value is LF (Line Feed).
      Parameters:
        `value` - the command terminator

    - #### getEcho

          public boolean getEcho()

      Returns echo flag.
      Returns:
        `true` if server echo is enabled; `false` otherwise

    - #### setEcho

          public void setEcho(boolean value)

      Sets server echo flag for the next connection.
      Parameters:
        `value` - if `true` server echo will be enabled for the next connection.

    - #### getRegexMatchLength

          public int getRegexMatchLength()

      Gets the number of characters to read from the end of the response buffer when using regular expressions to detect start or end prompts. Default value is 20.
      Returns:
        match length

    - #### setRegexMatchLength

          public void setRegexMatchLength(int value)

      Sets the number of characters to read from the end of the response buffer when using regular expressions to detect start or end prompts. Default value is 20.
      Parameters:
        `value` -

    - #### getCharacterSet

          public java.lang.String getCharacterSet()

      Gets the character set
      Returns:
        The character set used by the service

    - #### setCharacterSet

          public void setCharacterSet(java.lang.String value)

      Sets the session character set
      Parameters:
        `value` - the character set

    - #### getPollingInterval

          public int getPollingInterval()

      Gets the polling interval used when checking for completion of commands sent using send or sendWait methods. Default interval is 100ms.
      Returns:
        the polling interval in milliseconds.
      See Also:
        `send(java.lang.String, java.lang.String)`, `sendWait(java.lang.String, java.lang.String, boolean, long)`

    - #### setPollingInterval

          public void setPollingInterval(int value)

      Sets the polling interval used when checking for completion of commands sent using send or sendWait methods. Default interval is 100ms.
      Parameters:
        `value` - the polling interval in milliseconds.
      See Also:
        `send(java.lang.String, java.lang.String)`, `sendWait(java.lang.String, java.lang.String, boolean, long)`

    - #### getDebug

          public boolean getDebug()

      Checks if debugging is enabled. Default is disabled.
      Returns:
        true if debugging enabled, false otherwise

    - #### setDebug

          public void setDebug(boolean value)

      Enables or disables debugging information. In debug enabled mode all data received from SSH server is output to the debug stream. Default is disabled.
      Parameters:
        `value` - true to enable debugging, false to disable
      See Also:
        `setDebugStream(java.io.PrintStream)`

    - #### setDebugStream

          public void setDebugStream(java.io.PrintStream stream)

      Sets PrintStream used in outputting debug information. Default is System.out
      Parameters:
        `stream` - a PrintStream

    - #### getDebugStream

          public java.io.PrintStream getDebugStream()

      Gets PrintStream used in outputting debug information. Default is Sytem.out
      Returns:
        a PrintStream
      See Also:
        `setDebug(boolean)`, `setDebugStream(java.io.PrintStream)`

    - #### addSshListener

          public void addSshListener(SshListener listener)

      Add Ssh event listener.
      Parameters:
        `listener` - a SshListener
      See Also:
        `SshListener`

    - #### removeSshListener

          public void removeSshListener(SshListener listener)

      Remove Ssh event listener.
      Parameters:
        `listener` - a SshListener
      See Also:
        `SshListener`

    - #### connect

          public void connect(int timeout)
                       throws SshException

      Establishes connection with SSH server and performs login
      Parameters:
        `timeout` - timeout in milliseconds for establishing a connection
      Throws:
        `SshException` - if an SSH related exception occurs

    - #### connect

          public void connect()
                       throws SshException

      Establishes connection with SSH server and performs login.
      Throws:
        `SshException` - if an SSH related exception occurs

    - #### disconnect

          public void disconnect()

      Disconnects from SSH server.

    - #### sendRaw

          public void sendRaw(java.lang.String data)
                       throws java.io.IOException

      Sends data to SSH host without command terminator. Does not wait for shell prompt to be returned.
      Parameters:
        `data` - the data to send
      Throws:
        `java.io.IOException` - if an I/O related error occurs
      See Also:
        `setCommandTerminator(java.lang.String)`

    - #### sendNoWait

          public void sendNoWait(java.lang.String command)
                          throws java.io.IOException

      Sends command to SSH host terminated by command terminator. Does not wait for shell prompt to be returned.
      Parameters:
        `command` - the command to send
      Throws:
        `java.io.IOException` - if an I/O related error occurs
      See Also:
        `setCommandTerminator(java.lang.String)`

    - #### sendWait

          public java.lang.String sendWait(java.lang.String command,
                                           java.lang.String prompt,
                                           boolean regex,
                                           long timeout)
                                    throws SshException

      Sends command to SSH host terminated by command terminator. Waits until specified prompt is returned by SSH server buffering response data. If expected prompt is not received within defined timeout then an SshTaskTimeoutException will be thrown.
      Parameters:
        `command` - the command to send
        `prompt` - the prompt to wait for
        `timeout` - the timeout to use when waiting for task end prompt
        `regex` - true if the prompt to match is a regular expression, false otherwise
      Returns:
        the response from telnet server
      Throws:
        `SshException` - if regular expression prompts are used and regular expression is invalid
      See Also:
        `setCommandTerminator(java.lang.String)`, `setRegexMatchLength(int)`, `SshTaskTimeoutException`, `SshException`

    - #### sendWait

          public java.lang.String sendWait(java.lang.String command,
                                           java.lang.String prompt,
                                           long timeout)
                                    throws SshException

      Sends command to SSH host terminated by command terminator. Waits until specified prompt is returned by SSH server buffering response data. If expected prompt is not received within defined timeout then an SshTaskTimeoutException will be thrown.
      Parameters:
        `command` - the command to send
        `prompt` - the prompt to wait for
        `timeout` - the timeout to use when waiting for task end prompt
      Returns:
        the response from telnet server
      Throws:
        `SshException` - if regular expression prompts are used and regular expression is invalid
      See Also:
        `setCommandTerminator(java.lang.String)`, `SshException`, `SshTaskTimeoutException`

    - #### sendWait

          public java.lang.String sendWait(java.lang.String command,
                                           java.lang.String prompt,
                                           boolean regex)
                                    throws SshException

      Sends command to SSH host terminated by command terminator. Waits until specified prompt is returned by SSH server buffering response data. If expected prompt is not received within default timeout of 120 seconds then an SshTaskTimeoutException will be thrown.
      Parameters:
        `command` - the command to send
        `prompt` - the prompt to wait for
        `regex` - true if prompt to match is a regular expression, false otherwise
      Returns:
        the response from telnet server
      Throws:
        `SshException` - if regular expression prompts are used and regular expression is invalid
      See Also:
        `setCommandTerminator(java.lang.String)`, `setRegexMatchLength(int)`, `SshTaskTimeoutException`, `SshException`

    - #### sendWait

          public java.lang.String sendWait(java.lang.String command,
                                           java.lang.String prompt)
                                    throws SshException

      Sends command to SSH host terminated by command terminator. Waits until specified prompt is returned by SSH server buffering response data. If expected prompt is not received within default timeout of 120 seconds then an SshTaskTimeoutException will be thrown.
      Parameters:
        `command` - the command to send
        `prompt` - the prompt to wait for
      Returns:
        the response from telnet server
      Throws:
        `SshException` - if regular expression prompts are used and regular expression is invalid
      See Also:
        `setCommandTerminator(java.lang.String)`, `SshTaskTimeoutException`, `SshException`

    - #### send

          public java.lang.String send(java.lang.String command,
                                       java.lang.String prompt)
                                throws SshException

      Deprecated. replaced by `sendWait(String, String)` method
      Sends command to SSH host terminated by command terminator. Waits until the specified prompt is returned by SSH server buffering response data. If shell prompt is not received within default timeout of 120 seconds then an SshTaskTimeoutException will be thrown.
      Parameters:
        `command` - the command to send
        `prompt` - the prompt to wait for
      Returns:
        the response from SSH server
      Throws:
        `SshException` - if regular expression prompts are used and regular expression is invalid
      See Also:
        `setCommandTerminator(java.lang.String)`, `sendWait(java.lang.String, java.lang.String, boolean, long)`, `SshTaskTimeoutException`

    - #### send

          public java.lang.String send(java.lang.String command,
                                       long timeout)
                                throws SshException

      Sends command to SSH host terminated by command terminator. Waits until the shell prompt is returned by SSH server buffering response data. If shell prompt is not received within defined timeout then an SshTaskTimeoutException will be thrown.
      Parameters:
        `command` - the command to send
        `timeout` - the timeout to use when waiting for shell prompt
      Returns:
        the response from SSH server
      Throws:
        `SshException` - if regular expression prompts are used and regular expression is invalid
      See Also:
        `setShellPrompt(java.lang.String)`, `setCommandTerminator(java.lang.String)`, `SshTaskTimeoutException`

    - #### send

          public java.lang.String send(java.lang.String command)
                                throws SshException

      Sends command to SSH host terminated by command terminator. Waits until the shell prompt is returned by SSH server buffering response data. If shell prompt is not received within default timeout of 120 seconds then an SshTaskTimeoutException will be thrown.
      Parameters:
        `command` - the command to send
      Returns:
        the response from SSH server
      Throws:
        `SshException` - if regular expression prompts are used and regular expression is invalid
      See Also:
        `setShellPrompt(java.lang.String)`, `setCommandTerminator(java.lang.String)`, `SshTaskTimeoutException`

    - #### interrupt

          public void interrupt()

      Interrupts any running command waiting for an expected prompt. This method does not stop the command from running on the server but instead stops the `SshSession` from waiting for a response. You should only use this method in the event you wish to interrupt waiting for a response.

Copyright © JSCAPE LLC. 1999-2021. All Rights Reserved